[Upstream PR #249] Orchestration Kernel + External Access Broker

[Peyton-Spencer]

Upstream Reference

PR: nanocoai#249
Status: OPEN (created Feb 15, 11:47 UTC)
Author: Josuedutra
Severity: ARCHITECTURAL OVERHAUL

Summary

Major architectural addition introducing deterministic orchestration state machine and capability-based external access framework.

Components

Orchestration Kernel v0:

• Deterministic state machine: INBOX → TRIAGED → READY → DOING → REVIEW → APPROVAL → DONE
• Task lifecycle management with state transitions
• Optimistic locking for concurrent updates

External Access Broker v0:

• Capability-based external access with L0-L3 security levels
• HMAC-SHA256 request signing (per-group IPC secret)
• Idempotent dispatch with optimistic locking
• Backpressure (max 5 pending ext_calls per group)
• L3 two-man rule (requires 2+ governance approvals from different groups)
• Mandatory expiry for L2/L3 capabilities (7 days)
• Deny-wins precedence in capability checks
• Append-only audit trail

Providers:

• GitHub Provider: 16 actions (repos, PRs, issues, checks, branch protection)
• Cloud Logs Provider: 3 actions (log access, search, export)

Architectural Impact

CRITICAL — This introduces a complete governance framework that could replace/enhance our current multi-agent coordination architecture.

Key Questions:

1. How does this compare to our current IPC/task delegation system?
2. Can we adopt the governance state machine for team coordination?
3. Does the capability-based security model fit our use cases?
4. Should we wait for upstream stabilization or adopt early?

Relevance

VERY HIGH — Directly addresses:

• Multi-agent task coordination (state machine)
• External service access (capability-based security)
• Governance and approval flows (separation of powers)
• Audit trail and compliance

Action Plan

Phase 1: Architecture Review (2-3 days)

• Deep dive into orchestration kernel state machine
• Analyze external access broker capability model
• Compare with existing OmniAura IPC/task delegation architecture
• Identify integration points and conflicts
• Assess security model fit for our use cases

Phase 2: Integration Decision

• Decide: adopt, adapt, or defer
• If adopting: plan migration strategy from current IPC system
• If adapting: identify components to cherry-pick
• If deferring: document reasons and set review timeline

Phase 3: Implementation (if adopting/adapting)

• Implement integration on feature branch
• Update multi-agent coordination to use orchestration kernel
• Migrate external tool access to broker framework
• Add tests for state transitions and capability checks

Phase 4: Validation

• Test with existing agent workflows
• Validate governance flows (L0-L3 security levels)
• Performance testing with backpressure limits
• Security audit of HMAC signing and capability checks

Timeline

• Review: This week (urgent - architectural decision needed)
• Implementation: Next sprint (if adopted)
• Estimated Effort: HIGH (2-3 days review + 5-7 days implementation)

Related Issues

• Issue 🔴 SECURITY: API Key Exfiltration via Bypass Vectors #79 - Security: API Key Exfiltration (capability model could help)
• Existing IPC/task delegation system (/workspace/ipc/*)

Tracking

• Monitor upstream PR for merge status
• Track implementation changes and API evolution
• Check for breaking changes before merge
• Plan merge strategy (likely significant conflicts)

[Peyton-Spencer]

Security Integration: Capability Model Could Address Issue #79

The External Access Broker's capability-based security model directly addresses vulnerabilities in Issue #79 (API Key Exfiltration).

How Capabilities Help

Current Problem (Issue #79):

• API keys exposed via process.env
• Agent can read keys via /proc/self/environ, Read tool, temp files
• All-or-nothing access model

Capability Solution:

// Instead of exposing raw API keys to agent
process.env.GITHUB_TOKEN = "ghp_secret123"  // ❌ Exploitable

// Grant specific capabilities with audit trail
const capability = {
  provider: "github",
  action: "repos.create_issue",
  level: "L1", // Automated approval
  expiry: Date.now() + 3600000,
  scope: { repo: "omniaura/*" }
}

Agent calls:

// Via External Access Broker
await broker.dispatch({
  capability_id: "cap_123",
  action: "repos.create_issue",
  params: { repo: "omniaura/nanoclaw", title: "Bug report" }
})

Broker validates capability, signs request with HMAC, calls GitHub API on behalf of agent. Agent never sees raw token.

Integration with Issue #79 Fixes

Replace:

• Phase 2 Fix feat: Discord reaction approval for plans + share requests #4 ("Selective export")
• Phase 2 Fix feat: add Slack channel support #5 ("Pass secrets via ContainerInput.secrets")

With:

• External Access Broker for all external service access
• Capability grants instead of env vars
• Audit trail for all API calls

Architecture Comparison

Approach	Security	Auditability	Complexity
Current (env vars)	Low (exposed to agent)	None	Low
Issue #79 Fixes	Medium (hardened env)	Partial (Bash hooks)	Medium
Capability Model	High (broker-mediated)	Full (audit log)	High

Recommendation

Consider adopting Orchestration Kernel + External Access Broker instead of implementing Issue #79's env hardening fixes.

Trade-offs:

• ✅ Better security (agent never sees secrets)
• ✅ Full audit trail
• ✅ Granular permissions (per-action, per-resource)
• ✅ Expiry and revocation built-in
• ❌ Higher implementation complexity
• ❌ Requires architectural changes to external tool access
• ❌ Upstream PR not merged yet (may evolve)

Timeline:

• Issue 🔴 SECURITY: API Key Exfiltration via Bypass Vectors #79 fixes: 8-12 hours
• Capability integration: 2-3 days (per Issue [Upstream PR #249] Orchestration Kernel + External Access Broker #86 estimate)

---

Action Items:

1. Review Orchestration Kernel architecture (Phase 1 of Issue [Upstream PR #249] Orchestration Kernel + External Access Broker #86)
2. Prototype capability-based GitHub/Anthropic API access
3. Compare security posture vs Issue 🔴 SECURITY: API Key Exfiltration via Bypass Vectors #79 fixes
4. Decide: quick fix (🔴 SECURITY: API Key Exfiltration via Bypass Vectors #79) or architectural shift ([Upstream PR #249] Orchestration Kernel + External Access Broker #86)

cc @Peyton-Spencer - Architectural decision needed