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