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

package/dist/remote/admin-mutations.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mutating admin API (item A), mounted behind `requireAuth` at `/api/admin/*`
+ * alongside the read-only endpoints in `admin.ts`.
+ *
+ * Every mutation reuses the canonical tool-dispatch (item D) so there is exactly
+ * one implementation of connection/secret/listener logic. Caller create/delete
+ * uses the programmatic bootstrap (item E).
+ *
+ * Security invariants (same as the read-only side):
+ *   - Secret values are write-only: set via PUT, read back only as booleans.
+ *   - No secret value, AES channel key, or process.env value is ever serialized.
+ *   - After any config mutation, the daemon's live-reload path runs so ingestors
+ *     and routes pick up the change (replacing callboard's restart banner).
+ */
+import express from 'express';
+import { type RemoteServerConfig, type ResolvedRoute } from '../shared/config.js';
+import type { IngestorManager } from './ingestors/index.js';
+export interface AdminMutationDeps {
+    ingestorManager: () => IngestorManager;
+    loadConfig: () => RemoteServerConfig;
+    /** Resolve the live routes for a caller (with secrets) for tool dispatch. */
+    resolveRoutesForCaller: (alias: string) => ResolvedRoute[];
+    /** Re-resolve routes for all active sessions of a caller (live reload). */
+    refreshCaller: (alias: string) => void;
+    /** Register/refresh the authorized peer for a newly-created caller. */
+    reloadPeer: (alias: string) => void;
+    /** Drop the authorized peer + active sessions for a deleted caller. */
+    removePeer: (alias: string) => void;
+    /** Audit-log a sensitive admin mutation (credential issuance). Optional so
+     *  tests can omit it; the daemon wires it to the request audit log. */
+    audit?: (action: string, details?: Record<string, unknown>) => void;
+    /** Endpoint URL to pin in an issued bundle when the request omits one
+     *  (the public tunnel URL, or the daemon's own host:port). */
+    defaultEndpointUrl?: () => string;
+}
+/**
+ * Mount the mutating routes onto an existing admin router.
+ *
+ * The router is already behind `requireAuth` (wired in server.ts), so these
+ * handlers can assume the request is authenticated.
+ */
+export declare function mountAdminMutations(router: express.Router, deps: AdminMutationDeps): void;
+//# sourceMappingURL=admin-mutations.d.ts.map

package/dist/remote/admin-mutations.js

@@ -0,0 +1,321 @@
+/**
+ * Mutating admin API (item A), mounted behind `requireAuth` at `/api/admin/*`
+ * alongside the read-only endpoints in `admin.ts`.
+ *
+ * Every mutation reuses the canonical tool-dispatch (item D) so there is exactly
+ * one implementation of connection/secret/listener logic. Caller create/delete
+ * uses the programmatic bootstrap (item E).
+ *
+ * Security invariants (same as the read-only side):
+ *   - Secret values are write-only: set via PUT, read back only as booleans.
+ *   - No secret value, AES channel key, or process.env value is ever serialized.
+ *   - After any config mutation, the daemon's live-reload path runs so ingestors
+ *     and routes pick up the change (replacing callboard's restart banner).
+ */
+import rateLimit from 'express-rate-limit';
+import { saveRemoteConfig } from '../shared/config.js';
+import { dispatchTool } from './tool-dispatch.js';
+import { createCallerWithKeys, deleteCaller, issueCallerBundle, CALLER_ALIAS_REGEX, } from './caller-bootstrap.js';
+/** Translate a thrown error into an HTTP status + message. */
+function errorStatus(message) {
+    if (/already exists/i.test(message))
+        return 409;
+    if (/not found|unknown caller/i.test(message))
+        return 404;
+    if (/cannot delete|invalid|required/i.test(message))
+        return 400;
+    return 500;
+}
+/**
+ * Mount the mutating routes onto an existing admin router.
+ *
+ * The router is already behind `requireAuth` (wired in server.ts), so these
+ * handlers can assume the request is authenticated.
+ */
+export function mountAdminMutations(router, deps) {
+    /** Build a ToolContext for a caller, wired to live reload on mutation. */
+    function ctx(alias) {
+        return {
+            callerAlias: alias,
+            ingestorManager: deps.ingestorManager(),
+            refreshRoutes: () => deps.refreshCaller(alias),
+        };
+    }
+    /** Guard: 404 unless the caller exists in config. */
+    function callerExists(alias) {
+        return alias in deps.loadConfig().callers;
+    }
+    /** Run a tool and send its result, mapping thrown errors to HTTP codes. */
+    async function runTool(res, alias, tool, input) {
+        if (!callerExists(alias)) {
+            res.status(404).json({ error: `Unknown caller: ${alias}` });
+            return;
+        }
+        try {
+            const result = await dispatchTool(tool, input, deps.resolveRoutesForCaller(alias), ctx(alias));
+            res.json(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(errorStatus(message)).json({ error: message });
+        }
+    }
+    // ── Callers (create / delete) ──────────────────────────────────────────
+    // POST /api/admin/callers  { alias, name?, connections? }
+    router.post('/callers', (req, res) => {
+        const { alias, name, connections } = (req.body ?? {});
+        if (!alias || typeof alias !== 'string') {
+            res.status(400).json({ error: 'alias is required and must be a string' });
+            return;
+        }
+        if (!CALLER_ALIAS_REGEX.test(alias)) {
+            res.status(400).json({
+                error: 'alias must start with a letter or number and contain only letters, numbers, hyphens, and underscores',
+            });
+            return;
+        }
+        try {
+            const result = createCallerWithKeys(alias, {
+                ...(name !== undefined && { name }),
+                ...(Array.isArray(connections) && { connections }),
+            });
+            deps.reloadPeer(alias);
+            res.status(201).json({
+                alias: result.alias,
+                name: result.name,
+                fingerprint: result.fingerprint,
+                publicKeys: result.publicKeys,
+                keysDir: result.keysDir,
+                connections: result.connections,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(errorStatus(message)).json({ error: message });
+        }
+    });
+    // ── Caller credential issuance ─────────────────────────────────────────
+    //
+    // Mint (or rotate) a caller credential bundle and return it ONCE. drawlatch
+    // keeps only the public key, so the private material is unrecoverable after
+    // this response — re-issue to rotate. Rate-limited and audit-logged; the
+    // bundle never carries any connection-secret value (only connection names).
+    const issueLimiter = rateLimit({
+        windowMs: 60 * 1000,
+        max: 10,
+        standardHeaders: true,
+        legacyHeaders: false,
+        message: { error: 'Too many issuance requests. Try again in a minute.' },
+    });
+    // POST /api/admin/callers/:alias/issue  { connections?, endpointUrl?, passphrase?, name? }
+    router.post('/callers/:alias/issue', issueLimiter, (req, res) => {
+        const alias = req.params.alias;
+        if (!CALLER_ALIAS_REGEX.test(alias)) {
+            res.status(400).json({ error: 'Invalid caller alias' });
+            return;
+        }
+        const { connections, endpointUrl, passphrase, name } = (req.body ?? {});
+        if (connections !== undefined &&
+            (!Array.isArray(connections) || !connections.every((c) => typeof c === 'string'))) {
+            res.status(400).json({ error: 'connections must be an array of strings' });
+            return;
+        }
+        if (endpointUrl !== undefined && typeof endpointUrl !== 'string') {
+            res.status(400).json({ error: 'endpointUrl must be a string' });
+            return;
+        }
+        if (passphrase !== undefined && typeof passphrase !== 'string') {
+            res.status(400).json({ error: 'passphrase must be a string' });
+            return;
+        }
+        if (name !== undefined && typeof name !== 'string') {
+            res.status(400).json({ error: 'name must be a string' });
+            return;
+        }
+        const resolvedEndpoint = typeof endpointUrl === 'string' && endpointUrl.trim() !== ''
+            ? endpointUrl.trim()
+            : (deps.defaultEndpointUrl?.() ?? '');
+        const reissue = alias in deps.loadConfig().callers;
+        try {
+            const bundle = issueCallerBundle({
+                alias,
+                endpointUrl: resolvedEndpoint,
+                ...(typeof name === 'string' && { name }),
+                ...(Array.isArray(connections) && { connections }),
+                ...(typeof passphrase === 'string' && passphrase !== '' && { passphrase }),
+            });
+            // Install the fresh public key and invalidate any prior credential's
+            // active sessions (removePeer drops sessions + peer; reloadPeer re-adds
+            // the new key) so a rotation takes effect immediately.
+            deps.removePeer(alias);
+            deps.reloadPeer(alias);
+            deps.audit?.('caller_issue', {
+                caller: alias,
+                reissue,
+                passphraseWrapped: bundle.encryption !== null,
+                connections: bundle.connections,
+                fingerprint: bundle.fingerprint,
+            });
+            res.json(bundle);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(errorStatus(message)).json({ error: message });
+        }
+    });
+    // DELETE /api/admin/callers/:alias
+    router.delete('/callers/:alias', (req, res) => {
+        try {
+            deleteCaller(req.params.alias);
+            deps.removePeer(req.params.alias);
+            res.json({ deleted: req.params.alias });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(errorStatus(message)).json({ error: message });
+        }
+    });
+    // ── Tunnel (cloudflared) config-only toggle ────────────────────────────
+    //
+    // Persists `config.tunnel` to remote.config.json. The daemon reads this flag
+    // at boot to decide whether to spawn cloudflared, so a restart is required
+    // for the change to take effect. The dashboard surfaces this expectation via
+    // a banner when `tunnelEnabled` (intent) disagrees with `tunnelUrl` (runtime).
+    //
+    // PUT /api/admin/tunnel  { enabled: boolean }
+    router.put('/tunnel', (req, res) => {
+        const { enabled } = (req.body ?? {});
+        if (typeof enabled !== 'boolean') {
+            res.status(400).json({ error: 'enabled must be a boolean' });
+            return;
+        }
+        const config = deps.loadConfig();
+        config.tunnel = enabled;
+        saveRemoteConfig(config);
+        res.json({ tunnel: enabled });
+    });
+    // ── Connections (enable / secrets / test) ──────────────────────────────
+    // POST /api/admin/callers/:alias/connections/:connection  { enabled }
+    router.post('/callers/:alias/connections/:connection', async (req, res) => {
+        const { enabled } = (req.body ?? {});
+        if (typeof enabled !== 'boolean') {
+            res.status(400).json({ error: 'enabled must be a boolean' });
+            return;
+        }
+        await runTool(res, req.params.alias, 'set_connection_enabled', {
+            connection: req.params.connection,
+            enabled,
+        });
+    });
+    // PUT /api/admin/callers/:alias/connections/:connection/secrets  { secrets }
+    router.put('/callers/:alias/connections/:connection/secrets', async (req, res) => {
+        const { secrets } = (req.body ?? {});
+        if (!secrets || typeof secrets !== 'object') {
+            res.status(400).json({ error: 'secrets must be an object of name → value' });
+            return;
+        }
+        await runTool(res, req.params.alias, 'set_secrets', { secrets });
+    });
+    // POST /api/admin/callers/:alias/connections/:connection/test
+    router.post('/callers/:alias/connections/:connection/test', async (req, res) => {
+        await runTool(res, req.params.alias, 'test_connection', {
+            connection: req.params.connection,
+        });
+    });
+    // POST /api/admin/callers/:alias/connections/:connection/test-ingestor
+    router.post('/callers/:alias/connections/:connection/test-ingestor', async (req, res) => {
+        await runTool(res, req.params.alias, 'test_ingestor', {
+            connection: req.params.connection,
+        });
+    });
+    // ── Listener / ingestor control ────────────────────────────────────────
+    // POST /api/admin/callers/:alias/connections/:connection/listener/control
+    //   { action: 'start'|'stop'|'restart', instance_id? }
+    router.post('/callers/:alias/connections/:connection/listener/control', async (req, res) => {
+        const { action, instance_id } = (req.body ?? {});
+        if (action !== 'start' && action !== 'stop' && action !== 'restart') {
+            res.status(400).json({ error: "action must be 'start', 'stop', or 'restart'" });
+            return;
+        }
+        await runTool(res, req.params.alias, 'control_listener', {
+            connection: req.params.connection,
+            action,
+            ...(instance_id !== undefined && { instance_id }),
+        });
+    });
+    // GET /api/admin/callers/:alias/listener-configs
+    router.get('/callers/:alias/listener-configs', async (req, res) => {
+        await runTool(res, req.params.alias, 'list_listener_configs', {});
+    });
+    // GET /api/admin/callers/:alias/connections/:connection/listener/params?instance_id=
+    router.get('/callers/:alias/connections/:connection/listener/params', async (req, res) => {
+        const instanceId = req.query.instance_id;
+        await runTool(res, req.params.alias, 'get_listener_params', {
+            connection: req.params.connection,
+            ...(typeof instanceId === 'string' && { instance_id: instanceId }),
+        });
+    });
+    // PUT /api/admin/callers/:alias/connections/:connection/listener/params
+    //   { params, instance_id?, create_instance? }
+    router.put('/callers/:alias/connections/:connection/listener/params', async (req, res) => {
+        const { params, instance_id, create_instance } = (req.body ?? {});
+        if (!params || typeof params !== 'object') {
+            res.status(400).json({ error: 'params must be an object' });
+            return;
+        }
+        await runTool(res, req.params.alias, 'set_listener_params', {
+            connection: req.params.connection,
+            params,
+            ...(instance_id !== undefined && { instance_id }),
+            ...(create_instance !== undefined && { create_instance }),
+        });
+    });
+    // GET /api/admin/callers/:alias/connections/:connection/listener/instances
+    router.get('/callers/:alias/connections/:connection/listener/instances', async (req, res) => {
+        await runTool(res, req.params.alias, 'list_listener_instances', {
+            connection: req.params.connection,
+        });
+    });
+    // POST /api/admin/callers/:alias/connections/:connection/listener/instances
+    //   { instance_id, params? }  — creates a new multi-instance listener
+    router.post('/callers/:alias/connections/:connection/listener/instances', async (req, res) => {
+        const { instance_id, params } = (req.body ?? {});
+        if (!instance_id || typeof instance_id !== 'string') {
+            res.status(400).json({ error: 'instance_id is required and must be a string' });
+            return;
+        }
+        if (!CALLER_ALIAS_REGEX.test(instance_id)) {
+            res.status(400).json({
+                error: 'instance_id must start with a letter or number and contain only letters, numbers, hyphens, and underscores',
+            });
+            return;
+        }
+        await runTool(res, req.params.alias, 'set_listener_params', {
+            connection: req.params.connection,
+            instance_id,
+            params: params ?? {},
+            create_instance: true,
+        });
+    });
+    // DELETE /api/admin/callers/:alias/connections/:connection/listener/instances/:instanceId
+    router.delete('/callers/:alias/connections/:connection/listener/instances/:instanceId', async (req, res) => {
+        await runTool(res, req.params.alias, 'delete_listener_instance', {
+            connection: req.params.connection,
+            instance_id: req.params.instanceId,
+        });
+    });
+    // POST /api/admin/callers/:alias/connections/:connection/listener/resolve-options
+    //   { paramKey }
+    router.post('/callers/:alias/connections/:connection/listener/resolve-options', async (req, res) => {
+        const { paramKey } = (req.body ?? {});
+        if (!paramKey || typeof paramKey !== 'string') {
+            res.status(400).json({ error: 'paramKey is required and must be a string' });
+            return;
+        }
+        await runTool(res, req.params.alias, 'resolve_listener_options', {
+            connection: req.params.connection,
+            paramKey,
+        });
+    });
+}
+//# sourceMappingURL=admin-mutations.js.map

package/dist/remote/admin-types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Response DTOs for the daemon's `/admin/*` API (served at `/api/admin/*`).
+ *
+ * This file is the single source of truth for these shapes. `src/remote/admin.ts`
+ * imports them to annotate its handler responses, and the frontend imports them
+ * (type-only) instead of maintaining a duplicate `shared` mirror.
+ *
+ * Type-only — compiles to nothing.
+ */
+export type { CallerBundleV1, BundleEncryption, CallerSource, } from '../shared/protocol/caller-bundle.js';
+export interface AdminMeta {
+    version: string;
+    port: number;
+    pid: number;
+    startedAt: number;
+    uptimeSec: number;
+    configPath: string;
+    callerKeysDir: string;
+    serverKeysDir: string;
+    envFilePath: string;
+    /** Public URL of the self-managed cloudflared tunnel, when active (item C). */
+    tunnelUrl: string | null;
+    /** Whether the cloudflared tunnel is enabled in config (intent flag).
+     *  Distinct from `tunnelUrl`, which reflects the active runtime state —
+     *  the two disagree until the daemon restarts after a toggle. */
+    tunnelEnabled: boolean;
+}
+export interface AdminIngestorCounts {
+    connected: number;
+    error: number;
+    starting: number;
+    stopped: number;
+}
+export interface AdminHealth {
+    status: 'ok';
+    activeSessions: number;
+    ingestorCounts: AdminIngestorCounts;
+    uptimeSec: number;
+}
+export interface AdminCaller {
+    alias: string;
+    name: string | null;
+    connections: string[];
+    envKeys: string[];
+    fingerprint: string | null;
+    keysDirExists: boolean;
+    /** How this caller's keypair was provisioned (drives the source badge).
+     *  null for callers created before issuance existed. */
+    source: 'local-auto' | 'bundle-issued' | null;
+}
+export type ConnectionCategory = 'ai' | 'developer-tools' | 'gaming' | 'messaging' | 'productivity' | 'social-media';
+export interface AdminConnectionTemplate {
+    alias: string;
+    name: string;
+    description?: string;
+    docsUrl?: string;
+    openApiUrl?: string;
+    stability: 'stable' | 'beta' | 'dev';
+    category: ConnectionCategory;
+    requiredSecrets: string[];
+    optionalSecrets: string[];
+    hasIngestor: boolean;
+    ingestorType?: 'websocket' | 'webhook' | 'poll';
+    hasTestConnection: boolean;
+    hasTestIngestor: boolean;
+    hasListenerConfig: boolean;
+    supportsMultiInstance: boolean;
+    allowedEndpoints: string[];
+}
+/** Per-caller status for EVERY connection template — whether the caller has it
+ *  enabled, and which secrets are configured (booleans only, never values).
+ *  This is the one-call payload the dashboard Connections page renders from. */
+export interface AdminConnectionStatus extends AdminConnectionTemplate {
+    enabled: boolean;
+    requiredSecretsSet: Record<string, boolean>;
+    optionalSecretsSet: Record<string, boolean>;
+}
+export interface AdminSecretRef {
+    name: string;
+    present: boolean;
+}
+export interface AdminListenerInstance {
+    instanceId: string;
+    enabled: boolean;
+    params: Record<string, unknown>;
+}
+export interface AdminCallerConnection {
+    connectionAlias: string;
+    enabled: boolean;
+    isCustom: boolean;
+    requiredSecrets: AdminSecretRef[];
+    optionalSecrets: AdminSecretRef[];
+    hasIngestor: boolean;
+    instances: AdminListenerInstance[];
+}
+export type IngestorState = 'starting' | 'connected' | 'reconnecting' | 'stopped' | 'error';
+export interface AdminIngestor {
+    callerAlias: string;
+    connection: string;
+    instanceId?: string;
+    type: 'websocket' | 'webhook' | 'poll';
+    state: IngestorState;
+    bufferedEvents: number;
+    totalEventsReceived: number;
+    lastEventAt: string | null;
+    error?: string;
+    webhookRegistration?: {
+        registered: boolean;
+        webhookId?: string;
+        error?: string;
+    };
+}
+export interface AdminSession {
+    sessionIdShort: string;
+    callerAlias: string;
+    createdAt: number;
+    lastActivity: number;
+    requestCount: number;
+    windowRequests: number;
+    windowStart: number;
+}
+/** A buffered ingestor event, as surfaced to the dashboard Logs viewer.
+ *  This is the ingested payload from an external service (e.g. a Discord
+ *  message) — never a drawlatch secret. */
+export interface AdminEvent {
+    id: number;
+    idempotencyKey: string;
+    receivedAt: string;
+    receivedAtMs: number;
+    callerAlias: string;
+    source: string;
+    instanceId?: string;
+    eventType: string;
+    data: unknown;
+}
+export interface AdminSecret {
+    callerAlias: string;
+    connection: string;
+    name: string;
+    required: boolean;
+    present: boolean;
+}
+/**
+ * Legacy envelope from the standalone drawlatch-ui backend, which proxied to a
+ * separate daemon process and needed to surface an "offline" state when that
+ * process was unreachable. Retained as a type for the frontend's transition;
+ * same-origin calls in the merged daemon cannot refuse themselves.
+ */
+export interface DaemonOfflineEnvelope {
+    daemon: 'down';
+    error: string;
+}
+//# sourceMappingURL=admin-types.d.ts.map

package/dist/remote/admin-types.js

@@ -0,0 +1,11 @@
+/**
+ * Response DTOs for the daemon's `/admin/*` API (served at `/api/admin/*`).
+ *
+ * This file is the single source of truth for these shapes. `src/remote/admin.ts`
+ * imports them to annotate its handler responses, and the frontend imports them
+ * (type-only) instead of maintaining a duplicate `shared` mirror.
+ *
+ * Type-only — compiles to nothing.
+ */
+export {};
+//# sourceMappingURL=admin-types.js.map

package/dist/remote/admin.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 { type RemoteServerConfig } from '../shared/config.js';
+import { type AdminMutationDeps } from './admin-mutations.js';
+import type { IngestorManager } from './ingestors/index.js';
+import type { SessionSnapshot } from './server.js';
+export interface AdminRouterDeps extends AdminMutationDeps {
+    /** Sanitized session snapshot — see Session in server.ts. */
+    getSessionsSnapshot: () => SessionSnapshot[];
+    /** Late-bound so tests can swap the manager without rebuilding the router. */
+    ingestorManager: () => IngestorManager;
+    /** Late-bound so changes to disk config are picked up between requests. */
+    loadConfig: () => RemoteServerConfig;
+    version: string;
+    port: number;
+    startedAt: number;
+}
+export declare function createAdminRouter(deps: AdminRouterDeps): express.Router;
+//# sourceMappingURL=admin.d.ts.map