|
| 1 | +# Nexus Framework Roadmap |
| 2 | + |
| 3 | +This document outlines the strategic direction and planned improvements for the Nexus Framework. We welcome community contributions to help us achieve these goals. |
| 4 | + |
| 5 | +## 1. OIDC Hardening & Security |
| 6 | + |
| 7 | +**Status:** Partially Implemented |
| 8 | +**Goal:** Enhance the robustness of Identity assertions and caching mechanisms. |
| 9 | + |
| 10 | +**Completed:** |
| 11 | +- `id_token` verification via JWKS (signature, `iss`, `aud`, `exp`, `nonce`). |
| 12 | +- OIDC discovery (in-memory caching). |
| 13 | +- `nonce` generation and validation. |
| 14 | +- **Provider Configuration:** Explicit fields added to `provider_profiles` (`issuer`, `enable_discovery`, `user_info_endpoint`). |
| 15 | +- **Observability:** Metrics added for discovery hits/misses (`oidc_discovery_total`) and verification results (`oidc_verifications_total`). |
| 16 | + |
| 17 | +**Remaining:** |
| 18 | +- **Persistent Caching:** Store JWKS/metadata in DB/Redis with ETag/Last-Modified support to survive restarts and reduce upstream calls. Currently uses in-memory/request-scoped discovery. |
| 19 | +- **UserInfo:** Implement `UserInfo` endpoint fetching and normalization. Field exists in DB but logic is missing. |
| 20 | + |
| 21 | +## 2. Infrastructure Security (Transport Encryption) |
| 22 | + |
| 23 | +**Status:** Planned |
| 24 | +**Goal:** Encrypt internal traffic between `Gateway -> Broker` to satisfy "Encryption in Transit" requirements. |
| 25 | + |
| 26 | +**Strategy:** |
| 27 | +- **Preferred:** Use platform-native mTLS/TLS if available (e.g., AWS App Mesh, Azure Container Apps, Google Cloud Run). |
| 28 | +- **Alternative:** Configure standard TLS 1.3 in the Go `http.Server` (Broker) and `http.Client` (Gateway) using self-signed certs or a private CA. |
| 29 | +- **Note:** A full Service Mesh (Istio/Linkerd) is currently considered overkill for this architecture. |
| 30 | + |
| 31 | +## 3. Resilient Connection Handling |
| 32 | + |
| 33 | +**Status:** Partially Implemented |
| 34 | +**Goal:** Explicitly handle unrecoverable refresh errors to prevent endless retry loops. |
| 35 | + |
| 36 | +**Implementation:** |
| 37 | +- **Broker Logic:** Completed. `RefreshToken` logic detects 4xx errors (e.g., `invalid_grant`) and transitions connection status to `attention`. Returns `409 Conflict` with `error: attention_required`. |
| 38 | +- **Bridge Logic:** Pending. Bridge needs update to recognize `attention_required` error (409) and stop retrying. |
| 39 | + |
| 40 | +## 4. Interactive Authentication Flows |
| 41 | + |
| 42 | +**Status:** Partially Implemented |
| 43 | +**Goal:** Support human-in-the-loop flows for when provider refreshes fail due to MFA or CAPTCHA requirements. |
| 44 | + |
| 45 | +**Implementation Details:** |
| 46 | +1. **Broker Logic:** Completed. Transitions connection status to `attention` on specific errors. |
| 47 | +2. **Bridge Logic:** Pending. Needs to stop retrying and emit `ErrInteractionRequired`. |
| 48 | +3. **Frontend/Notification:** Planned. Enable system to trigger user alerts. |
| 49 | + |
| 50 | +## 5. Architecture: The Sidecar Model |
| 51 | + |
| 52 | +**Status:** Proposed / Long-Term |
| 53 | +**Goal:** Achieve zero-knowledge agent architecture by moving signing logic out of the application process. |
| 54 | + |
| 55 | +**Context:** |
| 56 | +Currently, the `bridge` runs as a library within the Agent's process. If compromised, usage secrets in RAM could be exposed. |
| 57 | + |
| 58 | +**The Solution:** |
| 59 | +Develop `nexus-sidecar`, a standalone proxy service deployed alongside the Agent. |
| 60 | +1. **Traffic Flow:** Agent sends unauthenticated HTTP/gRPC requests to `localhost:sidecar_port`. |
| 61 | +2. **Interception:** The Sidecar intercepts the request. |
| 62 | +3. **Signing:** The Sidecar fetches the credentials from the Gateway/Broker and signs the request. |
| 63 | +4. **Forwarding:** The Sidecar forwards the authenticated request to the upstream Provider. |
| 64 | + |
| 65 | +**Benefits:** |
| 66 | +- **Zero-Knowledge Agent:** Even with RCE, an attacker finds no keys in the Agent's memory. |
| 67 | +- **Polyglot Support:** Any language can use Nexus via simple HTTP requests to localhost. |
| 68 | + |
| 69 | +## 6. Production Hardening: CORS |
| 70 | + |
| 71 | +**Status:** Open |
| 72 | +**Priority:** Low (Staging/Dev only) |
| 73 | +**Date Logged:** 2026-01-27 |
| 74 | + |
| 75 | +**Description:** |
| 76 | +The AllowedOrigins for CORS in `nexus-gateway` (both REST and gRPC) are currently hardcoded to `["https://*", "http://*"]` to unblock staging. |
| 77 | + |
| 78 | +**Required Action:** |
| 79 | +Refactor the CORS configuration to read the allowed origins from an environment variable (e.g., `CORS_ALLOWED_ORIGINS`). This will allow strict enforcement of the frontend domain in production environments without code modification. |
| 80 | + |
| 81 | +## 7. Model Context Protocol (MCP) Adapter |
| 82 | + |
| 83 | +**Status:** Proposed |
| 84 | +**Goal:** Enable Nexus to act as an MCP server or seamlessly integrate with existing MCP adapters, providing AI agents standard, authenticated access to connected data sources. |
| 85 | + |
| 86 | +**Context:** |
| 87 | +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is rapidly becoming the standard for connecting AI models to external tools and datasets. While MCP defines *how* an LLM communicates with a data source, it relies on the underlying system to handle complex authentication flows (like OAuth 2.0). |
| 88 | + |
| 89 | +**The Solution:** |
| 90 | +Develop a `nexus-mcp-adapter` that bridges the gap between MCP's context protocol and Nexus's identity management capabilities. |
| 91 | +1. **Tool Exposure:** Automatically expose APIs connected via Nexus (e.g., Google Drive, GitHub) as standardized MCP Tools or Resources. |
| 92 | +2. **Transparent Authentication:** When an LLM calls an MCP Tool, the adapter uses Nexus (via the Bridge or Sidecar) to securely sign the outbound request with the correct, fresh access token. |
| 93 | +3. **Dynamic Provisioning:** Allow agents to discover available connections and request new OAuth flows dynamically through standard MCP messages. |
| 94 | + |
| 95 | +**Benefits:** |
| 96 | +- Instantly makes any API integrated with Nexus accessible to MCP-compatible LLMs (like Claude Desktop or custom agents). |
| 97 | +- Solves the hardest part of MCP integration: secure, multi-tenant authentication and token lifecycle management. |
0 commit comments