@usejarvis/brain 0.1.0

package/src/workflows/triggers/webhook.ts

@@ -0,0 +1,191 @@
+/**
+ * WebhookManager — manages inbound webhook endpoints for workflow triggers
+ *
+ * Each workflow can have a unique webhook path. Requests are validated
+ * against an optional HMAC-SHA256 secret (X-Jarvis-Signature header).
+ */
+
+// ── Types ──
+
+export type WebhookRoute = {
+  workflowId: string;
+  path: string;
+  secret: string | null;
+  registeredAt: number;
+};
+
+export type WebhookTriggerCallback = (workflowId: string, data: Record<string, unknown>) => void;
+
+// ── Helpers ──
+
+/**
+ * Compute an HMAC-SHA256 hex digest for the given body using the Web Crypto API.
+ * Works in both Bun and browser contexts.
+ */
+async function computeHmac(secret: string, body: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+
+  const signature = await crypto.subtle.sign('HMAC', keyMaterial, encoder.encode(body));
+  return Array.from(new Uint8Array(signature))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+// ── WebhookManager ──
+
+export class WebhookManager {
+  private routes: Map<string, WebhookRoute> = new Map();
+  private triggerCallback: WebhookTriggerCallback | null = null;
+
+  /**
+   * Register a workflow webhook.
+   * @returns the webhook path (e.g. "/webhooks/wf_abc123")
+   */
+  register(workflowId: string, secret?: string): string {
+    const path = `/webhooks/${workflowId}`;
+
+    this.routes.set(workflowId, {
+      workflowId,
+      path,
+      secret: secret ?? null,
+      registeredAt: Date.now(),
+    });
+
+    console.log(`[WebhookManager] Registered webhook for workflow "${workflowId}" at ${path}`);
+    return path;
+  }
+
+  /**
+   * Remove a workflow's webhook registration.
+   */
+  unregister(workflowId: string): void {
+    if (this.routes.delete(workflowId)) {
+      console.log(`[WebhookManager] Unregistered webhook for workflow "${workflowId}"`);
+    }
+  }
+
+  /**
+   * Handle an inbound webhook request.
+   *
+   * Validates the optional HMAC secret, extracts the JSON body, and fires
+   * the trigger callback. Returns a proper HTTP Response.
+   */
+  async handleRequest(workflowId: string, req: Request): Promise<Response> {
+    const route = this.routes.get(workflowId);
+
+    if (!route) {
+      return new Response(JSON.stringify({ error: 'Webhook not found' }), {
+        status: 404,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // Read raw body once
+    let rawBody: string;
+    try {
+      rawBody = await req.text();
+    } catch {
+      return new Response(JSON.stringify({ error: 'Failed to read request body' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // Validate HMAC signature if a secret is configured
+    if (route.secret) {
+      const signature = req.headers.get('x-jarvis-signature') ?? req.headers.get('X-Jarvis-Signature');
+
+      if (!signature) {
+        return new Response(JSON.stringify({ error: 'Missing signature header' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      const expected = await computeHmac(route.secret, rawBody);
+
+      // Constant-time comparison to prevent timing attacks
+      if (!timingSafeEqual(signature.toLowerCase(), expected.toLowerCase())) {
+        return new Response(JSON.stringify({ error: 'Invalid signature' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    }
+
+    // Parse body
+    let data: Record<string, unknown> = {};
+    if (rawBody.trim()) {
+      try {
+        const parsed = JSON.parse(rawBody);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          data = parsed as Record<string, unknown>;
+        } else {
+          data = { body: parsed };
+        }
+      } catch {
+        // Not JSON — pass as raw string
+        data = { body: rawBody };
+      }
+    }
+
+    // Enrich with request metadata
+    data._webhook = {
+      method: req.method,
+      url: req.url,
+      timestamp: Date.now(),
+      headers: Object.fromEntries(req.headers.entries()),
+    };
+
+    // Fire callback (non-blocking)
+    if (this.triggerCallback) {
+      try {
+        this.triggerCallback(workflowId, data);
+      } catch (err) {
+        console.error(`[WebhookManager] Trigger callback threw for workflow "${workflowId}":`, err);
+      }
+    } else {
+      console.warn(`[WebhookManager] No trigger callback set; webhook fired for "${workflowId}" but nothing will execute`);
+    }
+
+    return new Response(JSON.stringify({ ok: true, workflowId }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  /**
+   * Set the callback invoked when a webhook fires successfully.
+   */
+  setTriggerCallback(cb: WebhookTriggerCallback): void {
+    this.triggerCallback = cb;
+  }
+
+  /**
+   * Returns the map of all registered routes keyed by workflowId.
+   */
+  getRoutes(): Map<string, WebhookRoute> {
+    return new Map(this.routes);
+  }
+}
+
+// ── Utilities ──
+
+/**
+ * Constant-time string comparison to prevent timing-based secret leakage.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}

package/src/workflows/types.ts

@@ -0,0 +1,133 @@
+/**
+ * Workflow Automation Engine — Core Types
+ */
+
+// ── Node System ──
+
+export type NodeCategory = 'trigger' | 'action' | 'logic' | 'transform' | 'error';
+
+export type NodeConfigFieldType = 'string' | 'number' | 'boolean' | 'select' | 'code' | 'template' | 'json';
+
+export type NodeConfigField = {
+  type: NodeConfigFieldType;
+  label: string;
+  description?: string;
+  required: boolean;
+  default?: unknown;
+  options?: { label: string; value: string }[];
+  placeholder?: string;
+};
+
+// ── Workflow Definition (serialized graph) ──
+
+export type WorkflowDefinition = {
+  nodes: WorkflowNode[];
+  edges: WorkflowEdge[];
+  settings: WorkflowSettings;
+};
+
+export type WorkflowNode = {
+  id: string;
+  type: string;                          // e.g., 'trigger.cron', 'action.http_request'
+  label: string;
+  position: { x: number; y: number };
+  config: Record<string, unknown>;
+  retryPolicy?: RetryPolicy;
+  fallbackNodeId?: string;
+};
+
+export type WorkflowEdge = {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string;                 // e.g., 'true', 'false', 'default', 'error'
+  condition?: string;
+  label?: string;
+};
+
+export type WorkflowSettings = {
+  maxRetries: number;                    // default 3
+  retryDelayMs: number;                  // default 5000
+  timeoutMs: number;                     // default 300000 (5 min)
+  parallelism: 'sequential' | 'parallel';
+  onError: 'stop' | 'continue' | 'self_heal';
+};
+
+export type RetryPolicy = {
+  maxRetries: number;
+  delayMs: number;
+  backoff: 'fixed' | 'exponential';
+};
+
+export const DEFAULT_WORKFLOW_SETTINGS: WorkflowSettings = {
+  maxRetries: 3,
+  retryDelayMs: 5000,
+  timeoutMs: 300_000,
+  parallelism: 'parallel',
+  onError: 'stop',
+};
+
+// ── Execution ──
+
+export type ExecutionStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'paused';
+export type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'waiting';
+
+// ── Vault Types ──
+
+export type Workflow = {
+  id: string;
+  name: string;
+  description: string;
+  enabled: boolean;
+  authority_level: number;
+  authority_approved: boolean;
+  approved_at: number | null;
+  approved_by: string | null;
+  tags: string[];
+  current_version: number;
+  execution_count: number;
+  last_executed_at: number | null;
+  last_success_at: number | null;
+  last_failure_at: number | null;
+  created_at: number;
+  updated_at: number;
+};
+
+export type WorkflowVersion = {
+  id: string;
+  workflow_id: string;
+  version: number;
+  definition: WorkflowDefinition;
+  changelog: string | null;
+  created_by: string;
+  created_at: number;
+};
+
+export type WorkflowExecution = {
+  id: string;
+  workflow_id: string;
+  version: number;
+  trigger_type: string;
+  trigger_data: Record<string, unknown> | null;
+  status: ExecutionStatus;
+  variables: Record<string, unknown>;
+  error_message: string | null;
+  started_at: number;
+  completed_at: number | null;
+  duration_ms: number | null;
+};
+
+export type WorkflowStepResult = {
+  id: string;
+  execution_id: string;
+  node_id: string;
+  node_type: string;
+  status: StepStatus;
+  input_data: Record<string, unknown> | null;
+  output_data: Record<string, unknown> | null;
+  error_message: string | null;
+  retry_count: number;
+  started_at: number | null;
+  completed_at: number | null;
+  duration_ms: number | null;
+};

package/src/workflows/variables.ts

@@ -0,0 +1,72 @@
+/**
+ * Variable Scope — execution-scoped + persistent
+ *
+ * Execution-scoped variables live in memory for the current run.
+ * Persistent variables survive across executions (stored in vault).
+ */
+
+import * as vault from '../vault/workflows.ts';
+import type { VariableScopeInterface } from './nodes/registry.ts';
+
+export class VariableScope implements VariableScopeInterface {
+  private executionVars: Map<string, unknown> = new Map();
+  private workflowId: string;
+
+  constructor(workflowId: string, initialVars?: Record<string, unknown>) {
+    this.workflowId = workflowId;
+    if (initialVars) {
+      for (const [k, v] of Object.entries(initialVars)) {
+        this.executionVars.set(k, v);
+      }
+    }
+  }
+
+  /**
+   * Get variable — checks execution scope first, then persistent vault.
+   */
+  get(key: string): unknown {
+    if (this.executionVars.has(key)) {
+      return this.executionVars.get(key);
+    }
+    return vault.getVariable(this.workflowId, key);
+  }
+
+  /**
+   * Set execution-scoped variable (in-memory only).
+   */
+  set(key: string, value: unknown): void {
+    this.executionVars.set(key, value);
+  }
+
+  /**
+   * Set persistent variable (survives across executions).
+   */
+  setPersistent(key: string, value: unknown): void {
+    vault.setVariable(this.workflowId, key, value);
+    // Also set in execution scope for current run
+    this.executionVars.set(key, value);
+  }
+
+  /**
+   * Get all variables (execution + persistent merged).
+   */
+  toObject(): Record<string, unknown> {
+    const persistent = vault.getVariables(this.workflowId);
+    const result: Record<string, unknown> = { ...persistent };
+    for (const [k, v] of this.executionVars) {
+      result[k] = v;
+    }
+    return result;
+  }
+
+  /**
+   * Serialize execution variables for storage.
+   */
+  serialize(): string {
+    const obj: Record<string, unknown> = {};
+    for (const [k, v] of this.executionVars) {
+      obj[k] = v;
+    }
+    return JSON.stringify(obj);
+  }
+}