Descope Connection Hub: Complete Architecture Summary
Status: SUPERSEDED — see DESCOPE_CONNECTION_HUB_REFINED.md (CANONICAL)
Date: July 17, 2026
Version: v1.1 (Summary)
Canonical Path: docs/architecture/CONNECTION_ARCHITECTURE.md
Executive Summary
We've architected Descope as the universal connection hub for IntegrateWise with clear ownership boundaries and zero vendor lock-in:
- Descope owns: Identity, credentials, OAuth, token lifecycle
- IntegrateWise owns: Operations, continuity, governance, memory
- Provider Management MCP: Abstraction layer enabling pluggable identity providers
This is not Descope-specific architecture. It's a provider-neutral pattern that happens to use Descope for V0.
Why This Matters
| Problem | Solution | Benefit |
|---|---|---|
| Vendor lock-in to Descope | Provider Management MCP abstraction | Swap identity provider without rewriting code |
| Business logic couples to Descope | Provider-neutral Connection model | Hermes, Fabric, providers never see Descope concepts |
| Token sprawl (stored everywhere) | authorizationRef bridge only | Zero credentials in IW state |
| Manual credential refresh | Descope owns token lifecycle | Automatic refresh, no background jobs |
| Unclear ownership | Clear responsibility table | Zero confusion about who owns what |
Architecture Comparison
V1.0 (Tightly Coupled)
Hermes → Capability → Descope Adapter → Descope → Credentials
(business logic sees Descope)
Problem: Hard to replace Descope later.
V1.1 (Abstracted) ✅
Hermes → Capability → Provider Management MCP → Descope Adapter → Descope
(business logic provider-agnostic) ↓
Credentials (temporary)
Benefit: Replace Descope Adapter with Auth0 Adapter without touching Hermes.
Key Design Decisions
1. Ownership Table
| Layer | Owner | Reason |
|-------|-------|--------|
| Authentication | Descope | Specialized service, managed |
| Authorization | Descope | OAuth flows, user consent |
| Tokens | Descope | Security, encryption, compliance |
| Refresh logic | Descope | Token expiry, auto-refresh |
| Connection metadata | IW | Operational context (last used, policies) |
| Continuity | IW | Audit trail, learning, context |
| Capability routing | MCP Pool | Provider dispatch, versioning |
| Governance | IW | Authority checks, approval chains |
| Memory | IW | Spine, operational state |
2. Connection Abstraction
interface Connection {
id: string; // "github-primary"
provider: string; // "github" (provider-neutral)
authorizationRef: string; // "descope:github:auth_123" (credential bridge)
status: string; // "connected" (operational metadata)
capabilities: string[]; // ["repo.read", "repo.write"]
owner: string; // user_id
tenantId: string;
createdAt: Date;
lastUsedAt: Date;
}
Principle: Spine stores only provider-neutral fields. authorizationRef is the only link to Descope.
3. Runtime Execution
Hermes calls Capability Fabric with authorizationRef
↓
Fabric routes to Provider Management MCP
↓
MCP routes to Descope Adapter: resolve(authorizationRef)
↓
Adapter calls Descope Management API: get_connection(ref)
↓
Descope returns credentials (auto-refreshed if expired)
↓
Adapter passes credentials to Provider (GitHub, Salesforce, etc.)
↓
Provider executes
↓
Credentials destroyed (never persisted)
↓
Result returned to Hermes
No token storage. No credential persistence. Ever.
Files Delivered
Architecture Documentation
- DESCOPE_CONNECTION_HUB.md (v1.0) — Initial design
- DESCOPE_CONNECTION_HUB_REFINED.md (v1.1) — Refined with Provider Management MCP
- DESCOPE_ARCHITECTURE_SUMMARY.md (this file) — Executive overview
Implementation
- services/gateway/src/descope-callback.ts (207 lines) — OAuth callback handler
- Validates CSRF state
- Exchanges code with Descope Management API
- Returns authorizationRef to frontend
- Health check endpoint
Memory
- v0_memories/user/MEMORY.md — Updated with refined architecture + next steps
Implementation Roadmap (6 Phases)
| Phase | Task | Timeline | Owner |
|---|---|---|---|
| 1 | Create ProviderManagementMCP interface | 2 days | Architecture |
| 2 | Wire gateway routing for /api/v1/provider-management/callback | 1 day | Gateway |
| 3 | Implement Descope Adapter (V0) | 3 days | Adapter |
| 4 | Create Spine Connection model + migrations | 2 days | Spine |
| 5 | Update all providers to use Provider Management MCP | 5 days | Providers |
| 6 | End-to-end testing + monitoring | 3 days | QA |
Total: 2-3 weeks
V0 Ready: After Phase 4 (Connection model in Spine)
Production Ready: After Phase 6
Future-Proofing
This architecture enables future migrations:
Scenario: Migrate from Descope to Auth0
// Today: Descope Adapter
class DescopeAdapter implements ProviderAdapter { ... }
// Tomorrow: Auth0 Adapter (drop-in replacement)
class Auth0Adapter implements ProviderAdapter {
async resolveCredentials(authorizationRef: string): Promise<Credentials> {
// Call Auth0 Management API instead
const connection = await auth0Client.getConnection(authorizationRef);
return connection.credentials;
}
}
// Hermes doesn't care which adapter is active
// Spine doesn't change
// Providers don't care
Effort to migrate: ~1 week for Auth0 Adapter + testing. Zero changes to business logic.
Security Properties
✅ Credential isolation: No tokens in IW state (D1, Spine, cache, localStorage)
✅ Temporary credentials: Fetched on-demand, destroyed after use
✅ Server-side only: Descope Management Key never exposed to frontend
✅ Token refresh: Handled by Descope (no manual refresh logic)
✅ Audit trail: All operations recorded in Spine + Descope
✅ Governance enforced: INTEGRATION_CONNECT and INTEGRATION_USE authorities
✅ CSRF protection: State validation on OAuth callbacks
✅ Error handling: Graceful degradation, no credential leaks in logs
Ownership Boundaries (Locked)
Descope Manages
- User login/SSO/MFA
- OAuth consent flows
- Access token generation + signing
- Refresh token generation + storage
- Token expiry + auto-refresh
- Authorization references (authorizationRef generation)
IntegrateWise Manages
- Connection metadata (status, lastValidatedAt, health)
- Capability routing + selection
- Governance (authority checks, approval chains)
- Operational memory (Spine: entities, relationships, timeline)
- Audit trail + continuity
- Provider dispatch + execution
Nobody Manages (Avoided)
- ❌ Token storage in IW state
- ❌ Manual token refresh logic
- ❌ Credential caching
- ❌ Vendor-specific business logic in Hermes
Next Actions
Immediate (This Week)
- ✅ Finalize ProviderManagementMCP interface contract
- ✅ Design Descope Adapter implementation
- ✅ Spike gateway routing changes
- ✅ Plan Spine Connection model schema
Week 1-2 (Implementation)
- Create Provider Management MCP interface
- Implement Descope Adapter
- Wire gateway callback routing
- Add Spine Connection model + migrations
- Update providers (GitHub, Salesforce, Slack, etc.)
Week 3 (Testing + Deployment)
- End-to-end testing (connect → execute → health check)
- Monitoring + alerting
- Deploy to staging
- Performance benchmarks
- Documentation + runbooks
References
- Descope Docs: https://docs.descope.com/build/outbound-connections/
- MCP Adapter:
services/mcp-connector/src/providers/descope/ - Gateway:
services/gateway/src/ - Spine:
apps/web/src/data/knowledge.ts - Continuity Bridge:
services/mcp-connector/src/continuity-bridge.ts
Decision Log
Why Provider Management MCP?
To avoid Descope concepts leaking into Hermes, Capability Fabric, and provider implementations. One adapter change shouldn't ripple through the entire system.
Why authorizationRef only?
To force separation of concerns. IW never sees actual credentials. Only references to Descope-managed credentials.
Why temporary credentials?
To minimize blast radius if credentials are compromised. In-memory, ephemeral credentials mean no stored secrets.
Why Descope for V0?
It's a battle-tested identity platform with OAuth, SSO, MFA, SCIM. Reduces time-to-market. Architecture doesn't lock us in.
Q&A
Q: What if Descope goes down?
A: Fallback behavior: Provider Management MCP can temporarily cache credentials for 15 minutes, enabling partial availability. Full functionality resumes when Descope is back.
Q: What if we migrate to Auth0?
A: Create Auth0Adapter implementing ProviderAdapter interface. Plug it in. Update env var. Zero code changes elsewhere.
Q: What about token refresh?
A: Descope handles it. We call resolve(authorizationRef) which returns fresh credentials. No background jobs, no manual refresh logic.
Q: What if a user disconnects in Descope?
A: Descope callback to /api/v1/provider-management/connection-revoked updates Spine Connection.status = "disconnected". User sees "Reconnect" button.
Q: How do we audit who executed what?
A: Every execution recorded in Spine (operator, timestamp, capability, result). Plus Descope audit log for who authorized.
Locked Decisions
This architecture is locked. Any changes require written approval from:
- Architecture Lead
- Security Lead
- Product Lead
Changes locked until: August 15, 2026
Version History
| Version | Date | Changes |
|---|---|---|
| v1.0 | July 17, 2026 | Initial architecture |
| v1.1 | July 17, 2026 | Refined with Provider Management MCP abstraction |
| v1.1 (current) | July 17, 2026 | This summary document |
Status: Ready for Phase 1 implementation
Owner: Integration Architecture Team
Approval: Pending