@wopr-network/defcon 0.2.0

package/dist/engine/ssrf-guard.js

@@ -0,0 +1,159 @@
+import { resolve4, resolve6 } from "node:dns/promises";
+import { isIP } from "node:net";
+const DNS_CACHE_TTL_MS = 60_000;
+/** Exported for test access — clear between tests */
+export const _dnsCache = new Map();
+/**
+ * Returns true if the IP address is in a private/reserved range.
+ * Handles IPv4, IPv6 loopback, link-local, ULA, and IPv6-mapped IPv4.
+ */
+function isPrivateIp(ip) {
+    let normalized = ip;
+    // Handle IPv6-mapped IPv4: ::ffff:A.B.C.D
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(ip);
+    if (mapped) {
+        normalized = mapped[1];
+    }
+    // IPv6 loopback
+    if (normalized === "::1")
+        return true;
+    // IPv6 link-local fe80::/10
+    if (/^fe[89ab][0-9a-f]:/i.test(normalized))
+        return true;
+    // IPv6 ULA fc00::/7 (addresses starting with fc or fd)
+    if (/^f[cd]/i.test(normalized))
+        return true;
+    // IPv4 checks
+    const parts = normalized.split(".").map(Number);
+    if (parts.length === 4 && parts.every((p) => p >= 0 && p <= 255)) {
+        // 10.0.0.0/8
+        if (parts[0] === 10)
+            return true;
+        // 172.16.0.0/12
+        if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
+            return true;
+        // 192.168.0.0/16
+        if (parts[0] === 192 && parts[1] === 168)
+            return true;
+        // 127.0.0.0/8
+        if (parts[0] === 127)
+            return true;
+        // 169.254.0.0/16 (link-local)
+        if (parts[0] === 169 && parts[1] === 254)
+            return true;
+        // 0.0.0.0
+        if (parts.every((p) => p === 0))
+            return true;
+    }
+    return false;
+}
+/**
+ * Parse CIDR notation and check if an IP falls within the range.
+ */
+function ipInCidr(ip, cidr) {
+    const [base, prefixStr] = cidr.split("/");
+    if (!prefixStr)
+        return false;
+    const prefix = parseInt(prefixStr, 10);
+    if (Number.isNaN(prefix))
+        return false;
+    const baseParts = base.split(".").map(Number);
+    const ipParts = ip.split(".").map(Number);
+    if (baseParts.length !== 4 || ipParts.length !== 4)
+        return false;
+    // Validate prefix bounds for IPv4
+    if (prefix < 0 || prefix > 32)
+        return false;
+    const baseNum = (baseParts[0] << 24) | (baseParts[1] << 16) | (baseParts[2] << 8) | baseParts[3];
+    const ipNum = (ipParts[0] << 24) | (ipParts[1] << 16) | (ipParts[2] << 8) | ipParts[3];
+    const mask = prefix === 0 ? 0 : ~0 << (32 - prefix);
+    return (baseNum & mask) === (ipNum & mask);
+}
+/**
+ * Resolve hostname to IP addresses, using cache with 60s TTL.
+ */
+async function resolveHost(hostname) {
+    const cached = _dnsCache.get(hostname);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.ips;
+    }
+    const ips = [];
+    try {
+        const v4 = await resolve4(hostname);
+        ips.push(...v4);
+    }
+    catch {
+        // no A records
+    }
+    try {
+        const v6 = await resolve6(hostname);
+        ips.push(...v6);
+    }
+    catch {
+        // no AAAA records
+    }
+    _dnsCache.set(hostname, { ips, expiresAt: Date.now() + DNS_CACHE_TTL_MS });
+    return ips;
+}
+/**
+ * Parse the DEFCON_GATE_ALLOWLIST env var value into hostname and CIDR entries.
+ */
+function parseAllowlist(allowlist) {
+    const hostnames = new Set();
+    const cidrs = [];
+    for (const entry of allowlist
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)) {
+        if (entry.includes("/")) {
+            cidrs.push(entry);
+        }
+        else {
+            hostnames.add(entry);
+        }
+    }
+    return { hostnames, cidrs };
+}
+/**
+ * Check whether a URL is safe to fetch (not targeting private/reserved addresses).
+ *
+ * @param url - The full HTTPS URL to check
+ * @param allowlistEnv - Optional comma-separated allowlist (pass process.env.DEFCON_GATE_ALLOWLIST)
+ * @returns SsrfCheckResult indicating whether the request should proceed,
+ *          including resolvedIps to use for the actual fetch to avoid DNS rebinding TOCTOU.
+ */
+export async function checkSsrf(url, allowlistEnv) {
+    const parsed = new URL(url);
+    const hostname = parsed.hostname;
+    // Parse allowlist once and reuse both hostnames and cidrs
+    const allowlist = allowlistEnv ? parseAllowlist(allowlistEnv) : null;
+    // If allowlist is set and hostname is explicitly allowed, skip checks
+    if (allowlist?.hostnames.has(hostname)) {
+        return { allowed: true };
+    }
+    // If the hostname is an IP literal, check directly without DNS
+    let ips;
+    if (isIP(hostname)) {
+        ips = [hostname];
+    }
+    else {
+        ips = await resolveHost(hostname);
+        if (ips.length === 0) {
+            return { allowed: false, reason: `SSRF_BLOCKED: ${hostname} is unresolvable` };
+        }
+    }
+    // Check CIDR allowlist if present
+    if (allowlist && allowlist.cidrs.length > 0) {
+        const allIpsAllowed = ips.every((ip) => allowlist.cidrs.some((cidr) => ipInCidr(ip, cidr)));
+        if (allIpsAllowed) {
+            return { allowed: true, resolvedIps: ips };
+        }
+    }
+    // Check all resolved IPs — block if ANY is private
+    for (const ip of ips) {
+        if (isPrivateIp(ip)) {
+            return { allowed: false, reason: `SSRF_BLOCKED: ${hostname} resolves to private/reserved address ${ip}` };
+        }
+    }
+    return { allowed: true, resolvedIps: ips };
+}

