groundswell 0.0.2 → 1.0.0

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

@@ -1,245 +0,0 @@
-# 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`