{"slug":"connectors/ROUND_2_AUTH_NODE_INVENTORY","title":"Round 2 — Auth Node Inventory","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/ROUND_2_AUTH_NODE_INVENTORY.mdx","bytes":5952,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Date:** 2026-07-29  \n**Status:** Code exists; production keys needed\n\n---\n\n## Current Auth Architecture\n\n### What Exists in Code\n\n| Module                     | Location                                                        | Status                       |\n| -------------------------- | --------------------------------------------------------------- | ---------------------------- |\n| Clerk JWT verification     | `services/gateway/src/clerk-auth.ts`                            | ✅ Implemented               |\n| Clerk principal mapping    | `services/gateway/src/clerk-auth.ts` → `mapClerkPrincipal()`    | ✅ Implemented               |\n| Customer Zero detection    | `packages/types/src/customer-zero.ts` → `isCustomerZeroEmail()` | ✅ Implemented               |\n| Descope adapter (legacy)   | `services/gateway/src/descope-auth.ts`                          | ⚠️ Legacy, still in codebase |\n| OAuth authorization server | `services/mcp-connector/src/lib/oauth-auth-server.ts`           | ✅ Implemented               |\n| OAuth scope enforcement    | `services/mcp-connector/src/lib/oauth-scopes.ts`                | ✅ Implemented               |\n| Gateway auth middleware    | `services/gateway/src/index.ts:1928-1970`                       | ✅ Implemented               |\n| MCP Connector auth         | `services/mcp-connector/src/lib/access-auth.ts`                 | ✅ Implemented               |\n\n### Auth Flow (Current)\n\n```\nClient → Gateway\n  → Bearer token extracted\n  → Try Clerk verification (primary)\n    → verifyClerkToken(bearerToken, clerkSecretKey)\n    → mapClerkPrincipal(clerkPrincipal, { surface })\n    → VerifiedPrincipal: { userId, email, roles, tenantId, surface }\n  → If Clerk fails → Try Descope (legacy fallback)\n  → If both fail → 401\n  → Tenant resolution from VerifiedPrincipal.tenantId\n  → Trusted headers overwritten by Gateway\n  → Forward to downstream service\n```\n\n### VerifiedPrincipal Shape\n\n```typescript\ninterface VerifiedPrincipal {\n  userId: string;\n  email?: string;\n  name?: string;\n  roles: readonly string[];\n  tenantId: string;\n  organizationId?: string;\n  surface: \"integratewise-web\" | \"integratewise-api\" | \"iw-mcp\";\n  isAgent?: boolean;\n  agentId?: string;\n  delegationRef?: string;\n  issuedAt?: number;\n  expiresAt?: number;\n}\n```\n\n### Surface Mapping\n\n| Surface             | Trigger                            | Used by                 |\n| ------------------- | ---------------------------------- | ----------------------- |\n| `integratewise-web` | Frontend browser session           | Gateway → all services  |\n| `integratewise-api` | External API client                | Gateway → MCP Connector |\n| `iw-mcp`            | MCP client (Cursor, ChatGPT, etc.) | Gateway → MCP Connector |\n\n---\n\n## Single Shared Auth Node: What Needs to Happen\n\n### P0 #10 Requirements\n\nThe single shared auth node must handle:\n\n1. **Identity:** Clerk JWT verification → `VerifiedPrincipal`\n2. **Authorization:** OAuth scope enforcement → tool-level access control\n3. **Tenant resolution:** `VerifiedPrincipal.tenantId` → all downstream services\n4. **Workspace resolution:** Clerk org_id → workspace projections\n5. **Marketplace installation identity:** Installation JWT → tenant + scopes\n\n### What's Missing\n\n| Item                            | Status                          | Action                                                            |\n| ------------------------------- | ------------------------------- | ----------------------------------------------------------------- |\n| Clerk production secret key     | ❌ Not in `.env`                | Set `CLERK_SECRET_KEY` in Cloudflare Workers secrets              |\n| Clerk publishable key           | ❌ Not in `.env`                | Set `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` in Pages environment      |\n| Clerk JWKS endpoint             | ✅ Hardcoded in `clerk-auth.ts` | Verify it resolves after DNS is live                              |\n| Descope removal                 | ⚠️ Legacy code still present    | Remove `descope-auth.ts` after Clerk is verified in production    |\n| `GATEWAY_CONNECTOR_AUTH_SECRET` | ❌ Not set                      | Generate shared secret for Gateway→MCP Connector auth             |\n| `OAUTH_PRIVATE_KEY`             | ❌ Not set                      | Generate RSA keypair for OAuth JWT signing                        |\n| Tenant resolution middleware    | ✅ Exists in Gateway            | Verify it works with real Clerk org data                          |\n| Installation identity           | ⚠️ Partial                      | Marketplace installation JWT verification needs real verification |\n\n### Code Changes Needed\n\n1. **Remove Descope fallback** after Clerk production verification\n2. **Add tenant resolution middleware** that works with Clerk org_id\n3. **Wire `GATEWAY_CONNECTOR_AUTH_SECRET`** for Gateway→MCP Connector auth\n4. **Add OAuth keypair generation** for production JWT signing\n\n---\n\n## Production Clerk Setup Checklist\n\n1. Create Clerk application at dashboard.clerk.com\n2. Configure social connections (Google, GitHub, email)\n3. Create organizations feature\n4. Create `iw-customer-zero` organization\n5. Add `@integratewise.ai` domain to organization\n6. Generate production API keys:\n   - Secret key → `CLERK_SECRET_KEY` (Cloudflare Workers secret)\n   - Publishable key → `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` (Pages env)\n7. Configure JWT templates if needed (org_id, org_role, tenant_id)\n8. Verify JWKS endpoint: `https://integratewise.ai/clerk/.well-known/jwks.json`\n\n---\n\n## Verification\n\nAfter production Clerk is configured:\n\n```bash\n# Test Clerk JWT verification\ncurl -H \"Authorization: Bearer <valid-clerk-jwt>\" \\\n  https://gateway.integratewise.ai/api/v1/workspace/discovery\n\n# Expected: 200 with WorkspaceDiscoveryResponse\n# If 401: Clerk keys not configured or JWT invalid\n```\n"}