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

package/dist/remote/admin.js

@@ -0,0 +1,317 @@
+/**
+ * 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,
+                source: caller.source ?? null,
+            };
+        });
+        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,121 @@
+/**
+ * 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 { type RemoteServerConfig } from '../shared/config.js';
+import { type SerializedPublicKeys } from '../shared/crypto/keys.js';
+import type { CallerBundleV1 } from '../shared/protocol/caller-bundle.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 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 declare function createCallerWithKeys(alias: string, opts?: CreateCallerOptions): CreateCallerResult;
+export interface IssueCallerOptions {
+    alias: string;
+    /** Human-readable display name (preserved on re-issue; defaults to alias). */
+    name?: string;
+    /** Connections to authorize. Preserved on re-issue; clones `default` for new. */
+    connections?: string[];
+    /** drawlatch endpoint this caller identity is scoped to (pinned in the bundle). */
+    endpointUrl: string;
+    /** When set, `caller.*.priv` is scrypt+AES-256-GCM wrapped in the bundle. */
+    passphrase?: string;
+    /** ISO timestamp override (tests). Defaults to now. */
+    createdAt?: string;
+}
+/**
+ * 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 declare function issueCallerBundle(opts: IssueCallerOptions): CallerBundleV1;
+export interface IssueLocalCallerOptions {
+    /** Caller alias (default 'callboard-local'). */
+    alias?: string;
+    /** Human-readable display name. */
+    name?: string;
+    /** Connections to authorize (defaults to cloning `default`). */
+    connections?: string[];
+    /** callboard's keys dir (the directory that holds `callers/` and `server/`). */
+    keysDir: string;
+}
+export interface IssueLocalCallerResult {
+    alias: string;
+    fingerprint: string;
+    /** The caller key directory written inside callboard's keys dir. */
+    callerKeysDir: string;
+    connections: string[];
+}
+/**
+ * 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 declare function issueLocalCaller(opts: IssueLocalCallerOptions): IssueLocalCallerResult;
+/**
+ * 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 declare function maybeIssueLocalCaller(): IssueLocalCallerResult | null;
+/**
+ * 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;
+/** Re-exported for callers that want to introspect config without re-importing. */
+export type { RemoteServerConfig };
+//# sourceMappingURL=caller-bootstrap.d.ts.map