groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T4S1/research/security_implications_analysis.md

@@ -0,0 +1,245 @@
+# Security Implications: Exposing `isDescendantOf` as Public API
+
+## Executive Summary
+
+This document analyzes the security implications of making the `isDescendantOf()` method public in the Groundswell workflow engine.
+
+**Key Finding**: Groundswell is a library (not a service) with **NO built-in authentication/authorization**. Making `isDescendantOf()` public would expose workflow topology information that applications may not want to reveal.
+
+---
+
+## 1. Current Security Posture
+
+### 1.1 Groundswell is a Library
+
+```typescript
+// Groundswell has NO built-in security:
+// - No authentication
+// - No authorization
+// - No access control
+// - No audit logging
+
+// Security is the APPLICATION's responsibility
+```
+
+### 1.2 Information Already Exposed
+
+The `Workflow` class already exposes hierarchy information:
+
+```typescript
+export class Workflow {
+  public parent: Workflow | null = null;      // Parent reference
+  public children: Workflow[] = [];            // All children
+  public getNode(): WorkflowNode {             // Full node with tree
+    return this.node;  // Includes parent, children, logs, events, state
+  }
+}
+```
+
+**Risk Assessment**: Any code with a `Workflow` reference can already traverse the entire tree via `parent` and `children` properties.
+
+---
+
+## 2. What `isDescendantOf` Reveals
+
+### 2.1 Direct Information
+
+```typescript
+public isDescendantOf(ancestor: Workflow): boolean
+```
+
+**Returns**: `true` if this workflow is a descendant of the given ancestor.
+
+**Information Exposed**:
+- Whether a workflow is in the hierarchy tree of another
+- The existence of parent-child relationships
+- (Already exposed via public `parent` property)
+
+### 2.2 Comparison with Existing Public APIs
+
+| API | Information Exposed | Access Required |
+|-----|-------------------|-----------------|
+| `workflow.parent` | Direct parent reference | Any `Workflow` reference |
+| `workflow.children` | All immediate children | Any `Workflow` reference |
+| `workflow.getNode()` | Full tree structure | Any `Workflow` reference |
+| `isDescendantOf()` | Boolean relationship check | Any `Workflow` reference |
+
+**Conclusion**: `isDescendantOf()` does NOT expose any new information beyond what's already available via `parent` and `children` properties.
+
+---
+
+## 3. Security Considerations
+
+### 3.1 Information Disclosure Risk
+
+**Risk Level**: **MEDIUM** (not higher than current exposure)
+
+**Rationale**:
+- `parent` and `children` are already public
+- `getNode()` exposes the entire tree
+- `isDescendantOf()` only provides a convenience method
+
+**Attack Vector**: An attacker could already traverse the tree:
+```typescript
+// Current attack (without isDescendantOf):
+function isDescendant(current: Workflow, ancestor: Workflow): boolean {
+  let node = current;
+  while (node.parent) {
+    if (node.parent === ancestor) return true;
+    node = node.parent;
+  }
+  return false;
+}
+
+// With isDescendantOf (convenience, not new capability):
+const isDesc = current.isDescendantOf(ancestor);
+```
+
+### 3.2 Topology Extraction Risk
+
+**Scenario**: Extracting workflow topology for business intelligence.
+
+**Current State**: Already possible via:
+```typescript
+function extractTopology(workflow: Workflow) {
+  const tree: Record<string, string[]> = {};
+
+  function traverse(node: Workflow, path: string[]) {
+    tree[node.node.name] = [...path];
+    for (const child of node.children) {
+      traverse(child, [...path, node.node.name]);
+    }
+  }
+
+  // Find root and traverse
+  let root = workflow;
+  while (root.parent) root = root.parent;
+  traverse(root, []);
+
+  return tree;
+}
+```
+
+**With `isDescendantOf()`**: No additional risk.
+
+---
+
+## 4. Comparison with Introspection Tools
+
+Groundswell already provides introspection tools that expose MORE information:
+
+```typescript
+// Already PUBLIC tools:
+export const INTROSPECTION_TOOLS = [
+  inspectCurrentNodeTool,       // Current position
+  readAncestorChainTool,        // ALL ancestors
+  listSiblingsChildrenTool,     // Siblings and children
+  inspectPriorOutputsTool,      // Previous execution data
+  inspectCacheStatusTool,       // Cache state
+  requestSpawnWorkflowTool,     // Create children
+];
+```
+
+**Tool Output Example** (`read_ancestor_chain`):
+```typescript
+interface AncestorChainResult {
+  ancestors: AncestorInfo[];  // Full ancestor chain with names, statuses
+  totalDepth: number;
+}
+```
+
+**Security Implication**: Introspection tools already expose MORE detailed hierarchy information than `isDescendantOf()` would.
+
+---
+
+## 5. Industry Practices
+
+### 5.1 Major Workflow Systems
+
+| System | Ancestry API | Access Control | Notes |
+|--------|--------------|----------------|-------|
+| **Airflow** | No public API | RBAC (DAG-level) | Exposes DAG structure |
+| **Temporal** | No public API | mTLS + API keys | Does NOT expose hierarchy |
+| **Prefect** | No public API | Token auth | Does NOT expose hierarchy |
+| **Groundswell** | Private | None (library) | `parent`/`children` public |
+
+**Finding**: Industry keeps ancestry checking internal OR implements access control.
+
+### 5.2 Groundswell's Approach
+
+Groundswell's design:
+- Library-based security (application's responsibility)
+- Already exposes `parent` and `children`
+- Already provides introspection tools
+- No built-in access control
+
+---
+
+## 6. Recommendations
+
+### 6.1 Security Recommendation: **APPROVE with Safeguards**
+
+**Rationale**:
+1. `isDescendantOf()` does NOT expose new information
+2. `parent` and `children` are already public
+3. Introspection tools already expose MORE information
+4. Provides convenience and improves API ergonomics
+
+### 6.2 Safeguards to Implement
+
+1. **Documentation**: Clearly document that topology is exposed
+```typescript
+/**
+ * Check if this workflow is a descendant of the given ancestor workflow.
+ *
+ * @warning This method reveals workflow hierarchy information. If your
+ * application exposes workflows via an API, ensure you implement proper
+ * access control to prevent unauthorized topology discovery.
+ *
+ * @example
+ * ```typescript
+ * if (child.isDescendantOf(root)) {
+ *   console.log('Child is in root hierarchy');
+ * }
+ * ```
+ */
+public isDescendantOf(ancestor: Workflow): boolean
+```
+
+2. **Add to Security Guide**: Update `/plan/.../introspection-security-guide.md`
+   - Document that `isDescendantOf()` exposes hierarchy
+   - Recommend application-level access control
+
+3. **Provide Safe Alternative**: Consider a filtered version
+```typescript
+/**
+ * Get relationship information without exposing full topology.
+ * Returns null if workflows are unrelated.
+ */
+public getRelationship(other: Workflow): {
+  isAncestor: boolean;
+  isDescendant: boolean;
+  distance: number;  // Depth difference
+} | null
+```
+
+---
+
+## 7. Summary
+
+| Aspect | Finding |
+|--------|---------|
+| **New Information Exposed** | None (beyond current `parent`/`children`) |
+| **Security Risk** | MEDIUM (same as current exposure) |
+| **Industry Alignment** | Acceptable (with documentation) |
+| **Application Responsibility** | Implement access control if exposing via API |
+| **Recommendation** | APPROVE with safeguards |
+
+---
+
+## References
+
+- **Security Guide**: `/plan/001_d3bb02af4886/docs/research/general/introspection-security-guide.md`
+- **Workflow Class**: `/src/core/workflow.ts:162-180`
+- **Introspection Tools**: `/src/tools/introspection.ts`
+- **External Research**: `external_workflow_engines_research.md`