@tiledesk/tiledesk-server 3.3.5 → 3.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/app.js +7 -0
- package/deploynew.sh +7 -1
- package/docs/activities-client.md +27 -0
- package/docs/mcp-oauth2-it.md +279 -0
- package/docs/mcp-oauth2.md +279 -0
- package/docs/numeric-input-validation.md +91 -0
- package/docs/superpowers/plans/2026-11-10-mcp-oauth2-server-it.md +155 -0
- package/docs/superpowers/plans/2026-11-10-mcp-oauth2-server.md +155 -0
- package/docs/superpowers/plans/2026-11-10-mcp-oauth2-tybot-it.md +63 -0
- package/docs/superpowers/plans/2026-11-10-mcp-oauth2-tybot.md +63 -0
- package/docs/superpowers/specs/2026-11-10-mcp-oauth2-design-it.md +207 -0
- package/docs/superpowers/specs/2026-11-10-mcp-oauth2-design.md +207 -0
- package/jobs.js +15 -0
- package/models/mcpOAuthConnection.js +131 -0
- package/models/request.js +8 -0
- package/package.json +1 -1
- package/pubmodules/activities/activityMessageUtil.js +137 -0
- package/pubmodules/activities/models/activity.js +2 -0
- package/pubmodules/activities/routes/activity.js +39 -11
- package/pubmodules/activities/test/execution-filter.test.js +133 -0
- package/pubmodules/activities/test/execution-messages.test.js +158 -0
- package/pubmodules/canned/cannedResponseRoute.js +6 -9
- package/pubmodules/events/eventRoute.js +6 -9
- package/pubmodules/executions-publisher/index.js +457 -0
- package/pubmodules/executions-publisher/test/audit-consumer.test.js +384 -0
- package/pubmodules/executions-publisher/test/executions-publisher.test.js +204 -0
- package/pubmodules/pubModulesManager.js +12 -0
- package/routes/answered.js +7 -3
- package/routes/campaigns.js +7 -3
- package/routes/department.js +14 -3
- package/routes/executions-refire.js +148 -0
- package/routes/faq.js +6 -14
- package/routes/filesp.js +9 -4
- package/routes/kb.js +40 -15
- package/routes/lead.js +23 -28
- package/routes/logs.js +8 -1
- package/routes/mcp.js +11 -8
- package/routes/mcpOAuth.js +133 -0
- package/routes/mcpOAuthCallback.js +75 -0
- package/routes/message.js +3 -1
- package/routes/messagesRoot.js +5 -18
- package/routes/project.js +57 -12
- package/routes/project_user.js +21 -4
- package/routes/property.js +18 -20
- package/routes/request.js +36 -45
- package/routes/roles.js +8 -18
- package/routes/segment.js +8 -18
- package/routes/subscription.js +4 -5
- package/routes/tag.js +6 -9
- package/routes/unanswered.js +7 -3
- package/routes/user-request.js +29 -34
- package/routes/webhook.js +120 -54
- package/services/mcpOAuthDiscovery.js +248 -0
- package/services/mcpOAuthGoogleScopes.js +55 -0
- package/services/mcpOAuthService.js +732 -0
- package/services/mcpService.js +111 -15
- package/services/requestService.js +4 -2
- package/services/webhookService.js +4 -2
- package/test/executions-refire.test.js +362 -0
- package/test/kbRoute.js +4 -7
- package/test/mcpOAuthDiscovery.test.js +331 -0
- package/test/mcpOAuthGoogleScopes.test.js +25 -0
- package/test/mcpOAuthRoute.test.js +455 -0
- package/test/mcpOAuthService.test.js +693 -0
- package/test/mcpOAuthUtils.test.js +348 -0
- package/test/mcpServiceOAuth.test.js +267 -0
- package/test/numericInput.js +137 -0
- package/test/requestRoute.js +57 -0
- package/test/webhookConversationRoute.js +51 -0
- package/utils/logRedactor.js +4 -2
- package/utils/mcpOAuthCrypto.js +69 -0
- package/utils/mcpOAuthPkce.js +20 -0
- package/utils/numericInput.js +200 -0
- package/utils/outboundUrlGuard.js +131 -0
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# MCP OAuth2 — tiledesk-server Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
4
|
+
|
|
5
|
+
**Goal:** tiledesk-server acts as OAuth2 client for MCP servers (MCP-spec discovery + DCR, Google preset, manual), stores tokens encrypted, refreshes them lazily, serves a valid access token to the chatbot, and exposes a token-protected refresh API for the scheduler.
|
|
6
|
+
|
|
7
|
+
**Architecture:** Pure helpers (`mcpOAuthCrypto.js`, `mcpOAuthPkce.js`, `outboundUrlGuard.js`) → `mcpOAuthDiscovery.js` (RFC 9728 / 8414 / 7591) → `mcpOAuthService.js` (authorize, callback, refresh with Redis lock, revoke) over the `mcp_oauth_connections` model → admin/bot routes in `routes/mcpOAuth.js`, public callback in `routes/mcpOAuthCallback.js`, scheduler API in `routes/webhook.js` → `mcpService` injects the bearer.
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Node 18/Express, Mongoose, axios, Node `crypto` / `dns`, TdCache (Redis), mocha + chai-http + nock (test MongoDB + Redis).
|
|
10
|
+
|
|
11
|
+
**Spec:** `docs/superpowers/specs/2026-11-10-mcp-oauth2-design.md`
|
|
12
|
+
|
|
13
|
+
## Global Constraints
|
|
14
|
+
|
|
15
|
+
- Branch `features-2611/oauth2-mcp` (checked out). One commit per task. Never push.
|
|
16
|
+
- No new npm dependency (axios + Node built-ins only).
|
|
17
|
+
- Feature gate: every OAuth route answers 503 `"MCP OAuth is not available on this installation"` when `MCP_OAUTH_ENCRYPTION_KEY` is unset or not 32 bytes after base64 decoding. `mode: 'google'` additionally needs `MCP_OAUTH_GOOGLE_CLIENT_ID` and `_SECRET`; the scheduler API needs `MCP_OAUTH_REFRESH_TOKEN`. No default secrets.
|
|
18
|
+
- Tokens and client secrets are never in the `mcp` integration, never in a response except `access_token` on the bot-only token endpoint, never in logs.
|
|
19
|
+
- Redirect URI = `(MCP_OAUTH_REDIRECT_BASE_URL || API_URL)` without trailing slash + `/oauth2/mcp/callback`.
|
|
20
|
+
- Redis keys: `mcp_oauth:state:<state>` (TTL 600 s), `mcp_oauth:refresh_lock:<connection_id>` (TTL 30 s). `REFRESH_WINDOW_S = 300`.
|
|
21
|
+
- Outbound HTTP to user-influenced URLs goes through `outboundUrlGuard` (https, no private/loopback after DNS resolution, `maxRedirects: 0`, timeout 10000, `maxContentLength` 1 MB) unless `MCP_OAUTH_ALLOW_INSECURE_URLS=true`. Google endpoints are constants and skip the guard.
|
|
22
|
+
- Token endpoint requests are `application/x-www-form-urlencoded`; client auth `client_secret_basic` → `Authorization: Basic base64(urlencode(id):urlencode(secret))`, `client_secret_post` → `client_id` + `client_secret` in the body, `none` → `client_id` only.
|
|
23
|
+
- Errors returned by the service carry `.status` and `.code` (`needs_reauth`, `not_configured`, `bad_request`, `not_found`, `provider_error`); routes map them with `res.status(err.status || 500).send({ success: false, error: err.message, code: err.code })`.
|
|
24
|
+
- Tests: `NODE_ENV=test ./node_modules/.bin/mocha <files> --timeout 60000 --exit` with test MongoDB/Redis up (docker `tiledesk-test-mongo`, `tiledesk-test-redis`). nock every provider and MCP call; tests set `MCP_OAUTH_ALLOW_INSECURE_URLS=true` only where they target `http://` hosts, and one test keeps it unset to exercise the guard. `nock.isDone()` asserted per test.
|
|
25
|
+
|
|
26
|
+
## Review Focus
|
|
27
|
+
|
|
28
|
+
1. A connection of project A can never be read, refreshed, used or deleted from project B (token endpoint, management API, `oauth.connection_id` in `POST /mcp/servers`).
|
|
29
|
+
2. An admin JWT on `GET …/connections/:id/token` → 403; a bot JWT of the same project → 200.
|
|
30
|
+
3. Two concurrent token requests on an expiring token → exactly one call to the provider token endpoint, both callers get the new token.
|
|
31
|
+
4. A refresh response without `refresh_token` keeps the old one; with one, it replaces it (rotation).
|
|
32
|
+
5. State reuse: calling the callback twice with the same `state` → second call 400, no second code exchange.
|
|
33
|
+
6. `invalid_grant` on refresh → `needs_reauth`, token endpoint then answers 409 without calling the provider again.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
### Task 1: crypto, PKCE, URL guard, model
|
|
38
|
+
|
|
39
|
+
**Files:**
|
|
40
|
+
- Create: `utils/mcpOAuthCrypto.js`, `utils/mcpOAuthPkce.js`, `utils/outboundUrlGuard.js`, `models/mcpOAuthConnection.js`
|
|
41
|
+
- Modify: `utils/logRedactor.js` (`SENSITIVE_KEY_RE` and the JSON-string replace gain `access_token|refresh_token|code_verifier|client_secret`; key `code` only in the key regex)
|
|
42
|
+
- Test: `test/mcpOAuthUtils.test.js`
|
|
43
|
+
|
|
44
|
+
**Interfaces:**
|
|
45
|
+
- `mcpOAuthCrypto`: `isConfigured() → boolean`, `encrypt(plain) → 'v1:…'`, `decrypt(enc) → string` (throws on tamper / wrong key), `null`/`undefined` pass through.
|
|
46
|
+
- `mcpOAuthPkce`: `randomState() → base64url(32 bytes)`, `createVerifier() → 64-char base64url`, `challengeOf(verifier) → base64url(sha256)`.
|
|
47
|
+
- `outboundUrlGuard`: `assertAllowed(url) → Promise<URL>` (throws `.status = 400`, message `"URL not allowed: <reason>"`), `httpOptions() → { maxRedirects: 0, timeout: 10000, maxContentLength: 1048576 }`.
|
|
48
|
+
- Model fields exactly as spec §4, `timestamps: true`, unique index `{ id_project: 1, server_url: 1 }`, `toPublic(doc)` static returning the spec §9 shape.
|
|
49
|
+
|
|
50
|
+
- [ ] **Step 1: Failing tests.** Encrypt/decrypt round-trip; flipping one ciphertext byte throws; key unset → `isConfigured()` false; challenge of RFC 7636 appendix B verifier `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk` = `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM`; guard rejects `http://x`, `https://127.0.0.1`, `https://10.0.0.1`, `https://169.254.169.254`, `https://[::1]`, `https://[fd00::1]`, a hostname that resolves to `192.168.1.1` (stub `dns.promises.lookup`), accepts a public address; guard with `MCP_OAUTH_ALLOW_INSECURE_URLS=true` accepts `http://localhost:3232`; `redactValue({ access_token: 'x', refresh_token: 'y', code_verifier: 'z' })` all `[REDACTED]`; `toPublic` has no `*_enc`.
|
|
51
|
+
- [ ] **Step 2: Run** `… test/mcpOAuthUtils.test.js` → fail.
|
|
52
|
+
- [ ] **Step 3: Implement.** AES-256-GCM, 12-byte IV. Guard: `dns.promises.lookup(host, { all: true })`, reject if **any** address is in 0.0.0.0/8, 10/8, 100.64/10, 127/8, 169.254/16, 172.16/12, 192.168/16, ::, ::1, fc00::/7, fe80::/10, IPv4-mapped forms of those.
|
|
53
|
+
- [ ] **Step 4: Run** the file plus `test/logRedactor*.js` if present → pass.
|
|
54
|
+
- [ ] **Step 5: Commit** — `feat(mcp-oauth): encryption, PKCE, outbound URL guard and connection model`.
|
|
55
|
+
|
|
56
|
+
### Task 2: discovery and dynamic client registration
|
|
57
|
+
|
|
58
|
+
**Files:**
|
|
59
|
+
- Create: `services/mcpOAuthDiscovery.js`
|
|
60
|
+
- Test: `test/mcpOAuthDiscovery.test.js`
|
|
61
|
+
|
|
62
|
+
**Interfaces:**
|
|
63
|
+
- `discover(serverUrl) → { resource, issuer, authorization_endpoint, token_endpoint, revocation_endpoint?, registration_endpoint?, scopes_supported?, token_endpoint_auth_methods_supported? }` per spec §6.1. Errors 400 `"This MCP server does not require OAuth"`, 400 `"OAuth metadata not found for <url>"`, 400 `"Authorization server does not support PKCE S256"`, 502 on network failure.
|
|
64
|
+
- `register(metadata, redirectUri) → { client_id, client_secret?, token_endpoint_auth_method }` per spec §6.2; 400 when `registration_endpoint` is missing.
|
|
65
|
+
- Pure `wellKnownUrls(baseUrl, suffix) → string[]` (path-inserted first, then root).
|
|
66
|
+
|
|
67
|
+
- [ ] **Step 1: Failing tests (nock).** 401 with `WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"` → that URL is fetched; without the header → path-inserted then root well-known tried in order; issuer `https://auth.example.com/tenant1` → `https://auth.example.com/.well-known/oauth-authorization-server/tenant1` first, then `/.well-known/openid-configuration` fallback; 200 on unauthenticated initialize → "does not require OAuth"; `code_challenge_methods_supported: ['plain']` → PKCE error; DCR body asserted (redirect URI, grant types, `client_name: 'Tiledesk'`); a metadata URL pointing to `https://10.0.0.5/…` rejected by the guard (insecure flag unset).
|
|
68
|
+
- [ ] **Step 2: Run** → fail.
|
|
69
|
+
- [ ] **Step 3: Implement** with axios + `outboundUrlGuard` before every request. The initialize body is the same JSON-RPC `initialize` as `mcpService.sendInitializeRequest` (protocol `2025-03-26`), headers `Accept: application/json, text/event-stream`. Parse `WWW-Authenticate` with a small regex for `resource_metadata="…"`.
|
|
70
|
+
- [ ] **Step 4: Run** → pass.
|
|
71
|
+
- [ ] **Step 5: Commit** — `feat(mcp-oauth): MCP authorization discovery and dynamic client registration`.
|
|
72
|
+
|
|
73
|
+
### Task 3: OAuth service — authorize, callback, refresh, revoke
|
|
74
|
+
|
|
75
|
+
**Files:**
|
|
76
|
+
- Create: `services/mcpOAuthService.js`
|
|
77
|
+
- Modify: `app.js` (`mcpOAuthService.setTdCache(tdCache)` next to `mcpService.setTdCache`)
|
|
78
|
+
- Test: `test/mcpOAuthService.test.js`
|
|
79
|
+
|
|
80
|
+
**Interfaces:**
|
|
81
|
+
- Consumes Task 1 and Task 2.
|
|
82
|
+
- `startAuthorization(id_project, user_id, body) → { authorization_url, connection_id }` (spec §6 step 1; validates `mode`, `server_url`, `return_url` origin vs `MCP_OAUTH_RETURN_ORIGINS`, manual fields).
|
|
83
|
+
- `completeAuthorization({ code, state, error }) → { connection, return_url }` (spec §6 step 2; state read + `del` before the exchange).
|
|
84
|
+
- `getAccessToken(id_project, connection_id, { force } = {}) → { access_token, token_type, expires_at }` (spec §7, lock + poll).
|
|
85
|
+
- `refreshDue(withinSeconds) → { refreshed, failed, needs_reauth }`.
|
|
86
|
+
- `revokeAndDelete(id_project, connection_id) → { revoked }` (does not touch the integration; Task 4 does).
|
|
87
|
+
- `getConnection(id_project, connection_id)` → doc or 404; `listConnections(id_project)`.
|
|
88
|
+
|
|
89
|
+
- [ ] **Step 1: Failing tests (nock + Redis).**
|
|
90
|
+
- mcp mode end-to-end: authorize → discovery + DCR called, URL has `code_challenge_method=S256`, `resource`, `state`; Redis state exists; callback → token exchange body has `code_verifier` matching the challenge, `redirect_uri`, `resource`; connection `active`, tokens decrypt to the mocked values; state key gone.
|
|
91
|
+
- Second authorize on the same server reuses the stored DCR client (no second `/register`).
|
|
92
|
+
- google mode: authorize URL host `accounts.google.com`, has `access_type=offline`, `prompt=consent`; env unset → 503.
|
|
93
|
+
- manual mode: client secret stored encrypted; `client_secret_basic` sends the Basic header.
|
|
94
|
+
- `return_url` with origin not allowed → 400.
|
|
95
|
+
- Callback with unknown state → 400; with `error=access_denied` → `last_error.code = 'access_denied'`, returns `return_url`; same state twice → second 400 (Review Focus 5).
|
|
96
|
+
- `getAccessToken`: fresh token → no provider call; expiring → refresh, `last_refresh_at` set; response without `refresh_token` keeps the old, with one replaces it (Review Focus 4); `invalid_grant` → `needs_reauth` 409, next call 409 with no nock interceptor consumed (Review Focus 6); `invalid_client` in mcp mode → `client_id` cleared; 500 from provider → 503, status still `active`; two parallel calls → one interceptor, both resolve with the new token (Review Focus 3); connection of another project → 404 (Review Focus 1).
|
|
97
|
+
- `refreshDue(900)`: refreshes only active connections with a refresh token expiring within 900 s; one failure does not stop the others.
|
|
98
|
+
- `revokeAndDelete`: revocation called with the refresh token; revocation 500 → still deleted, `revoked: false`.
|
|
99
|
+
- [ ] **Step 2: Run** → fail.
|
|
100
|
+
- [ ] **Step 3: Implement.** Lock via `tdCache.setNX`; release with `tdCache.del` in `finally`. Poll compares `last_refresh_at` with the value read before trying the lock. Without `tdCache` (tests that don't wire it) fall back to an in-process `Map` of pending promises keyed by connection id, so the single-instance behaviour is the same.
|
|
101
|
+
- [ ] **Step 4: Run** → pass.
|
|
102
|
+
- [ ] **Step 5: Commit** — `feat(mcp-oauth): authorization code + PKCE flow, lazy refresh with lock, revocation`.
|
|
103
|
+
|
|
104
|
+
### Task 4: routes — admin, bot token, callback, scheduler refresh
|
|
105
|
+
|
|
106
|
+
**Files:**
|
|
107
|
+
- Create: `routes/mcpOAuth.js` (mounted inside `routes/mcp.js` as `router.use('/oauth', mcpOAuth)`), `routes/mcpOAuthCallback.js`
|
|
108
|
+
- Modify: `app.js` (`app.use('/oauth2/mcp', mcpOAuthCallback)` before the first `/:projectid` router), `routes/webhook.js` (`POST /mcp-oauth/refresh`)
|
|
109
|
+
- Test: `test/mcpOAuthRoute.test.js`
|
|
110
|
+
|
|
111
|
+
**Interfaces:**
|
|
112
|
+
- `POST /:projectid/mcp/oauth/authorize` (admin) → Task 3 `startAuthorization` with `req.user._id`.
|
|
113
|
+
- `GET /:projectid/mcp/oauth/connections`, `GET …/:id` (admin) → public shape.
|
|
114
|
+
- `POST …/:id/refresh` (admin) → `getAccessToken(..., { force: true })`, responds with the public connection (no token).
|
|
115
|
+
- `DELETE …/:id` (admin) → `revokeAndDelete`, then remove `oauth` from every `mcp` integration server with that `connection_id`, save, `integrationEvent.emit('integration.update', …)`.
|
|
116
|
+
- `GET …/:id/token` (bot/subscription only: `roleChecker.isTypesAsFunction(['bot','subscription'], req.user, req.projectid)` else 403) → `{ access_token, token_type, expires_at }`.
|
|
117
|
+
- Admin-only sub-routes add `roleChecker.hasRole('admin')` (the `/mcp` mount also admits bot/subscription).
|
|
118
|
+
- `GET /oauth2/mcp/callback` → 302 to `return_url` with `mcp_oauth=success&connection_id=` or `mcp_oauth=error&error=`; without `return_url` a small HTML page; 400 HTML page on bad state.
|
|
119
|
+
- `POST /webhook/mcp-oauth/refresh` → `x-auth-token` timing-safe check (copy `/scheduled-start`), body `{ connection_id }` or `{ within_seconds }` (integer 60..86400, default 900).
|
|
120
|
+
|
|
121
|
+
- [ ] **Step 1: Failing tests (chai-http + nock).** Admin flow authorize → callback (302 Location asserted) → list shows `active` and no secret field; admin JWT on `/token` → 403, bot JWT → 200 (Review Focus 2); bot of project B on project A's connection → 404 (Review Focus 1); agent role on `/authorize` → 403; DELETE removes `oauth` from the integration entry and the entry stays; feature env unset → 503 on every route; webhook refresh: no token → 401, wrong token → 401, `MCP_OAUTH_REFRESH_TOKEN` unset → 503, `{ within_seconds: 900 }` → counts.
|
|
122
|
+
- [ ] **Step 2: Run** → fail.
|
|
123
|
+
- [ ] **Step 3: Implement.** Check how existing tests create a bot JWT (e.g. `test/nativemcp.test.js`, faq_kb tests) and reuse that helper.
|
|
124
|
+
- [ ] **Step 4: Run** the file plus `test/nativemcp.test.js` → pass.
|
|
125
|
+
- [ ] **Step 5: Commit** — `feat(mcp-oauth): admin, bot token, callback and scheduler refresh routes`.
|
|
126
|
+
|
|
127
|
+
### Task 5: mcpService uses OAuth connections
|
|
128
|
+
|
|
129
|
+
**Files:**
|
|
130
|
+
- Modify: `services/mcpService.js`, `routes/mcp.js` (doc comments only: `oauth: { connection_id }`)
|
|
131
|
+
- Test: `test/mcpServiceOAuth.test.js`
|
|
132
|
+
|
|
133
|
+
**Interfaces:**
|
|
134
|
+
- `buildServerConfig(projectId, body)`: `oauth.connection_id` → `serverConfig.oauth = { connection_id }`; the legacy shape (`clientId`/`clientSecret`/`redirectUrl`/`scope` without `connection_id`) keeps today's error.
|
|
135
|
+
- `resolveRequestHeaders(headers, serverConfig) → Promise<Boolean>`: existing `applyRequestHeaders`, then the OAuth bearer (overrides `Authorization`).
|
|
136
|
+
- `sendJSONRPCRequest` / `sendInitializedNotification` call `resolveRequestHeaders`; on HTTP 401 with `serverConfig.oauth` → `getAccessToken(..., { force: true })` and one retry.
|
|
137
|
+
- `normalizeMcpServerEntry`: custom and native entries accept `oauth.connection_id`; the connection must exist in `projectId` (404 otherwise); stored as `oauth: { connection_id, mode }`; tools discovery uses it. `resolveNativeServerConfig` passes `oauth` through when given.
|
|
138
|
+
- `getCacheKey(url, projectId, connectionId?)`.
|
|
139
|
+
|
|
140
|
+
- [ ] **Step 1: Failing tests (nock MCP server).** `POST /:projectid/mcp/connect` with `oauth.connection_id` → MCP requests carry `Authorization: Bearer <token>`; customHeaders `Authorization` is overridden; MCP 401 once → refresh + retry succeeds; 401 twice → error, no loop; `POST /mcp/servers` with a connection of another project → 404 (Review Focus 1); saved entry has `oauth: { connection_id, mode }` and no token anywhere in `integration.value` (`JSON.stringify` check); legacy `oauth: { clientId }` still 400 with the old message.
|
|
141
|
+
- [ ] **Step 2: Run** → fail.
|
|
142
|
+
- [ ] **Step 3: Implement.**
|
|
143
|
+
- [ ] **Step 4: Run** the file plus `test/nativemcp.test.js test/mcpOAuthRoute.test.js` → pass.
|
|
144
|
+
- [ ] **Step 5: Commit** — `feat(mcp-oauth): bearer injection and 401 retry in mcpService`.
|
|
145
|
+
|
|
146
|
+
### Task 6: docs and manual end-to-end
|
|
147
|
+
|
|
148
|
+
**Files:**
|
|
149
|
+
- Modify: `CHANGELOG.md` (unreleased entry), `docs/superpowers/specs/2026-11-10-mcp-oauth2-design.md` (status, any decision taken during implementation)
|
|
150
|
+
|
|
151
|
+
- [ ] **Step 1:** Run the reference server: `git clone https://github.com/modelcontextprotocol/example-remote-server && npm i && npm run dev:internal` (port 3232).
|
|
152
|
+
- [ ] **Step 2:** Server with `MCP_OAUTH_ENCRYPTION_KEY=$(openssl rand -base64 32)`, `MCP_OAUTH_ALLOW_INSECURE_URLS=true`, `MCP_OAUTH_RETURN_ORIGINS=http://localhost:4200`, `MCP_OAUTH_REFRESH_TOKEN=<random>`. `POST /:projectid/mcp/oauth/authorize { mode: 'mcp', server_url: 'http://localhost:3232/mcp' }` → open the URL, consent → callback → `active`.
|
|
153
|
+
- [ ] **Step 3:** `POST /:projectid/mcp/connect { url, oauth: { connection_id } }` → tools listed. Bot JWT on `/token` → token. Set `expires_at` in the past in Mongo → next `/token` refreshes. `POST /webhook/mcp-oauth/refresh` → counts.
|
|
154
|
+
- [ ] **Step 4:** Record results (what ran, what was mocked) in the spec's status line.
|
|
155
|
+
- [ ] **Step 5: Commit** — `docs(mcp-oauth): changelog and verification notes`.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# MCP OAuth2 — Piano di implementazione tiledesk-chatbot (tybot)
|
|
2
|
+
|
|
3
|
+
> **Per gli agenti:** SUB-SKILL RICHIESTA: usare superpowers:subagent-driven-development (consigliata) o superpowers:executing-plans per implementare questo piano task per task. Gli step usano la sintassi checkbox (`- [ ]`) per il tracciamento.
|
|
4
|
+
|
|
5
|
+
**Obiettivo:** Quando un'action AI Prompt usa un server MCP la cui voce nell'integration ha `oauth.connection_id`, tybot recupera l'access token da tiledesk-server e lo invia come `Authorization: Bearer …` al backend LLM insieme agli altri header MCP.
|
|
6
|
+
|
|
7
|
+
**Architettura:** Nuovo `services/McpOAuthTokenService.js` (`GET /:id_project/mcp/oauth/connections/:id/token` con il JWT del chatbot, breve cache in-process) → `DirAiPrompt` risolve i token dopo `enrichServersFromIntegration` e li passa ad `arrayToObject`, che imposta `headers.Authorization` per ultimo.
|
|
8
|
+
|
|
9
|
+
**Stack:** Node, `utils/HttpUtils`, mocha + l'harness di test esistente di AI Prompt.
|
|
10
|
+
|
|
11
|
+
**Spec:** `docs/superpowers/specs/2026-11-10-mcp-oauth2-design-it.md` (§7 endpoint del token, §8 cosa salva il server nell'integration, §11 errori).
|
|
12
|
+
|
|
13
|
+
## Vincoli globali
|
|
14
|
+
|
|
15
|
+
- Branch: nuovo `feature/mcp-oauth2` da `main` in tiledesk-chatbot. Un commit per task. Mai fare push.
|
|
16
|
+
- Dipende dall'endpoint del token sul server, già implementato in tiledesk-server (commit `496a71cb`, verificato end to end: spec §14). I token si recuperano sempre dal server: tybot non legge mai `mcp_oauth_connections` dal suo database, anche se `IntegrationService` legge le integration da lì (i token sono cifrati e il refresh sta sul server).
|
|
17
|
+
- Richiesta: `GET API_ENDPOINT + "/" + id_project + "/mcp/oauth/connections/" + connection_id + "/token"`, header `Authorization: 'JWT ' + this.token` (come `IntegrationService.getIntegrationFromApi`). Body della risposta 200 `{ access_token, token_type, expires_at }`.
|
|
18
|
+
- Cache: `Map` in-process con chiave `id_project:connection_id`, voce valida fino a `expires_at - 60 s`; nessuna cache quando `expires_at` è null; mai nei log.
|
|
19
|
+
- Errore (409 `needs_reauth`, 404, 5xx, rete): l'action fallisce come quando manca l'integration MCP — `flowError` = `"MCP server <name> needs to be reconnected"` per il 409, `"MCP server <name> OAuth token unavailable"` negli altri casi; poi `falseIntent` se impostato, altrimenti `callback()`.
|
|
20
|
+
- L'`Authorization` da OAuth sovrascrive un `Authorization` proveniente da `customHeaders` o da variabili del flow.
|
|
21
|
+
- Test: sottoinsieme di `npm test` per `tybotRoute/test/conversation-ai_prompt_test.js`, `tybotRoute/test/dir_ai_prompt_headers_test.js` e il nuovo file; il server è mockato dallo stub HTTP già usato in quei test.
|
|
22
|
+
|
|
23
|
+
## Punti di attenzione per la review
|
|
24
|
+
|
|
25
|
+
1. Un server senza `oauth` → nessuna richiesta del token (nessuna regressione, nessuna latenza aggiunta).
|
|
26
|
+
2. Il token non compare mai nell'output di `winston`/`this.logger` (`json.servers` è loggato in debug: oscurare lì `headers.Authorization`).
|
|
27
|
+
3. I server nativi non hanno mai `oauth`: il server lo rifiuta sulle voci native (400, spec §8). Una voce nativa non deve chiamare il service del token e mantiene invariati gli header delle variabili del flow.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
### Task 1: service del token
|
|
32
|
+
|
|
33
|
+
**File:**
|
|
34
|
+
- Creare: `tybotRoute/services/McpOAuthTokenService.js`
|
|
35
|
+
- Test: `tybotRoute/test/mcp_oauth_token_service_test.js`
|
|
36
|
+
|
|
37
|
+
**Interfacce:**
|
|
38
|
+
- `getToken(id_project, connection_id, token) → Promise<{ access_token, token_type, expires_at }>`; rifiuta con `err.status` (409/404/5xx, 502 su errore di rete) ed `err.code` preso dal body.
|
|
39
|
+
- `clearCache()` per i test. Campi d'istanza `httpUtils`, `now` sostituibili come in `IntegrationService`.
|
|
40
|
+
|
|
41
|
+
- [ ] **Step 1: Test che falliscono.** 200 → restituito e messo in cache (seconda chiamata senza HTTP); la cache scade 60 s prima di `expires_at` (stub di `now`); `expires_at: null` → nessuna cache; 409 → rifiuta con `status 409, code 'needs_reauth'`; errore di rete → 502.
|
|
42
|
+
- [ ] **Step 2: Eseguire** → fallisce.
|
|
43
|
+
- [ ] **Step 3: Implementare.**
|
|
44
|
+
- [ ] **Step 4: Eseguire** → passa.
|
|
45
|
+
- [ ] **Step 5: Commit** — `feat(ai-prompt): MCP OAuth token service`.
|
|
46
|
+
|
|
47
|
+
### Task 2: iniezione del bearer in DirAiPrompt
|
|
48
|
+
|
|
49
|
+
**File:**
|
|
50
|
+
- Modificare: `tybotRoute/tiledeskChatbotPlugs/directives/DirAiPrompt.js`
|
|
51
|
+
- Test: `tybotRoute/test/dir_ai_prompt_headers_test.js` (nuovi casi), `tybotRoute/test/conversation-ai_prompt_test.js` (un caso end-to-end)
|
|
52
|
+
|
|
53
|
+
**Interfacce:**
|
|
54
|
+
- `resolveOAuthTokens(servers, mcp_integration) → Promise<{ tokens: { [serverName]: 'Bearer …' }, error?: string }>`: per ogni server dell'action, `getIntegrationServer`; se `integrationServer.oauth?.connection_id` → `McpOAuthTokenService.getToken(this.projectId, id, this.token)`. Le richieste vanno in parallelo; il primo errore valorizza `error`.
|
|
55
|
+
- `arrayToObject(arr, mcp_integration, flowVariables, oauthTokens = {})`: dopo `mergeHeadersWithVariables`, `if (oauthTokens[server.name]) cleanServer.headers.Authorization = oauthTokens[server.name]`.
|
|
56
|
+
- Chiamato nel ramo `action.servers` subito dopo `resolveNativeServerUrls`, prima di costruire `flowVariables`; il percorso d'errore ricalca `nativeUrlError`.
|
|
57
|
+
- La riga `winston.debug("DirAiPrompt json.servers: ", …)` logga una copia con `headers.Authorization` sostituito da `'[REDACTED]'`.
|
|
58
|
+
|
|
59
|
+
- [ ] **Step 1: Test che falliscono.** Server dell'integration con `oauth: { connection_id: 'c1' }` → `json.servers.<name>.headers.Authorization === 'Bearer t1'`; `Authorization: 'x'` nei customHeaders → sovrascritto; server senza `oauth` → service del token non chiamato (punto di review 1); server nativo senza `oauth` → service del token non chiamato e header delle variabili del flow invariati (punto di review 3); service del token 409 → `flowError` "needs to be reconnected" e viene eseguito il false intent; il log di debug non contiene `t1` (punto di review 2).
|
|
60
|
+
- [ ] **Step 2: Eseguire** → fallisce.
|
|
61
|
+
- [ ] **Step 3: Implementare.**
|
|
62
|
+
- [ ] **Step 4: Eseguire** i due file di test AI Prompt esistenti più quello del Task 1 → passa.
|
|
63
|
+
- [ ] **Step 5: Commit** — `feat(ai-prompt): send MCP OAuth bearer from the server token endpoint`.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# MCP OAuth2 — tiledesk-chatbot (tybot) Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
4
|
+
|
|
5
|
+
**Goal:** When an AI Prompt action uses an MCP server whose integration entry has `oauth.connection_id`, tybot fetches the access token from tiledesk-server and sends it as `Authorization: Bearer …` to the LLM backend with the other MCP headers.
|
|
6
|
+
|
|
7
|
+
**Architecture:** New `services/McpOAuthTokenService.js` (`GET /:id_project/mcp/oauth/connections/:id/token` with the chatbot JWT, short in-process cache) → `DirAiPrompt` resolves tokens after `enrichServersFromIntegration` and passes them to `arrayToObject`, which sets `headers.Authorization` last.
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Node, `utils/HttpUtils`, mocha + the existing AI Prompt test harness.
|
|
10
|
+
|
|
11
|
+
**Spec:** `docs/superpowers/specs/2026-11-10-mcp-oauth2-design.md` (§7 token endpoint, §8 what the server stores in the integration, §11 errors).
|
|
12
|
+
|
|
13
|
+
## Global Constraints
|
|
14
|
+
|
|
15
|
+
- Branch: new `feature/mcp-oauth2` from `main` in tiledesk-chatbot. One commit per task. Never push.
|
|
16
|
+
- Depends on the server token endpoint, already implemented in tiledesk-server (commit `496a71cb`, verified end to end: spec §14). Tokens are always fetched from the server: tybot never reads `mcp_oauth_connections` from its database, even though `IntegrationService` reads integrations from it (tokens are encrypted and refresh lives on the server).
|
|
17
|
+
- Request: `GET API_ENDPOINT + "/" + id_project + "/mcp/oauth/connections/" + connection_id + "/token"`, header `Authorization: 'JWT ' + this.token` (same as `IntegrationService.getIntegrationFromApi`). 200 body `{ access_token, token_type, expires_at }`.
|
|
18
|
+
- Cache: in-process `Map` keyed `id_project:connection_id`, entry valid until `expires_at - 60 s`; no cache when `expires_at` is null; never logged.
|
|
19
|
+
- Failure (409 `needs_reauth`, 404, 5xx, network): the action fails like a missing MCP integration — `flowError` = `"MCP server <name> needs to be reconnected"` for 409, `"MCP server <name> OAuth token unavailable"` otherwise; then `falseIntent` if set, else `callback()`.
|
|
20
|
+
- `Authorization` from OAuth overrides an `Authorization` coming from `customHeaders` or flow variables.
|
|
21
|
+
- Tests: `npm test` subset for `tybotRoute/test/conversation-ai_prompt_test.js`, `tybotRoute/test/dir_ai_prompt_headers_test.js` and the new file; the server is mocked by the existing HTTP stub used in those tests.
|
|
22
|
+
|
|
23
|
+
## Review Focus
|
|
24
|
+
|
|
25
|
+
1. A server without `oauth` → no token request at all (no regression, no added latency).
|
|
26
|
+
2. The token never appears in `winston`/`this.logger` output (`json.servers` is logged at debug: redact `headers.Authorization` there).
|
|
27
|
+
3. Native servers never carry `oauth`: the server rejects it on native entries (400, spec §8). A native entry must not call the token service and keeps its flow-variable headers unchanged.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
### Task 1: token service
|
|
32
|
+
|
|
33
|
+
**Files:**
|
|
34
|
+
- Create: `tybotRoute/services/McpOAuthTokenService.js`
|
|
35
|
+
- Test: `tybotRoute/test/mcp_oauth_token_service_test.js`
|
|
36
|
+
|
|
37
|
+
**Interfaces:**
|
|
38
|
+
- `getToken(id_project, connection_id, token) → Promise<{ access_token, token_type, expires_at }>`; rejects with `err.status` (409/404/5xx, 502 on network) and `err.code` from the body.
|
|
39
|
+
- `clearCache()` for tests. Instance fields `httpUtils`, `now` substitutable like `IntegrationService`.
|
|
40
|
+
|
|
41
|
+
- [ ] **Step 1: Failing tests.** 200 → returned and cached (second call no HTTP); cache expiry 60 s before `expires_at` (stub `now`); `expires_at: null` → no cache; 409 → rejects `status 409, code 'needs_reauth'`; network error → 502.
|
|
42
|
+
- [ ] **Step 2: Run** → fail.
|
|
43
|
+
- [ ] **Step 3: Implement.**
|
|
44
|
+
- [ ] **Step 4: Run** → pass.
|
|
45
|
+
- [ ] **Step 5: Commit** — `feat(ai-prompt): MCP OAuth token service`.
|
|
46
|
+
|
|
47
|
+
### Task 2: DirAiPrompt bearer injection
|
|
48
|
+
|
|
49
|
+
**Files:**
|
|
50
|
+
- Modify: `tybotRoute/tiledeskChatbotPlugs/directives/DirAiPrompt.js`
|
|
51
|
+
- Test: `tybotRoute/test/dir_ai_prompt_headers_test.js` (new cases), `tybotRoute/test/conversation-ai_prompt_test.js` (one end-to-end case)
|
|
52
|
+
|
|
53
|
+
**Interfaces:**
|
|
54
|
+
- `resolveOAuthTokens(servers, mcp_integration) → Promise<{ tokens: { [serverName]: 'Bearer …' }, error?: string }>`: for each action server, `getIntegrationServer`; if `integrationServer.oauth?.connection_id` → `McpOAuthTokenService.getToken(this.projectId, id, this.token)`. Requests run in parallel; first failure sets `error`.
|
|
55
|
+
- `arrayToObject(arr, mcp_integration, flowVariables, oauthTokens = {})`: after `mergeHeadersWithVariables`, `if (oauthTokens[server.name]) cleanServer.headers.Authorization = oauthTokens[server.name]`.
|
|
56
|
+
- Called in the `action.servers` branch right after `resolveNativeServerUrls`, before building `flowVariables`; the error path mirrors `nativeUrlError`.
|
|
57
|
+
- The `winston.debug("DirAiPrompt json.servers: ", …)` line logs a copy with `headers.Authorization` replaced by `'[REDACTED]'`.
|
|
58
|
+
|
|
59
|
+
- [ ] **Step 1: Failing tests.** Integration server with `oauth: { connection_id: 'c1' }` → `json.servers.<name>.headers.Authorization === 'Bearer t1'`; customHeaders `Authorization: 'x'` → overridden; server without `oauth` → token service not called (Review Focus 1); native server without `oauth` → token service not called and flow-variable headers unchanged (Review Focus 3); token service 409 → `flowError` "needs to be reconnected" and the false intent runs; debug log does not contain `t1` (Review Focus 2).
|
|
60
|
+
- [ ] **Step 2: Run** → fail.
|
|
61
|
+
- [ ] **Step 3: Implement.**
|
|
62
|
+
- [ ] **Step 4: Run** the two existing AI Prompt test files plus Task 1's → pass.
|
|
63
|
+
- [ ] **Step 5: Commit** — `feat(ai-prompt): send MCP OAuth bearer from the server token endpoint`.
|
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# MCP OAuth2 — Design
|
|
2
|
+
|
|
3
|
+
Data: 2026-11-10 · Stato: lato server implementato (commit f4fe91fe..3224546e) e verificato end to end contro il server di riferimento (§14); restano tybot, UI e job dello scheduler
|
|
4
|
+
Repo: tiledesk-server, tiledesk-chatbot (tybot). La UI di dashboard / design-studio e tiledesk-scheduler-service sono follow-up (§12).
|
|
5
|
+
Branch: `features-2611/oauth2-mcp` (tiledesk-server).
|
|
6
|
+
Server MCP di riferimento: [modelcontextprotocol/example-remote-server](https://github.com/modelcontextprotocol/example-remote-server) ([guida OAuth](https://github.com/modelcontextprotocol/example-remote-server/blob/main/docs/oauth-implementation.md)), specifica MCP Authorization `2025-06-18`.
|
|
7
|
+
|
|
8
|
+
## 1. Obiettivo
|
|
9
|
+
|
|
10
|
+
Un admin di progetto può collegare un server MCP protetto da OAuth2. tiledesk-server fa da client OAuth: esegue il flusso authorization code + PKCE, salva i token cifrati, li rinfresca e fornisce al chatbot engine un access token valido ogni volta che un'action AI Prompt chiama quel server MCP. Tre modi per configurare il client OAuth:
|
|
11
|
+
|
|
12
|
+
- **mcp** — la specifica MCP Authorization: discovery a partire dall'URL del server MCP, Dynamic Client Registration. L'admin inserisce solo l'URL MCP.
|
|
13
|
+
- **google** — preset con gli endpoint di Google e un unico client OAuth Google di Tiledesk da env.
|
|
14
|
+
- **manual** — l'admin inserisce endpoint di autorizzazione e token, client id/secret e scope (qualsiasi provider OAuth2 senza discovery).
|
|
15
|
+
|
|
16
|
+
## 2. Decisioni (utente, 2026-11-10)
|
|
17
|
+
|
|
18
|
+
1. I token stanno nel database. Il chatbot chiama un endpoint del server che restituisce l'access token letto dal DB. Uno scheduler, in seguito, chiamerà un'API del server che rinfresca e salva i token nel DB.
|
|
19
|
+
2. Strategia di refresh per ora: **lazy** — l'endpoint del token rinfresca quando l'access token sta per scadere. L'API di refresh per lo scheduler si crea ora; la registrazione del job nello scheduler è un follow-up.
|
|
20
|
+
3. Google: un unico client OAuth Google Cloud di Tiledesk (`MCP_OAUTH_GOOGLE_CLIENT_ID` / `_SECRET`). Nessun client per progetto.
|
|
21
|
+
4. Scope di questo giro: fasi server 1–3 (store + flusso + token a runtime) più l'API di refresh, e la modifica a tybot che usa l'endpoint del token.
|
|
22
|
+
5. Il codice del client OAuth è scritto con axios. Nessuna dipendenza da `@modelcontextprotocol/sdk`.
|
|
23
|
+
|
|
24
|
+
## 3. Stato attuale (verificato 2026-11-10)
|
|
25
|
+
|
|
26
|
+
- `services/mcpService.js` gestisce l'autenticazione tramite `customHeaders` o il vecchio `auth` (bearer / api-key / basic). `buildServerConfig` rifiuta un oggetto `oauth`: *"OAuth2 authentication is not supported yet"*.
|
|
27
|
+
- I server MCP sono salvati nell'integration `mcp` (`models/integrations.js`, `value.servers[]`). I server custom sono identificati da `url`, quelli nativi da `nativeId` (`findServerIndex`).
|
|
28
|
+
- `GET /:projectid/integration*` è in cache mongoose per `cacheUtil.longTTL` (`project:<id>:integrations`) e restituisce `customHeaders[].value` non mascherati (`maskIntegrationSecrets` maschera solo `apikey`, `api_key`, `token`, `secret`, `client_secret`, `password`). Quindi un token non deve essere scritto nell'integration.
|
|
29
|
+
- `DirAiPrompt.js` di tybot legge `/integration/name/mcp` con il token del bot a ogni esecuzione, trasforma i `customHeaders` in `headers` (`arrayToObject`, `enrichServersFromIntegration`) e li inoltra al backend LLM.
|
|
30
|
+
- `/:projectid/mcp` è montato con `passport basic|jwt`, `validtoken`, `roleChecker.hasRoleOrTypes('admin', ['bot','subscription'])`.
|
|
31
|
+
- Gli endpoint interni protetti da token seguono `/webhook/scheduled-start`: header `x-auth-token`, `crypto.timingSafeEqual` contro un token da env, 503 se non configurato.
|
|
32
|
+
- `TdCache` ha `setNX(key, value, ttlSeconds)`, `setJSON`, `getJSON`, `del`.
|
|
33
|
+
- `utils/logRedactor.js` oscura le chiavi `^(…|token|…|authorization|x-auth-token|…)$` (regex ancorata: `access_token` e `refresh_token` **non** sono coperti) e le stringhe `Bearer …`.
|
|
34
|
+
- `routes/urlPreview.js` ha solo un controllo degli IP privati basato su regex dell'hostname (nessuna risoluzione DNS).
|
|
35
|
+
- Disponibili Node 18.19, axios, nock, mocha + chai-http.
|
|
36
|
+
|
|
37
|
+
## 4. Modello dati (tiledesk-server)
|
|
38
|
+
|
|
39
|
+
Nuova collection `mcp_oauth_connections` (`models/mcpOAuthConnection.js`):
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
{
|
|
43
|
+
id_project: String (index),
|
|
44
|
+
mode: 'mcp' | 'google' | 'manual',
|
|
45
|
+
server_url: String, // URL del server MCP = risorsa OAuth (RFC 8707)
|
|
46
|
+
name: String, // nome visualizzato
|
|
47
|
+
status: 'pending' | 'active' | 'needs_reauth' | 'revoked',
|
|
48
|
+
// client OAuth
|
|
49
|
+
client_id: String,
|
|
50
|
+
client_secret_enc: String, // cifrato, assente per client pubblici / google (env)
|
|
51
|
+
client_registered_at: Date, // solo DCR
|
|
52
|
+
// endpoint (scoperti, preset o manuali)
|
|
53
|
+
resource: String, // modalità mcp: `resource` dei protected resource metadata (può essere l'origin, non server_url)
|
|
54
|
+
issuer: String,
|
|
55
|
+
authorization_endpoint: String,
|
|
56
|
+
token_endpoint: String,
|
|
57
|
+
revocation_endpoint: String,
|
|
58
|
+
registration_endpoint: String,
|
|
59
|
+
token_endpoint_auth_method: 'client_secret_basic' | 'client_secret_post' | 'none',
|
|
60
|
+
scopes: [String],
|
|
61
|
+
// token
|
|
62
|
+
access_token_enc: String,
|
|
63
|
+
refresh_token_enc: String,
|
|
64
|
+
token_type: String, // 'Bearer'
|
|
65
|
+
expires_at: Date, // null quando il provider non invia expires_in
|
|
66
|
+
granted_scopes: [String],
|
|
67
|
+
last_refresh_at: Date,
|
|
68
|
+
last_error: { code: String, message: String, at: Date },
|
|
69
|
+
created_by: String, // id dell'utente che ha avviato il flusso
|
|
70
|
+
createdAt, updatedAt
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Indice univoco `{ id_project: 1, server_url: 1 }`: una connessione per server MCP per progetto.
|
|
75
|
+
|
|
76
|
+
La voce del server nell'integration riceve solo un riferimento (nessun segreto):
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
oauth: { connection_id: String, mode: 'mcp'|'google'|'manual' }
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Cifratura: AES-256-GCM, chiave `MCP_OAUTH_ENCRYPTION_KEY` (32 byte, base64). Formato salvato `v1:<iv b64>:<tag b64>:<ciphertext b64>`. Mai restituito da nessuna API tranne l'endpoint del token (§7), che restituisce solo l'access token.
|
|
83
|
+
|
|
84
|
+
## 5. Configurazione
|
|
85
|
+
|
|
86
|
+
| Env | Scopo |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `MCP_OAUTH_ENCRYPTION_KEY` | Obbligatoria. Senza, ogni rotta OAuth risponde 503 `"MCP OAuth is not available on this installation"`. |
|
|
89
|
+
| `MCP_OAUTH_REDIRECT_BASE_URL` | URL base pubblico del server; redirect URI = `<base>/oauth2/mcp/callback`. Se assente si usa `API_URL`. |
|
|
90
|
+
| `MCP_OAUTH_RETURN_ORIGINS` | Origin separate da virgola ammesse come `return_url` (dashboard / design-studio). |
|
|
91
|
+
| `MCP_OAUTH_GOOGLE_CLIENT_ID`, `MCP_OAUTH_GOOGLE_CLIENT_SECRET` | Preset Google. Senza, `mode: 'google'` risponde 503. |
|
|
92
|
+
| `MCP_OAUTH_REFRESH_TOKEN` | `x-auth-token` dell'API di refresh per lo scheduler. Senza, l'API risponde 503. |
|
|
93
|
+
| `MCP_OAUTH_ALLOW_INSECURE_URLS` | `true` solo in dev/test: consente `http://` e host privati/loopback (serve per il server di riferimento su `localhost:3232`). |
|
|
94
|
+
|
|
95
|
+
## 6. Flusso di autorizzazione
|
|
96
|
+
|
|
97
|
+
1. **Avvio** — `POST /:projectid/mcp/oauth/authorize` (admin), body `{ server_url, name?, mode, scopes?, return_url?, manual?: { authorization_endpoint, token_endpoint, revocation_endpoint?, client_id, client_secret?, token_endpoint_auth_method? } }`.
|
|
98
|
+
- `mcp`: discovery (§6.1), poi DCR se per quel server non c'è un client salvato (§6.2).
|
|
99
|
+
- `google`: endpoint `https://accounts.google.com/o/oauth2/v2/auth`, `https://oauth2.googleapis.com/token`, `https://oauth2.googleapis.com/revoke`; parametri extra `access_type=offline`, `prompt=consent`, `include_granted_scopes=true`; `scopes` obbligatori.
|
|
100
|
+
- `manual`: endpoint e client dal body (client secret cifrato).
|
|
101
|
+
- Crea o aggiorna la connessione (`status: 'pending'` se nuova; una connessione `active` resta utilizzabile finché il nuovo flusso non si completa).
|
|
102
|
+
- Genera `state` (32 byte casuali, base64url) e `code_verifier` (64 caratteri), `code_challenge = base64url(sha256(verifier))`, metodo `S256`.
|
|
103
|
+
- Salva `mcp_oauth:state:<state>` → `{ id_project, connection_id, code_verifier, return_url, user_id }` su Redis, TTL 600 s.
|
|
104
|
+
- Restituisce `{ authorization_url, connection_id }`. Parametri dell'URL: `response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `state`, `scope` (separati da spazio, se presenti), `resource=<server_url>` (modalità mcp).
|
|
105
|
+
2. **Callback** — `GET /oauth2/mcp/callback?code&state` (pubblica, montata prima dei router `/:projectid`).
|
|
106
|
+
- Legge e **cancella** lo state (monouso). Mancante/scaduto → pagina 400.
|
|
107
|
+
- Parametro `error` dal provider → `last_error` sulla connessione, redirect a `return_url?mcp_oauth=error&error=<code>`.
|
|
108
|
+
- Scambia il code sul token endpoint (`grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier`, `resource` in modalità mcp, autenticazione del client secondo `token_endpoint_auth_method`).
|
|
109
|
+
- Salva i token cifrati, `expires_at = now + expires_in`, `status: 'active'`, azzera `last_error`.
|
|
110
|
+
- Redirect a `return_url?mcp_oauth=success&connection_id=<id>`; senza `return_url`, una pagina HTML minima "Connesso, puoi chiudere questa finestra".
|
|
111
|
+
3. **Uso** — l'admin salva poi il server MCP con `oauth.connection_id` (`POST /:projectid/mcp/servers`); `mcpService` usa il token per connect / discovery dei tool (§8).
|
|
112
|
+
|
|
113
|
+
### 6.1 Discovery (modalità `mcp`)
|
|
114
|
+
|
|
115
|
+
1. `POST <server_url>` con una richiesta `initialize` senza autenticazione. Ci si aspetta 401 con `WWW-Authenticate: Bearer resource_metadata="<url>"`.
|
|
116
|
+
2. Protected Resource Metadata (RFC 9728): l'URL `resource_metadata`, altrimenti `<origin>/.well-known/oauth-protected-resource<path>`, altrimenti `<origin>/.well-known/oauth-protected-resource`. Si prende `authorization_servers[0]` e `scopes_supported` come scope di default se non ne vengono indicati.
|
|
117
|
+
3. Authorization Server Metadata: `<issuer>/.well-known/oauth-authorization-server` (RFC 8414, con inserimento del path se l'issuer ha un path), altrimenti `/.well-known/openid-configuration`. Richiede `authorization_endpoint`, `token_endpoint`; `code_challenge_methods_supported`, se presente, deve includere `S256`.
|
|
118
|
+
4. Se il server risponde 200 all'initialize non autenticato, la discovery fallisce con 400 `"This MCP server does not require OAuth"`.
|
|
119
|
+
|
|
120
|
+
### 6.2 Dynamic Client Registration (modalità `mcp`)
|
|
121
|
+
|
|
122
|
+
- `POST registration_endpoint` con `{ client_name: 'Tiledesk', redirect_uris: [<redirect uri>], grant_types: ['authorization_code','refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'client_secret_post' }`.
|
|
123
|
+
- Si salvano `client_id`, `client_secret` (cifrato), il `token_endpoint_auth_method` restituito, `client_registered_at`.
|
|
124
|
+
- Nessun `registration_endpoint` → 400 `"This MCP server does not support dynamic client registration; use mode 'manual'"`.
|
|
125
|
+
- Il client registrato viene riusato dai flussi successivi della stessa connessione. Una risposta `invalid_client` dal token endpoint elimina il client salvato, così il prossimo authorize si registra di nuovo (il server di riferimento fa scadere i client dopo 30 giorni).
|
|
126
|
+
|
|
127
|
+
## 7. Token a runtime e refresh
|
|
128
|
+
|
|
129
|
+
`oauthTokenService.getAccessToken(connection)`:
|
|
130
|
+
|
|
131
|
+
- `status !== 'active'` → errore `needs_reauth` (409).
|
|
132
|
+
- `expires_at` assente o a più di `REFRESH_WINDOW_S = 300` s → decifra e restituisce.
|
|
133
|
+
- Altrimenti refresh:
|
|
134
|
+
- Lock `mcp_oauth:refresh_lock:<id>` con `setNX`, TTL 30 s.
|
|
135
|
+
- Lock non acquisito → interroga il DB ogni 250 ms per al massimo 5 s cercando un `last_refresh_at` più recente; poi restituisce il token se ancora valido, altrimenti 503.
|
|
136
|
+
- Lock acquisito → ricarica la connessione, `grant_type=refresh_token` (+ `resource` in modalità mcp). Salva il nuovo access token; salva il nuovo refresh token **solo se ne arriva uno** (Google non li ruota mai, il server di riferimento sì). Rilascia il lock.
|
|
137
|
+
- `invalid_grant` → `status: 'needs_reauth'`, `last_error`, 409. `invalid_client` → elimina anche il client DCR (§6.2). Errore di rete/5xx → `last_error`, 503, stato invariato.
|
|
138
|
+
- Nessun refresh token e access token scaduto → `needs_reauth`.
|
|
139
|
+
|
|
140
|
+
Endpoint:
|
|
141
|
+
|
|
142
|
+
- `GET /:projectid/mcp/oauth/connections/:id/token` — **solo chiamanti bot o subscription** (un JWT admin riceve 403, così i token non arrivano mai alla dashboard). 200 `{ access_token, token_type, expires_at }`.
|
|
143
|
+
- `POST /:projectid/mcp/oauth/connections/:id/refresh` — admin; forza un refresh, restituisce la connessione pubblica.
|
|
144
|
+
- `POST /webhook/mcp-oauth/refresh` — scheduler; header `x-auth-token: $MCP_OAUTH_REFRESH_TOKEN`. Body `{ connection_id }` ne rinfresca una e risponde 200 `{ success, connection_id, expires_at }` (404 se non esiste, 409 `needs_reauth`); `{ within_seconds }` (default 900, max 86400) rinfresca ogni connessione `active` con refresh token e `expires_at` entro quella finestra, in sequenza, isolando ogni errore. 200 `{ success, refreshed, failed, needs_reauth }`; 400 se `within_seconds` non è un intero tra 60 e 86400. 401 token errato, 503 non configurato.
|
|
145
|
+
|
|
146
|
+
## 8. Modifiche a mcpService
|
|
147
|
+
|
|
148
|
+
- `serverConfig` riceve `oauth: { connection_id }`. `applyRequestHeaders` diventa compatibile con l'asincrono tramite un nuovo `resolveRequestHeaders(serverConfig)`: quando `oauth.connection_id` è valorizzato carica la connessione (stesso `id_project`), ottiene il token e imposta `Authorization: Bearer <token>`, sovrascrivendo un eventuale `Authorization` dei `customHeaders`.
|
|
149
|
+
- `sendJSONRPCRequest`: un 401 da un server con OAuth provoca un refresh forzato e un solo nuovo tentativo.
|
|
150
|
+
- `buildServerConfig` accetta `oauth.connection_id` (rifiuta la vecchia forma di `oauth` con il messaggio attuale). `normalizeMcpServerEntry` copia `oauth: { connection_id, mode }` nella voce salvata dopo aver verificato che la connessione appartenga al progetto.
|
|
151
|
+
- `getCacheKey` include l'id della connessione, così le sessioni non vengono condivise tra connessioni.
|
|
152
|
+
- Deciso durante lo sviluppo: il bearer viene inviato solo se il `server_url` della connessione coincide con l'URL chiamato (normalizzato), altrimenti 400. Senza questo controllo un admin potrebbe collegare la connessione del server A al server B e consegnare a B il token di A.
|
|
153
|
+
- Deciso durante lo sviluppo: le voci native con `oauth` rispondono 400. L'URL dei server nativi non viene mai esposto, quindi l'admin non può lanciare `authorize` su di essi; per supportarli `authorize` deve accettare un `nativeId` (§12).
|
|
154
|
+
- Gli errori OAuth mantengono il loro status attraverso `sendJSONRPCRequest` e `routes/mcp.js` (404, 409, 503) invece del 500 generico.
|
|
155
|
+
|
|
156
|
+
## 9. API di gestione delle connessioni (admin)
|
|
157
|
+
|
|
158
|
+
- `GET /:projectid/mcp/oauth/connections` — forma pubblica: `{ _id, mode, server_url, name, status, scopes, granted_scopes, expires_at, last_refresh_at, last_error, issuer, createdAt, updatedAt }`. Nessun segreto, nessun `client_id` per google.
|
|
159
|
+
- `GET /:projectid/mcp/oauth/connections/:id` — stessa forma.
|
|
160
|
+
- `DELETE /:projectid/mcp/oauth/connections/:id` — revoca best-effort (refresh token, poi access token) su `revocation_endpoint`, cancella la connessione, rimuove `oauth` dalle voci dell'integration che la referenziano (le voci restano, senza autenticazione) ed emette `integration.update`. 200 `{ success: true, revoked: Boolean }`.
|
|
161
|
+
|
|
162
|
+
## 10. Sicurezza
|
|
163
|
+
|
|
164
|
+
- PKCE S256 sempre; `state` monouso, TTL 10 minuti, legato a progetto e utente.
|
|
165
|
+
- L'origin di `return_url` deve essere in `MCP_OAUTH_RETURN_ORIGINS`, altrimenti 400 all'authorize.
|
|
166
|
+
- Guard sugli URL in uscita (`utils/outboundUrlGuard.js`) per ogni URL influenzato dall'utente (URL del server, metadati, endpoint da discovery o manuali): solo `https:`, gli indirizzi risolti via DNS non devono essere loopback, privati, link-local, CGNAT, ULA o non specificati; `maxRedirects: 0`; timeout 10 s; body delle risposte ≤ 1 MB. `MCP_OAUTH_ALLOW_INSECURE_URLS=true` lo disattiva.
|
|
167
|
+
- Segreti cifrati a riposo; `logRedactor` aggiunge `access_token`, `refresh_token`, `code_verifier`, `code`, `client_secret`; `maskIntegrationSecrets` invariato (nessun segreto nell'integration).
|
|
168
|
+
- Endpoint del token raggiungibile solo con credenziali bot/subscription dello stesso progetto.
|
|
169
|
+
|
|
170
|
+
## 11. Errori (riepilogo)
|
|
171
|
+
|
|
172
|
+
| Caso | Stato |
|
|
173
|
+
|---|---|
|
|
174
|
+
| Env della feature mancante | 503 |
|
|
175
|
+
| Body errato / discovery o DCR non supportati / return_url non ammesso | 400 |
|
|
176
|
+
| Connessione di un altro progetto o inesistente | 404 |
|
|
177
|
+
| Admin che chiama l'endpoint del token | 403 |
|
|
178
|
+
| Connessione `needs_reauth` / `revoked` / `pending` sul token | 409 `{ success: false, error: <messaggio>, code: 'needs_reauth' }` |
|
|
179
|
+
| Connessione OAuth usata per un altro URL di server | 400 |
|
|
180
|
+
| Provider irraggiungibile o 5xx | 503 (502 su authorize / callback) |
|
|
181
|
+
|
|
182
|
+
## 12. Follow-up (non in questo giro)
|
|
183
|
+
|
|
184
|
+
- **Job dello scheduler**: un cron globale (ogni 10–15 minuti) in tiledesk-scheduler-service che chiama `POST /webhook/mcp-oauth/refresh` con `{ within_seconds: 900 }`. Serve un nuovo target (o un target HTTP generico) nello scheduler; contratto non verificato (repo non accessibile da qui). Mantiene vivi i refresh token dei provider con scadenza per inattività breve (il server di riferimento: 7 giorni) e segnala presto i `needs_reauth`.
|
|
185
|
+
- **UI** (dashboard / design-studio): pulsante "Connetti" che apre `authorization_url` in un popup, legge `mcp_oauth=success|error` sul `return_url`, mostra lo stato e "Riconnetti".
|
|
186
|
+
- **Verifica Google**: gli scope sensibili/ristretti (Gmail, Drive) richiedono la verifica dell'app da parte di Google (ristretti: assessment CASA); con stato di pubblicazione "Testing" i refresh token scadono dopo 7 giorni.
|
|
187
|
+
- Server MCP nativi con OAuth: `authorize` che accetta un `nativeId` (l'URL resta nascosto), poi voci del catalogo con modalità `oauth` e scope di default.
|
|
188
|
+
|
|
189
|
+
## 13. Test
|
|
190
|
+
|
|
191
|
+
- Unitari: round-trip della cifratura e rilevamento delle manomissioni; challenge PKCE; costruzione degli URL di discovery (con e senza path); guard sugli URL.
|
|
192
|
+
- Test delle rotte con nock per discovery, DCR, token, refresh, revoca; Redis per state/lock.
|
|
193
|
+
- Concorrenza: due richieste del token in parallelo su un token in scadenza → esattamente una chiamata di refresh.
|
|
194
|
+
- End-to-end manuale contro il server di riferimento (`npm run dev:internal`, porta 3232) con `MCP_OAUTH_ALLOW_INSECURE_URLS=true`.
|
|
195
|
+
|
|
196
|
+
## 14. Verifica (2026-11-10)
|
|
197
|
+
|
|
198
|
+
- Automatica: 128 test mocha (`test/mcpOAuthUtils`, `mcpOAuthDiscovery`, `mcpOAuthService`, `mcpOAuthRoute`, `mcpServiceOAuth`, `nativemcp`), eseguiti con Node 22 e con i moduli enterprise tolti da `node_modules`. Provider e server MCP sono simulati con nock; Mongo e Redis sono reali (locali).
|
|
199
|
+
- End to end manuale contro il server di riferimento (`npm run dev:internal`, porta 3232, auth in modalità interna) e tiledesk-server sulla porta 3000 con `MCP_OAUTH_ALLOW_INSECURE_URLS=true` e un database dedicato. Niente di simulato; la pagina di consenso dell'identity provider fittizio del server di riferimento è stata guidata con curl. Risultati:
|
|
200
|
+
- `authorize` in modalità `mcp`: discovery, registrazione dinamica (`token_endpoint_auth_method: none`, nessun secret) e parametro `resource` `http://localhost:3232/`.
|
|
201
|
+
- Callback: 302 al `return_url` con `mcp_oauth=success`; la connessione è `active` e la forma pubblica non contiene segreti.
|
|
202
|
+
- `POST /mcp/connect` e `/mcp/servers` con `oauth.connection_id`: 9 tool; la voce salvata contiene `{ connection_id, mode: 'mcp' }`.
|
|
203
|
+
- `/token`: admin 403, JWT del bot 200. Con `expires_at` spostato nel passato la chiamata successiva ha fatto il refresh e restituito un nuovo access token, con cui i tool sono stati elencati. Il server di riferimento ruota i refresh token e tre refresh di seguito sono andati a buon fine.
|
|
204
|
+
- Webhook dello scheduler: token errato 401; `{ connection_id }` 200; `{ within_seconds: 900 }` con una connessione in scadenza → `refreshed: 1`.
|
|
205
|
+
- A riposo: `access_token_enc` / `refresh_token_enc` nel formato `v1:`, il token in chiaro assente dal documento.
|
|
206
|
+
- `DELETE`: `revoked: true`, la voce dell'integration resta senza `oauth`, le chiamate successive con il vecchio `connection_id` rispondono 404.
|
|
207
|
+
- Non verificato: Google con un client reale (servono credenziali Google Cloud), il percorso 401 e nuovo tentativo contro un server reale (coperto solo con nock), il lato scheduler.
|