package/dist/engine/state-machine.d.ts

@@ -0,0 +1,12 @@
+import type { Logger } from "../logger.js";
+import type { Flow, Transition } from "../repositories/interfaces.js";
+export declare function evaluateCondition(condition: string, context: Record<string, unknown>): boolean;
+export declare function findTransition(flow: Flow, currentState: string, signal: string, context: Record<string, unknown>, skipGateCheck?: boolean, logger?: Logger): Transition | null;
+export interface ValidationError {
+    message: string;
+}
+export declare function validateFlow(flow: Flow): ValidationError[];
+/**
+ * A state is terminal if no transitions use it as fromState.
+ */
+export declare function isTerminal(flow: Flow, state: string): boolean;

package/dist/engine/state-machine.js

@@ -0,0 +1,74 @@
+import { consoleLogger } from "../logger.js";
+import { getHandlebars } from "./handlebars.js";
+const hbs = getHandlebars();
+// ─── Condition Evaluation ───
+export function evaluateCondition(condition, context) {
+    const template = hbs.compile(condition);
+    const result = template(context).trim();
+    return result.length > 0 && result !== "false" && result !== "0";
+}
+// ─── Transition Matching ───
+export function findTransition(flow, currentState, signal, context, skipGateCheck = false, logger = consoleLogger) {
+    const candidates = flow.transitions
+        .filter((t) => t.fromState === currentState && t.trigger === signal)
+        .sort((a, b) => b.priority - a.priority);
+    for (const candidate of candidates) {
+        if (!skipGateCheck && candidate.gateId !== null) {
+            const entity = context.entity;
+            const gatePassed = entity?.gateResults?.some((g) => g.gateId === candidate.gateId && g.passed) ?? false;
+            if (!gatePassed)
+                continue;
+        }
+        try {
+            if (candidate.condition === null || evaluateCondition(candidate.condition, context)) {
+                return candidate;
+            }
+        }
+        catch (err) {
+            logger.warn(`Condition evaluation failed for transition '${candidate.fromState}' -> '${candidate.toState}' (trigger: '${candidate.trigger}'), skipping: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return null;
+}
+export function validateFlow(flow) {
+    const errors = [];
+    const stateNames = new Set(flow.states.map((s) => s.name));
+    if (!stateNames.has(flow.initialState)) {
+        errors.push({ message: `initialState "${flow.initialState}" is not a defined state` });
+    }
+    for (const t of flow.transitions) {
+        if (!stateNames.has(t.fromState)) {
+            errors.push({ message: `Transition from non-existent state "${t.fromState}"` });
+        }
+        if (!stateNames.has(t.toState)) {
+            errors.push({ message: `Transition to non-existent state "${t.toState}"` });
+        }
+    }
+    if (stateNames.has(flow.initialState)) {
+        const reachable = new Set();
+        const queue = [flow.initialState];
+        while (queue.length > 0) {
+            const current = queue.pop();
+            if (reachable.has(current))
+                continue;
+            reachable.add(current);
+            for (const t of flow.transitions) {
+                if (t.fromState === current && stateNames.has(t.toState) && !reachable.has(t.toState)) {
+                    queue.push(t.toState);
+                }
+            }
+        }
+        for (const name of stateNames) {
+            if (!reachable.has(name)) {
+                errors.push({ message: `State "${name}" is unreachable from initialState` });
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * A state is terminal if no transitions use it as fromState.
+ */
+export function isTerminal(flow, state) {
+    return !flow.transitions.some((t) => t.fromState === state);
+}

package/dist/execution/active-runner.d.ts

@@ -0,0 +1,45 @@
+import type { Engine } from "../engine/engine.js";
+import type { Logger } from "../logger.js";
+import type { IEntityRepository, IFlowRepository, IInvocationRepository } from "../repositories/interfaces.js";
+/** Adapter for AI model providers (Anthropic, OpenAI, etc.). */
+export interface IAIProviderAdapter {
+    /** Send a prompt to an AI model and return the response content. */
+    invoke(prompt: string, config: {
+        model: string;
+    }): Promise<{
+        content: string;
+    }>;
+}
+export interface ActiveRunnerDeps {
+    engine: Engine;
+    aiAdapter: IAIProviderAdapter;
+    invocationRepo: IInvocationRepository;
+    entityRepo: IEntityRepository;
+    flowRepo: IFlowRepository;
+    modelTierMap?: Record<string, string>;
+    logger?: Logger;
+}
+export interface ActiveRunnerRunOptions {
+    pollIntervalMs?: number;
+    once?: boolean;
+    flowName?: string;
+    signal?: AbortSignal;
+}
+export declare class ActiveRunner {
+    private engine;
+    private aiAdapter;
+    private invocationRepo;
+    private entityRepo;
+    private flowRepo;
+    private modelTierMap;
+    private logger;
+    constructor(deps: ActiveRunnerDeps);
+    run(options?: ActiveRunnerRunOptions): Promise<void>;
+    private pollOnce;
+    private processInvocation;
+    private resolveModel;
+    parseResponse(content: string): {
+        signal: string;
+        artifacts: Record<string, unknown>;
+    } | null;
+}

package/dist/execution/active-runner.js

@@ -0,0 +1,165 @@
+import { consoleLogger } from "../logger.js";
+const DEFAULT_MODEL_TIER_MAP = {
+    opus: "claude-opus-4-6",
+    sonnet: "claude-sonnet-4-6",
+    haiku: "claude-haiku-4-5-20251001",
+};
+const DEFAULT_MODEL = "claude-sonnet-4-6";
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+export class ActiveRunner {
+    engine;
+    aiAdapter;
+    invocationRepo;
+    entityRepo;
+    flowRepo;
+    modelTierMap;
+    logger;
+    constructor(deps) {
+        this.engine = deps.engine;
+        this.aiAdapter = deps.aiAdapter;
+        this.invocationRepo = deps.invocationRepo;
+        this.entityRepo = deps.entityRepo;
+        this.flowRepo = deps.flowRepo;
+        this.modelTierMap = deps.modelTierMap ?? DEFAULT_MODEL_TIER_MAP;
+        this.logger = deps.logger ?? consoleLogger;
+    }
+    async run(options = {}) {
+        const { pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, once = false, flowName, signal } = options;
+        let flowId;
+        if (flowName) {
+            const flow = await this.flowRepo.getByName(flowName);
+            if (!flow)
+                throw new Error(`Flow "${flowName}" not found`);
+            flowId = flow.id;
+        }
+        while (true) {
+            if (signal?.aborted)
+                break;
+            const processed = await this.pollOnce(flowId, signal);
+            if (once)
+                break;
+            if (!processed) {
+                await sleep(pollIntervalMs, signal);
+            }
+        }
+    }
+    async pollOnce(flowId, signal) {
+        const candidates = await this.invocationRepo.findUnclaimedActive(flowId);
+        if (candidates.length === 0)
+            return false;
+        for (const invocation of candidates) {
+            const claimed = await this.invocationRepo.claim(invocation.id, "active-runner");
+            if (!claimed)
+                continue;
+            await this.processInvocation(claimed, signal);
+            return true;
+        }
+        return false;
+    }
+    async processInvocation(invocation, signal) {
+        const model = await this.resolveModel(invocation);
+        let content;
+        try {
+            const response = await this.aiAdapter.invoke(invocation.prompt, { model });
+            content = response.content;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await this.invocationRepo.fail(invocation.id, message);
+            return;
+        }
+        const parsed = this.parseResponse(content);
+        if (!parsed) {
+            await this.invocationRepo.fail(invocation.id, "No SIGNAL found in AI response");
+            return;
+        }
+        // Complete the current invocation BEFORE calling processSignal so the
+        // concurrency check inside the engine doesn't count it as still-active.
+        try {
+            await this.invocationRepo.complete(invocation.id, parsed.signal, parsed.artifacts);
+        }
+        catch (err) {
+            this.logger.error(`[active-runner] complete() failed for invocation ${invocation.id} before processSignal:`, err);
+            try {
+                await this.invocationRepo.releaseClaim(invocation.id);
+            }
+            catch (releaseErr) {
+                this.logger.error("[active-runner] releaseClaim failed:", releaseErr);
+            }
+            return;
+        }
+        const MAX_PROCESS_SIGNAL_RETRIES = 3;
+        let result;
+        try {
+            result = await this.engine.processSignal(invocation.entityId, parsed.signal, parsed.artifacts, invocation.id);
+        }
+        catch (err) {
+            this.logger.error(`[active-runner] processSignal failed for entity ${invocation.entityId}:`, err);
+            // processSignal failed after we already completed the invocation. Track retry count
+            // via context to prevent infinite re-queue loops on persistent errors.
+            const retryCount = invocation.context?.retryCount ?? 0;
+            if (retryCount >= MAX_PROCESS_SIGNAL_RETRIES) {
+                this.logger.error(`[active-runner] entity ${invocation.entityId} exceeded max processSignal retries (${MAX_PROCESS_SIGNAL_RETRIES}), marking as stuck`);
+                await this.entityRepo.updateArtifacts(invocation.entityId, { stuck: true, stuckAt: new Date().toISOString() });
+                return;
+            }
+            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, { ...(invocation.context ?? {}), retryCount: retryCount + 1 });
+            return;
+        }
+        // Gate timed out — re-queue after backoff instead of failing.
+        // Create a replacement unclaimed invocation so the entity can be reclaimed
+        // on the next poll cycle after the backoff wait.
+        if (result.gated && result.gateTimedOut) {
+            const retryAfterMs = 30000;
+            this.logger.info(`[active-runner] gate timed out for entity ${invocation.entityId}, re-queuing after ${retryAfterMs}ms`);
+            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, invocation.context ?? undefined);
+            await sleep(retryAfterMs, signal);
+            return;
+        }
+    }
+    async resolveModel(invocation) {
+        const entity = await this.entityRepo.get(invocation.entityId);
+        if (!entity)
+            return DEFAULT_MODEL;
+        const flow = await this.flowRepo.get(entity.flowId);
+        if (!flow)
+            return DEFAULT_MODEL;
+        const state = flow.states.find((s) => s.name === invocation.stage);
+        const tier = state?.modelTier ?? flow.defaultModelTier;
+        if (!tier)
+            return DEFAULT_MODEL;
+        return this.modelTierMap[tier] ?? DEFAULT_MODEL;
+    }
+    parseResponse(content) {
+        const signalMatch = content.match(/^SIGNAL:\s*(.+)$/m);
+        if (!signalMatch)
+            return null;
+        const signal = signalMatch[1].trim();
+        let artifacts = {};
+        const artifactsMatch = content.match(/^ARTIFACTS:\s*\n([\s\S]*)/m);
+        if (artifactsMatch) {
+            try {
+                artifacts = JSON.parse(artifactsMatch[1].trim());
+            }
+            catch {
+                this.logger.warn("[active-runner] Failed to parse ARTIFACTS JSON, using empty object. Raw content:", artifactsMatch[1].trim());
+            }
+        }
+        return { signal, artifacts };
+    }
+}
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/execution/admin-schemas.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod/v4";
+export declare const AdminFlowCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    initialState: z.ZodString;
+    discipline: z.ZodOptional<z.ZodString>;
+    defaultModelTier: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    entitySchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    maxConcurrent: z.ZodOptional<z.ZodNumber>;
+    maxConcurrentPerRepo: z.ZodOptional<z.ZodNumber>;
+    affinityWindowMs: z.ZodOptional<z.ZodNumber>;
+    gateTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    createdBy: z.ZodOptional<z.ZodString>;
+    timeoutPrompt: z.ZodOptional<z.ZodString>;
+    states: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        modelTier: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            passive: "passive";
+            active: "active";
+        }>>;
+        promptTemplate: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const AdminFlowUpdateSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    discipline: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    defaultModelTier: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    maxConcurrent: z.ZodOptional<z.ZodNumber>;
+    maxConcurrentPerRepo: z.ZodOptional<z.ZodNumber>;
+    affinityWindowMs: z.ZodOptional<z.ZodNumber>;
+    gateTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    initialState: z.ZodOptional<z.ZodString>;
+    timeoutPrompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const AdminStateCreateSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+    name: z.ZodString;
+    modelTier: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        passive: "passive";
+        active: "active";
+    }>>;
+    promptTemplate: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const AdminStateUpdateSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+    state_name: z.ZodString;
+    modelTier: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        passive: "passive";
+        active: "active";
+    }>>;
+    promptTemplate: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const AdminTransitionCreateSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+    fromState: z.ZodString;
+    toState: z.ZodString;
+    trigger: z.ZodString;
+    gateName: z.ZodOptional<z.ZodString>;
+    condition: z.ZodOptional<z.ZodString>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    spawnFlow: z.ZodOptional<z.ZodString>;
+    spawnTemplate: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AdminTransitionUpdateSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+    transition_id: z.ZodString;
+    fromState: z.ZodOptional<z.ZodString>;
+    toState: z.ZodOptional<z.ZodString>;
+    trigger: z.ZodOptional<z.ZodString>;
+    gateName: z.ZodOptional<z.ZodString>;
+    condition: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    spawnFlow: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    spawnTemplate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const AdminGateCreateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"command">;
+    command: z.ZodString;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    failurePrompt: z.ZodOptional<z.ZodString>;
+    timeoutPrompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"function">;
+    functionRef: z.ZodString;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    failurePrompt: z.ZodOptional<z.ZodString>;
+    timeoutPrompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"api">;
+    apiConfig: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    failurePrompt: z.ZodOptional<z.ZodString>;
+    timeoutPrompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export declare const AdminGateAttachSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+    transition_id: z.ZodString;
+    gate_name: z.ZodString;
+}, z.core.$strip>;
+export declare const AdminFlowSnapshotSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+}, z.core.$strip>;
+export declare const AdminFlowRestoreSchema: z.ZodObject<{
+    flow_name: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strip>;