@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,207 @@
|
|
|
1
|
+
# MCP OAuth2 — Design
|
|
2
|
+
|
|
3
|
+
Date: 2026-11-10 · Status: server side implemented (commits f4fe91fe..3224546e) and verified end to end against the reference server (§14); tybot, UI and scheduler job pending
|
|
4
|
+
Repos: tiledesk-server, tiledesk-chatbot (tybot). Dashboard / design-studio UI and tiledesk-scheduler-service are follow-ups (§12).
|
|
5
|
+
Branch: `features-2611/oauth2-mcp` (tiledesk-server).
|
|
6
|
+
Reference MCP server: [modelcontextprotocol/example-remote-server](https://github.com/modelcontextprotocol/example-remote-server) ([OAuth guide](https://github.com/modelcontextprotocol/example-remote-server/blob/main/docs/oauth-implementation.md)), MCP Authorization spec `2025-06-18`.
|
|
7
|
+
|
|
8
|
+
## 1. Goal
|
|
9
|
+
|
|
10
|
+
A project admin can connect an MCP server that is protected by OAuth2. tiledesk-server acts as the OAuth client: it runs the authorization code + PKCE flow, stores the tokens encrypted, refreshes them, and gives the chatbot engine a valid access token whenever an AI Prompt action calls that MCP server. Three ways to configure the OAuth client:
|
|
11
|
+
|
|
12
|
+
- **mcp** — the MCP Authorization spec: discovery from the MCP server URL, Dynamic Client Registration. The admin types only the MCP URL.
|
|
13
|
+
- **google** — preset with Google's endpoints and one Tiledesk-owned Google OAuth client from env.
|
|
14
|
+
- **manual** — the admin enters authorization/token endpoints, client id/secret and scopes (any OAuth2 provider without discovery).
|
|
15
|
+
|
|
16
|
+
## 2. Decisions (user, 2026-11-10)
|
|
17
|
+
|
|
18
|
+
1. Tokens live in the database. The chatbot calls a server endpoint that returns the access token read from the DB. A scheduler, later, calls a server API that refreshes and saves tokens in the DB.
|
|
19
|
+
2. Refresh strategy for now: **lazy** — the token endpoint refreshes when the access token is about to expire. The scheduler-facing refresh API is built now; registering the scheduler job is a follow-up.
|
|
20
|
+
3. Google: one Tiledesk Google Cloud OAuth client (`MCP_OAUTH_GOOGLE_CLIENT_ID` / `_SECRET`). No per-project client.
|
|
21
|
+
4. Scope of this round: server phases 1–3 (store + flow + runtime token) plus the refresh API, and the tybot change that consumes the token endpoint.
|
|
22
|
+
5. OAuth client code is written with axios. No `@modelcontextprotocol/sdk` dependency.
|
|
23
|
+
|
|
24
|
+
## 3. Current state (verified 2026-11-10)
|
|
25
|
+
|
|
26
|
+
- `services/mcpService.js` handles auth via `customHeaders` or legacy `auth` (bearer / api-key / basic). `buildServerConfig` rejects an `oauth` object: *"OAuth2 authentication is not supported yet"*.
|
|
27
|
+
- MCP servers are stored in the `mcp` integration (`models/integrations.js`, `value.servers[]`). Custom servers are keyed by `url`, native ones by `nativeId` (`findServerIndex`).
|
|
28
|
+
- `GET /:projectid/integration*` is mongoose-cached for `cacheUtil.longTTL` (`project:<id>:integrations`) and returns `customHeaders[].value` unmasked (`maskIntegrationSecrets` masks only `apikey`, `api_key`, `token`, `secret`, `client_secret`, `password`). So a token must not be written into the integration.
|
|
29
|
+
- tybot `DirAiPrompt.js` reads `/integration/name/mcp` with the bot token on every run, turns `customHeaders` into `headers` (`arrayToObject`, `enrichServersFromIntegration`) and forwards them to the LLM backend.
|
|
30
|
+
- `/:projectid/mcp` is mounted with `passport basic|jwt`, `validtoken`, `roleChecker.hasRoleOrTypes('admin', ['bot','subscription'])`.
|
|
31
|
+
- Internal token-protected endpoints follow `/webhook/scheduled-start`: header `x-auth-token`, `crypto.timingSafeEqual` against an env token, 503 when not configured.
|
|
32
|
+
- `TdCache` has `setNX(key, value, ttlSeconds)`, `setJSON`, `getJSON`, `del`.
|
|
33
|
+
- `utils/logRedactor.js` redacts keys `^(…|token|…|authorization|x-auth-token|…)$` (anchored: `access_token`, `refresh_token` are **not** covered) and `Bearer …` strings.
|
|
34
|
+
- `routes/urlPreview.js` has a hostname-regex private-IP check only (no DNS resolution).
|
|
35
|
+
- Node 18.19, axios, nock, mocha + chai-http available.
|
|
36
|
+
|
|
37
|
+
## 4. Data model (tiledesk-server)
|
|
38
|
+
|
|
39
|
+
New collection `mcp_oauth_connections` (`models/mcpOAuthConnection.js`):
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
{
|
|
43
|
+
id_project: String (index),
|
|
44
|
+
mode: 'mcp' | 'google' | 'manual',
|
|
45
|
+
server_url: String, // MCP server URL = OAuth resource (RFC 8707)
|
|
46
|
+
name: String, // display name
|
|
47
|
+
status: 'pending' | 'active' | 'needs_reauth' | 'revoked',
|
|
48
|
+
// OAuth client
|
|
49
|
+
client_id: String,
|
|
50
|
+
client_secret_enc: String, // encrypted, absent for public clients / google (env)
|
|
51
|
+
client_registered_at: Date, // DCR only
|
|
52
|
+
// endpoints (discovered, preset or manual)
|
|
53
|
+
resource: String, // mcp mode: `resource` of the protected resource metadata (may be the origin, not 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
|
+
// tokens
|
|
62
|
+
access_token_enc: String,
|
|
63
|
+
refresh_token_enc: String,
|
|
64
|
+
token_type: String, // 'Bearer'
|
|
65
|
+
expires_at: Date, // null when the provider sends no expires_in
|
|
66
|
+
granted_scopes: [String],
|
|
67
|
+
last_refresh_at: Date,
|
|
68
|
+
last_error: { code: String, message: String, at: Date },
|
|
69
|
+
created_by: String, // user id that started the flow
|
|
70
|
+
createdAt, updatedAt
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Index `{ id_project: 1, server_url: 1 }` unique: one connection per MCP server per project.
|
|
75
|
+
|
|
76
|
+
The integration server entry gains a reference only (no secrets):
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
oauth: { connection_id: String, mode: 'mcp'|'google'|'manual' }
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Encryption: AES-256-GCM, key `MCP_OAUTH_ENCRYPTION_KEY` (32 bytes, base64). Stored format `v1:<iv b64>:<tag b64>:<ciphertext b64>`. Never returned by any API except the token endpoint (§7), which returns only the access token.
|
|
83
|
+
|
|
84
|
+
## 5. Configuration
|
|
85
|
+
|
|
86
|
+
| Env | Purpose |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `MCP_OAUTH_ENCRYPTION_KEY` | Required. Without it every OAuth route answers 503 `"MCP OAuth is not available on this installation"`. |
|
|
89
|
+
| `MCP_OAUTH_REDIRECT_BASE_URL` | Public base URL of the server; redirect URI = `<base>/oauth2/mcp/callback`. Falls back to `API_URL`. |
|
|
90
|
+
| `MCP_OAUTH_RETURN_ORIGINS` | Comma-separated origins allowed as `return_url` (dashboard / design-studio). |
|
|
91
|
+
| `MCP_OAUTH_GOOGLE_CLIENT_ID`, `MCP_OAUTH_GOOGLE_CLIENT_SECRET` | Google preset. Without them, `mode: 'google'` answers 503. |
|
|
92
|
+
| `MCP_OAUTH_REFRESH_TOKEN` | `x-auth-token` of the scheduler refresh API. Without it the API answers 503. |
|
|
93
|
+
| `MCP_OAUTH_ALLOW_INSECURE_URLS` | `true` only in dev/test: allows `http://` and private/loopback hosts (needed for the reference server on `localhost:3232`). |
|
|
94
|
+
|
|
95
|
+
## 6. Authorization flow
|
|
96
|
+
|
|
97
|
+
1. **Start** — `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), then DCR if no stored client for that server (§6.2).
|
|
99
|
+
- `google`: endpoints `https://accounts.google.com/o/oauth2/v2/auth`, `https://oauth2.googleapis.com/token`, `https://oauth2.googleapis.com/revoke`; extra params `access_type=offline`, `prompt=consent`, `include_granted_scopes=true`; `scopes` required.
|
|
100
|
+
- `manual`: endpoints and client from the body (client secret encrypted).
|
|
101
|
+
- Upserts the connection (`status: 'pending'` when new; an `active` connection stays usable until the new flow completes).
|
|
102
|
+
- Generates `state` (32 random bytes, base64url) and `code_verifier` (64 chars), `code_challenge = base64url(sha256(verifier))`, method `S256`.
|
|
103
|
+
- Stores `mcp_oauth:state:<state>` → `{ id_project, connection_id, code_verifier, return_url, user_id }` in Redis, TTL 600 s.
|
|
104
|
+
- Returns `{ authorization_url, connection_id }`. URL params: `response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `state`, `scope` (space-joined, when any), `resource=<server_url>` (mcp mode).
|
|
105
|
+
2. **Callback** — `GET /oauth2/mcp/callback?code&state` (public, mounted before the `/:projectid` routers).
|
|
106
|
+
- Reads and **deletes** the state (single use). Missing/expired → 400 page.
|
|
107
|
+
- `error` param from the provider → connection `last_error`, redirect `return_url?mcp_oauth=error&error=<code>`.
|
|
108
|
+
- Exchanges the code at the token endpoint (`grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier`, `resource` in mcp mode, client auth per `token_endpoint_auth_method`).
|
|
109
|
+
- Saves tokens encrypted, `expires_at = now + expires_in`, `status: 'active'`, clears `last_error`.
|
|
110
|
+
- Redirects to `return_url?mcp_oauth=success&connection_id=<id>`; without `return_url`, a minimal HTML page "Connected, you can close this window".
|
|
111
|
+
3. **Use** — the admin then saves the MCP server with `oauth.connection_id` (`POST /:projectid/mcp/servers`); `mcpService` uses the token for connect / tools discovery (§8).
|
|
112
|
+
|
|
113
|
+
### 6.1 Discovery (mode `mcp`)
|
|
114
|
+
|
|
115
|
+
1. `POST <server_url>` with an `initialize` request and no auth. Expect 401 with `WWW-Authenticate: Bearer resource_metadata="<url>"`.
|
|
116
|
+
2. Protected Resource Metadata (RFC 9728): the `resource_metadata` URL, else `<origin>/.well-known/oauth-protected-resource<path>`, else `<origin>/.well-known/oauth-protected-resource`. Take `authorization_servers[0]`, and `scopes_supported` as default scopes when none are given.
|
|
117
|
+
3. Authorization Server Metadata: `<issuer>/.well-known/oauth-authorization-server` (RFC 8414, with path insertion when the issuer has a path), else `/.well-known/openid-configuration`. Requires `authorization_endpoint`, `token_endpoint`; `code_challenge_methods_supported` must include `S256` when present.
|
|
118
|
+
4. If the server answers 200 to the unauthenticated initialize, discovery fails with 400 `"This MCP server does not require OAuth"`.
|
|
119
|
+
|
|
120
|
+
### 6.2 Dynamic Client Registration (mode `mcp`)
|
|
121
|
+
|
|
122
|
+
- `POST registration_endpoint` with `{ client_name: 'Tiledesk', redirect_uris: [<redirect uri>], grant_types: ['authorization_code','refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'client_secret_post' }`.
|
|
123
|
+
- Store `client_id`, `client_secret` (encrypted), the returned `token_endpoint_auth_method`, `client_registered_at`.
|
|
124
|
+
- No `registration_endpoint` → 400 `"This MCP server does not support dynamic client registration; use mode 'manual'"`.
|
|
125
|
+
- The registered client is reused by later flows of the same connection. A token endpoint answer `invalid_client` drops the stored client so the next authorize registers again (the reference server expires clients after 30 days).
|
|
126
|
+
|
|
127
|
+
## 7. Runtime token and refresh
|
|
128
|
+
|
|
129
|
+
`oauthTokenService.getAccessToken(connection)`:
|
|
130
|
+
|
|
131
|
+
- `status !== 'active'` → error `needs_reauth` (409).
|
|
132
|
+
- `expires_at` absent or more than `REFRESH_WINDOW_S = 300` s away → decrypt and return.
|
|
133
|
+
- Otherwise refresh:
|
|
134
|
+
- Lock `mcp_oauth:refresh_lock:<id>` with `setNX`, TTL 30 s.
|
|
135
|
+
- Not acquired → poll the DB every 250 ms for up to 5 s for a newer `last_refresh_at`; then return the token if still valid, else 503.
|
|
136
|
+
- Acquired → reload the connection, `grant_type=refresh_token` (+ `resource` in mcp mode). Save the new access token; save the new refresh token **only when one is returned** (Google never rotates, the reference server does). Release the lock.
|
|
137
|
+
- `invalid_grant` → `status: 'needs_reauth'`, `last_error`, 409. `invalid_client` → also drop the DCR client (§6.2). Network/5xx → `last_error`, 503, status unchanged.
|
|
138
|
+
- No refresh token and the access token expired → `needs_reauth`.
|
|
139
|
+
|
|
140
|
+
Endpoints:
|
|
141
|
+
|
|
142
|
+
- `GET /:projectid/mcp/oauth/connections/:id/token` — **bot or subscription callers only** (an admin JWT gets 403, so tokens never reach the dashboard). 200 `{ access_token, token_type, expires_at }`.
|
|
143
|
+
- `POST /:projectid/mcp/oauth/connections/:id/refresh` — admin; forces a refresh, returns the public connection.
|
|
144
|
+
- `POST /webhook/mcp-oauth/refresh` — scheduler; header `x-auth-token: $MCP_OAUTH_REFRESH_TOKEN`. Body `{ connection_id }` refreshes one and answers 200 `{ success, connection_id, expires_at }` (404 unknown, 409 `needs_reauth`); `{ within_seconds }` (default 900, max 86400) refreshes every `active` connection with a refresh token and `expires_at` within that window, sequentially, each failure isolated. 200 `{ success, refreshed, failed, needs_reauth }`; 400 when `within_seconds` is not an integer in 60..86400. 401 bad token, 503 not configured.
|
|
145
|
+
|
|
146
|
+
## 8. mcpService changes
|
|
147
|
+
|
|
148
|
+
- `serverConfig` gains `oauth: { connection_id }`. `applyRequestHeaders` becomes async-aware through a new `resolveRequestHeaders(serverConfig)`: when `oauth.connection_id` is set it loads the connection (same `id_project`), gets the token and sets `Authorization: Bearer <token>`, overriding any `Authorization` from `customHeaders`.
|
|
149
|
+
- `sendJSONRPCRequest`: a 401 from an OAuth-backed server triggers one forced refresh and one retry.
|
|
150
|
+
- `buildServerConfig` accepts `oauth.connection_id` (rejects the old `oauth` shape with the current message). `normalizeMcpServerEntry` copies `oauth: { connection_id, mode }` into the stored entry after checking the connection belongs to the project.
|
|
151
|
+
- `getCacheKey` includes the connection id so sessions are not shared across connections.
|
|
152
|
+
- Decided during implementation: the bearer is sent only when the connection's `server_url` equals the requested URL (normalized), else 400. Without it an admin could point a connection of server A at server B and hand B the token of A.
|
|
153
|
+
- Decided during implementation: native entries with `oauth` answer 400. Native URLs are never exposed, so the admin cannot run `authorize` on them; supporting them needs `authorize` to accept a `nativeId` (§12).
|
|
154
|
+
- OAuth errors keep their status through `sendJSONRPCRequest` and `routes/mcp.js` (404, 409, 503) instead of the generic 500.
|
|
155
|
+
|
|
156
|
+
## 9. Connection management API (admin)
|
|
157
|
+
|
|
158
|
+
- `GET /:projectid/mcp/oauth/connections` — public shape: `{ _id, mode, server_url, name, status, scopes, granted_scopes, expires_at, last_refresh_at, last_error, issuer, createdAt, updatedAt }`. No secrets, no `client_id` for google.
|
|
159
|
+
- `GET /:projectid/mcp/oauth/connections/:id` — same shape.
|
|
160
|
+
- `DELETE /:projectid/mcp/oauth/connections/:id` — best-effort revocation (refresh token, then access token) at `revocation_endpoint`, delete the connection, remove `oauth` from integration entries that reference it (they stay, unauthenticated) and emit `integration.update`. 200 `{ success: true, revoked: Boolean }`.
|
|
161
|
+
|
|
162
|
+
## 10. Security
|
|
163
|
+
|
|
164
|
+
- PKCE S256 always; `state` single-use, 10-min TTL, bound to project and user.
|
|
165
|
+
- `return_url` origin must be in `MCP_OAUTH_RETURN_ORIGINS`, else 400 at authorize.
|
|
166
|
+
- Outbound URL guard (`utils/outboundUrlGuard.js`) for every user-influenced URL (server URL, metadata, endpoints from discovery or manual): `https:` only, DNS-resolved addresses must not be loopback, private, link-local, CGNAT, ULA or unspecified; `maxRedirects: 0`; 10 s timeout; response bodies ≤ 1 MB. `MCP_OAUTH_ALLOW_INSECURE_URLS=true` disables it.
|
|
167
|
+
- Secrets encrypted at rest; `logRedactor` gains `access_token`, `refresh_token`, `code_verifier`, `code`, `client_secret`; `maskIntegrationSecrets` unchanged (no secrets in the integration).
|
|
168
|
+
- Token endpoint reachable only with bot/subscription credentials of the same project.
|
|
169
|
+
|
|
170
|
+
## 11. Errors (summary)
|
|
171
|
+
|
|
172
|
+
| Case | Status |
|
|
173
|
+
|---|---|
|
|
174
|
+
| Feature env missing | 503 |
|
|
175
|
+
| Bad body / discovery or DCR not supported / return_url not allowed | 400 |
|
|
176
|
+
| Connection of another project or missing | 404 |
|
|
177
|
+
| Admin calling the token endpoint | 403 |
|
|
178
|
+
| Connection `needs_reauth` / `revoked` / `pending` on token | 409 `{ success: false, error: <message>, code: 'needs_reauth' }` |
|
|
179
|
+
| OAuth connection used for another server URL | 400 |
|
|
180
|
+
| Provider unreachable or 5xx | 503 (502 at authorize / callback) |
|
|
181
|
+
|
|
182
|
+
## 12. Follow-ups (not in this round)
|
|
183
|
+
|
|
184
|
+
- **Scheduler job**: one global cron (every 10–15 min) in tiledesk-scheduler-service calling `POST /webhook/mcp-oauth/refresh` with `{ within_seconds: 900 }`. Needs a new target (or a generic HTTP target) in the scheduler; contract not verified (repo not accessible from here). Keeps refresh tokens alive for providers with short idle expiry (the reference server: 7 days) and flags `needs_reauth` early.
|
|
185
|
+
- **UI** (dashboard / design-studio): "Connect" button opening `authorization_url` in a popup, reading `mcp_oauth=success|error` on `return_url`, showing status and "Reconnect".
|
|
186
|
+
- **Google verification**: sensitive/restricted scopes (Gmail, Drive) need Google app verification (restricted: CASA assessment); in "Testing" publishing status refresh tokens expire after 7 days.
|
|
187
|
+
- Native MCP servers with OAuth: `authorize` accepting a `nativeId` (the URL stays hidden), then catalog entries with a default `oauth` mode/scopes.
|
|
188
|
+
|
|
189
|
+
## 13. Testing
|
|
190
|
+
|
|
191
|
+
- Unit: crypto round-trip and tamper detection; PKCE challenge; discovery URL construction (with and without path); URL guard.
|
|
192
|
+
- Route tests with nock for discovery, DCR, token, refresh, revoke; Redis for state/lock.
|
|
193
|
+
- Concurrency: two parallel token requests on an expiring token → exactly one refresh call.
|
|
194
|
+
- Manual end-to-end against the reference server (`npm run dev:internal`, port 3232) with `MCP_OAUTH_ALLOW_INSECURE_URLS=true`.
|
|
195
|
+
|
|
196
|
+
## 14. Verification (2026-11-10)
|
|
197
|
+
|
|
198
|
+
- Automated: 128 mocha tests (`test/mcpOAuthUtils`, `mcpOAuthDiscovery`, `mcpOAuthService`, `mcpOAuthRoute`, `mcpServiceOAuth`, `nativemcp`), run on Node 22 with the enterprise modules removed from `node_modules`. Providers and MCP servers are mocked with nock; Mongo and Redis are real (local).
|
|
199
|
+
- Manual end to end against the reference server (`npm run dev:internal`, port 3232, internal auth mode) and tiledesk-server on port 3000 with `MCP_OAUTH_ALLOW_INSECURE_URLS=true` and a dedicated database. Nothing mocked; the consent page of the reference server's mock identity provider was driven with curl. Results:
|
|
200
|
+
- `authorize` in mode `mcp`: discovery, dynamic registration (`token_endpoint_auth_method: none`, no secret) and the `resource` parameter `http://localhost:3232/`.
|
|
201
|
+
- Callback: 302 to `return_url` with `mcp_oauth=success`; the connection is `active` and the public shape has no secrets.
|
|
202
|
+
- `POST /mcp/connect` and `/mcp/servers` with `oauth.connection_id`: 9 tools; the saved entry holds `{ connection_id, mode: 'mcp' }`.
|
|
203
|
+
- `/token`: admin 403, bot JWT 200. With `expires_at` moved to the past the next call refreshed and returned a new access token, and tools were listed with it. The reference server rotates refresh tokens and three refreshes in a row succeeded.
|
|
204
|
+
- Scheduler webhook: wrong token 401; `{ connection_id }` 200; `{ within_seconds: 900 }` with one connection due → `refreshed: 1`.
|
|
205
|
+
- At rest: `access_token_enc` / `refresh_token_enc` in `v1:` format, the plaintext token absent from the document.
|
|
206
|
+
- `DELETE`: `revoked: true`, the integration entry kept without `oauth`, later calls with the old `connection_id` answer 404.
|
|
207
|
+
- Not verified: Google with a real client (needs Google Cloud credentials), the 401-then-retry path against a live server (covered only by nock), the scheduler side.
|
package/jobs.js
CHANGED
|
@@ -120,6 +120,19 @@ function startJobListeners(tdCache) {
|
|
|
120
120
|
jobsManager.listenMultiWorker(require('@tiledesk/tiledesk-multi-worker'));
|
|
121
121
|
}
|
|
122
122
|
|
|
123
|
+
/**
|
|
124
|
+
* Conversations closed here (the scheduler's unresponsive-bot close, say) emit request.close in this process only:
|
|
125
|
+
* without the publisher their executions never end. Publish only: the audit consumer runs on the API pods.
|
|
126
|
+
* Off (no listeners) when EXECUTIONS_AMQP_URL is unset.
|
|
127
|
+
*/
|
|
128
|
+
function startExecutionsPublisher() {
|
|
129
|
+
try {
|
|
130
|
+
require('./pubmodules/executions-publisher').listen({ audit: false });
|
|
131
|
+
} catch (err) {
|
|
132
|
+
winston.info("Jobs error initializing executionsPublisher module", err);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
123
136
|
function startAnalyticsPublisher() {
|
|
124
137
|
try {
|
|
125
138
|
require('./pubmodules/analytics-publisher').listen();
|
|
@@ -150,6 +163,8 @@ async function main() {
|
|
|
150
163
|
|
|
151
164
|
startAnalyticsPublisher();
|
|
152
165
|
|
|
166
|
+
startExecutionsPublisher();
|
|
167
|
+
|
|
153
168
|
winston.info("Jobs started");
|
|
154
169
|
|
|
155
170
|
// Keeps the process alive.
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
const mongoose = require('mongoose');
|
|
2
|
+
const Schema = mongoose.Schema;
|
|
3
|
+
const winston = require('../config/winston');
|
|
4
|
+
|
|
5
|
+
const McpOAuthConnectionSchema = new Schema({
|
|
6
|
+
id_project: {
|
|
7
|
+
type: String,
|
|
8
|
+
required: true,
|
|
9
|
+
index: true
|
|
10
|
+
},
|
|
11
|
+
mode: {
|
|
12
|
+
type: String,
|
|
13
|
+
enum: ['mcp', 'google', 'manual'],
|
|
14
|
+
required: true
|
|
15
|
+
},
|
|
16
|
+
server_url: {
|
|
17
|
+
type: String,
|
|
18
|
+
required: true
|
|
19
|
+
},
|
|
20
|
+
name: {
|
|
21
|
+
type: String
|
|
22
|
+
},
|
|
23
|
+
status: {
|
|
24
|
+
type: String,
|
|
25
|
+
enum: ['pending', 'active', 'needs_reauth', 'revoked'],
|
|
26
|
+
default: 'pending'
|
|
27
|
+
},
|
|
28
|
+
client_id: {
|
|
29
|
+
type: String
|
|
30
|
+
},
|
|
31
|
+
client_secret_enc: {
|
|
32
|
+
type: String
|
|
33
|
+
},
|
|
34
|
+
client_registered_at: {
|
|
35
|
+
type: Date
|
|
36
|
+
},
|
|
37
|
+
resource: {
|
|
38
|
+
type: String
|
|
39
|
+
},
|
|
40
|
+
issuer: {
|
|
41
|
+
type: String
|
|
42
|
+
},
|
|
43
|
+
authorization_endpoint: {
|
|
44
|
+
type: String
|
|
45
|
+
},
|
|
46
|
+
token_endpoint: {
|
|
47
|
+
type: String
|
|
48
|
+
},
|
|
49
|
+
revocation_endpoint: {
|
|
50
|
+
type: String
|
|
51
|
+
},
|
|
52
|
+
registration_endpoint: {
|
|
53
|
+
type: String
|
|
54
|
+
},
|
|
55
|
+
token_endpoint_auth_method: {
|
|
56
|
+
type: String,
|
|
57
|
+
enum: ['client_secret_basic', 'client_secret_post', 'none']
|
|
58
|
+
},
|
|
59
|
+
scopes: {
|
|
60
|
+
type: [String],
|
|
61
|
+
default: []
|
|
62
|
+
},
|
|
63
|
+
access_token_enc: {
|
|
64
|
+
type: String
|
|
65
|
+
},
|
|
66
|
+
refresh_token_enc: {
|
|
67
|
+
type: String
|
|
68
|
+
},
|
|
69
|
+
token_type: {
|
|
70
|
+
type: String
|
|
71
|
+
},
|
|
72
|
+
expires_at: {
|
|
73
|
+
type: Date
|
|
74
|
+
},
|
|
75
|
+
granted_scopes: {
|
|
76
|
+
type: [String],
|
|
77
|
+
default: []
|
|
78
|
+
},
|
|
79
|
+
last_refresh_at: {
|
|
80
|
+
type: Date
|
|
81
|
+
},
|
|
82
|
+
last_error: {
|
|
83
|
+
code: String,
|
|
84
|
+
message: String,
|
|
85
|
+
at: Date
|
|
86
|
+
},
|
|
87
|
+
created_by: {
|
|
88
|
+
type: String
|
|
89
|
+
}
|
|
90
|
+
}, {
|
|
91
|
+
timestamps: true
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
McpOAuthConnectionSchema.index({ id_project: 1, server_url: 1 }, { unique: true });
|
|
95
|
+
// refreshDue: active connections expiring within the window
|
|
96
|
+
McpOAuthConnectionSchema.index({ status: 1, expires_at: 1 });
|
|
97
|
+
|
|
98
|
+
const PUBLIC_FIELDS = [
|
|
99
|
+
'_id', 'mode', 'server_url', 'name', 'status', 'scopes', 'granted_scopes', 'expires_at',
|
|
100
|
+
'last_refresh_at', 'last_error', 'issuer', 'createdAt', 'updatedAt'
|
|
101
|
+
];
|
|
102
|
+
|
|
103
|
+
/** The connection as returned by the API: no client credentials, no tokens. */
|
|
104
|
+
McpOAuthConnectionSchema.statics.toPublic = function (connection) {
|
|
105
|
+
if (!connection) {
|
|
106
|
+
return connection;
|
|
107
|
+
}
|
|
108
|
+
const source = connection.toObject ? connection.toObject() : connection;
|
|
109
|
+
const result = {};
|
|
110
|
+
for (const field of PUBLIC_FIELDS) {
|
|
111
|
+
if (source[field] !== undefined) {
|
|
112
|
+
result[field] = source[field];
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
return result;
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
const McpOAuthConnection = mongoose.model('mcp_oauth_connection', McpOAuthConnectionSchema);
|
|
119
|
+
|
|
120
|
+
// Created explicitly because MONGOOSE_AUTOINDEX can be off: without it a project could
|
|
121
|
+
// end up with two connections for the same MCP server.
|
|
122
|
+
McpOAuthConnection.collection
|
|
123
|
+
.createIndex({ id_project: 1, server_url: 1 }, { unique: true })
|
|
124
|
+
.then(function () {
|
|
125
|
+
winston.verbose('McpOAuthConnection unique index ensured');
|
|
126
|
+
})
|
|
127
|
+
.catch(function (err) {
|
|
128
|
+
winston.error('McpOAuthConnection unique index not created: ', err);
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
module.exports = McpOAuthConnection;
|
package/models/request.js
CHANGED
|
@@ -215,6 +215,14 @@ var RequestSchema = new Schema({
|
|
|
215
215
|
rating: {
|
|
216
216
|
type: Number,
|
|
217
217
|
required: false,
|
|
218
|
+
min: 1,
|
|
219
|
+
max: 5,
|
|
220
|
+
validate: {
|
|
221
|
+
validator: function (v) {
|
|
222
|
+
return v == null || Number.isInteger(v);
|
|
223
|
+
},
|
|
224
|
+
message: 'rating must be an integer between 1 and 5'
|
|
225
|
+
}
|
|
218
226
|
},
|
|
219
227
|
rating_message: {
|
|
220
228
|
type: String,
|
package/package.json
CHANGED
|
@@ -189,6 +189,131 @@ function kbContentLabel(activity) {
|
|
|
189
189
|
return 'content';
|
|
190
190
|
}
|
|
191
191
|
|
|
192
|
+
const EXECUTION_VERBS = {
|
|
193
|
+
// "stop" is shown as "pause" (feedback 2026-11-13): the verbs keep their names, the sentences say pause.
|
|
194
|
+
// enMode/itMode follow "<id> of <agent>": the soft pause waits for the current action, the hard one does not.
|
|
195
|
+
EXECUTION_STOP_SOFT: { en: 'paused execution', it: "ha messo in pausa l'esecuzione",
|
|
196
|
+
enTried: 'tried to pause execution', itTried: "ha provato a mettere in pausa l'esecuzione",
|
|
197
|
+
enMode: 'after the current action', itMode: "dopo l'azione corrente" },
|
|
198
|
+
EXECUTION_STOP_HARD: { en: 'paused execution', it: "ha messo in pausa l'esecuzione",
|
|
199
|
+
enTried: 'tried to pause execution', itTried: "ha provato a mettere in pausa l'esecuzione",
|
|
200
|
+
enMode: 'now', itMode: 'subito' },
|
|
201
|
+
EXECUTION_DESTROY: { en: 'destroyed execution', it: "ha eliminato l'esecuzione",
|
|
202
|
+
enTried: 'tried to destroy execution', itTried: "ha provato a eliminare l'esecuzione" },
|
|
203
|
+
EXECUTION_RESUME: { en: 'resumed execution', it: "ha ripreso l'esecuzione",
|
|
204
|
+
enTried: 'tried to resume execution', itTried: "ha provato a riprendere l'esecuzione" },
|
|
205
|
+
EXECUTION_START_NEW: { en: 'started a new run of execution', it: 'ha avviato una nuova esecuzione da',
|
|
206
|
+
enTried: 'tried to start a new run of execution', itTried: 'ha provato ad avviare una nuova esecuzione da' },
|
|
207
|
+
EXECUTION_DATA_ACCESS: { en: 'viewed the data of execution', it: "ha visualizzato i dati dell'esecuzione" },
|
|
208
|
+
EXECUTION_DATA_ACCESS_DENIED: { en: 'was denied access to the data of execution', it: "non ha ottenuto l'accesso ai dati dell'esecuzione" },
|
|
209
|
+
EXECUTION_RETENTION_UPDATE: { en: 'changed executions retention', it: 'ha modificato la conservazione delle esecuzioni' },
|
|
210
|
+
EXECUTION_STOP_NOTICE_UPDATE: { en: 'changed the executions pause notice', it: "ha modificato l'avviso di esecuzione in pausa" }
|
|
211
|
+
};
|
|
212
|
+
|
|
213
|
+
// "on, custom text" / "off" / "on, default text": the setting after the change (en / it)
|
|
214
|
+
function stopNoticeState(activity, it) {
|
|
215
|
+
const s = activity.actionObj && activity.actionObj.stop_notice;
|
|
216
|
+
const after = s && (s.after || s);
|
|
217
|
+
if (!after || typeof after.enabled !== 'boolean') return '';
|
|
218
|
+
if (!after.enabled) return it ? 'disattivato' : 'off';
|
|
219
|
+
const custom = typeof after.text === 'string' && after.text.trim() !== '';
|
|
220
|
+
return it ? (custom ? 'attivo, testo personalizzato' : 'attivo, testo predefinito') : (custom ? 'on, custom text' : 'on, default text');
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
// "trace 90 → 30 days, data 30 → 7 days": only the parts that changed (en); "tracce ... giorni, dati ... giorni" (it)
|
|
224
|
+
function retentionChanges(activity, it) {
|
|
225
|
+
const r = (activity.actionObj && activity.actionObj.retention) || {};
|
|
226
|
+
const before = r.before || {};
|
|
227
|
+
const after = r.after || {};
|
|
228
|
+
const parts = [];
|
|
229
|
+
[['trace_days', 'trace', 'tracce'], ['data_days', 'data', 'dati']].forEach(function (k) {
|
|
230
|
+
if (before[k[0]] !== after[k[0]]) {
|
|
231
|
+
parts.push((it ? k[2] : k[1]) + ' ' + before[k[0]] + ' → ' + after[k[0]] + (it ? ' giorni' : ' days'));
|
|
232
|
+
}
|
|
233
|
+
});
|
|
234
|
+
return parts.join(', ');
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
// actionObj.result is 'accepted' or 'rejected:<status>' (a 409 is audited too); no result (older rows) = accepted
|
|
238
|
+
function executionRejection(activity) {
|
|
239
|
+
const result = activity && activity.actionObj && activity.actionObj.result;
|
|
240
|
+
if (typeof result !== 'string' || !/^rejected(:|$)/.test(result)) {
|
|
241
|
+
return null;
|
|
242
|
+
}
|
|
243
|
+
return { reason: result.indexOf(':') >= 0 ? result.substring(result.indexOf(':') + 1) : '' };
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
// The status in "(rejected: <status>)" as the dashboard names it: stopped/stopping read paused/pausing.
|
|
247
|
+
const SHOWN_STATUS = { stopped: 'paused', stopping: 'pausing' };
|
|
248
|
+
function shownStatus(status) {
|
|
249
|
+
return Object.prototype.hasOwnProperty.call(SHOWN_STATUS, status) ? SHOWN_STATUS[status] : status;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
function isExecutionVerb(verb) {
|
|
253
|
+
return Object.prototype.hasOwnProperty.call(EXECUTION_VERBS, verb);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
// "<actor> paused execution <short id> of <agent> after the current action" (en) /
|
|
257
|
+
// "<actor> ha messo in pausa l'esecuzione <id> di <agent> dopo l'azione corrente" (it); a rejected control:
|
|
258
|
+
// "<actor> tried to pause execution <id> of <agent> now (rejected: <status>)" /
|
|
259
|
+
// "<actor> ha provato a mettere in pausa l'esecuzione <id> di <agent> subito (rifiutato: <status>)". The dashboard renders the same en sentence.
|
|
260
|
+
function buildExecutionMessage(activity, lang) {
|
|
261
|
+
if (!activity || !isExecutionVerb(activity.verb)) {
|
|
262
|
+
return null;
|
|
263
|
+
}
|
|
264
|
+
const it = lang === 'it';
|
|
265
|
+
const phrases = EXECUTION_VERBS[activity.verb];
|
|
266
|
+
if (activity.verb === 'EXECUTION_STOP_NOTICE_UPDATE') {
|
|
267
|
+
const state = stopNoticeState(activity, it);
|
|
268
|
+
return actorLabel(activity) + ' ' + (it ? phrases.it : phrases.en) + (state ? ': ' + state : '');
|
|
269
|
+
}
|
|
270
|
+
if (activity.verb === 'EXECUTION_RETENTION_UPDATE') {
|
|
271
|
+
const changes = retentionChanges(activity, it);
|
|
272
|
+
return actorLabel(activity) + ' ' + (it ? phrases.it : phrases.en) + (changes ? ': ' + changes : '');
|
|
273
|
+
}
|
|
274
|
+
// a denied data access is itself the rejection: its sentence has no "tried"/"(rejected: ...)" form
|
|
275
|
+
let rejected = activity.verb === 'EXECUTION_DATA_ACCESS_DENIED' ? null : executionRejection(activity);
|
|
276
|
+
// a start new whose refire got no answer: the run may have started, so it reads as started, flagged unconfirmed
|
|
277
|
+
const unconfirmed = !!rejected && activity.verb === 'EXECUTION_START_NEW' && rejected.reason === 'refire_unconfirmed';
|
|
278
|
+
if (unconfirmed) {
|
|
279
|
+
rejected = null;
|
|
280
|
+
}
|
|
281
|
+
const object = (activity.target && activity.target.object) || {};
|
|
282
|
+
const executionId = String((activity.target && activity.target.id) || '');
|
|
283
|
+
// the random tail of a uuid v7 (its head is the timestamp, shared by runs started close together); the same
|
|
284
|
+
// short id the executions destroy confirmation and the dashboard use
|
|
285
|
+
const shortId = executionId.replace(/-/g, '').slice(-6);
|
|
286
|
+
const agent = object.agent_name || (activity.related && activity.related.name) || object.agent_id || 'agent';
|
|
287
|
+
const phrase = rejected ? (it ? phrases.itTried : phrases.enTried) : (it ? phrases.it : phrases.en);
|
|
288
|
+
let message = actorLabel(activity) + ' ' + phrase + ' ' + shortId +
|
|
289
|
+
(it ? ' di ' : ' of ') + agent;
|
|
290
|
+
const mode = it ? phrases.itMode : phrases.enMode;
|
|
291
|
+
if (mode) {
|
|
292
|
+
message += ' ' + mode;
|
|
293
|
+
}
|
|
294
|
+
if (unconfirmed) {
|
|
295
|
+
message += it ? ' (non confermata)' : ' (unconfirmed)';
|
|
296
|
+
}
|
|
297
|
+
if (rejected) {
|
|
298
|
+
message += ' (' + (it ? 'rifiutato' : 'rejected') + (rejected.reason ? ': ' + shownStatus(rejected.reason) : '') + ')';
|
|
299
|
+
}
|
|
300
|
+
const reason = activity.actionObj && activity.actionObj.reason;
|
|
301
|
+
if (reason && activity.verb !== 'EXECUTION_DATA_ACCESS_DENIED') {
|
|
302
|
+
message += ' · "' + reason + '"';
|
|
303
|
+
}
|
|
304
|
+
if (activity.verb === 'EXECUTION_DATA_ACCESS') {
|
|
305
|
+
const scope = (activity.actionObj && activity.actionObj.scope) || {};
|
|
306
|
+
message += ' · ' + (scope.type === 'step' ? (it ? '1 blocco' : '1 block') : (it ? 'intera esecuzione' : 'whole execution'));
|
|
307
|
+
}
|
|
308
|
+
if (activity.verb === 'EXECUTION_DATA_ACCESS_DENIED') {
|
|
309
|
+
const role = activity.actionObj && activity.actionObj.role;
|
|
310
|
+
if (role) {
|
|
311
|
+
message += ' (' + (it ? 'ruolo ' : 'role ') + role + ')';
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
return message;
|
|
315
|
+
}
|
|
316
|
+
|
|
192
317
|
function buildDefaultActivityMessage(activity) {
|
|
193
318
|
if (!activity || !activity.verb) {
|
|
194
319
|
return null;
|
|
@@ -310,6 +435,17 @@ function buildDefaultActivityMessage(activity) {
|
|
|
310
435
|
return actor + ' deleted content ' + kbContentLabel(activity) +
|
|
311
436
|
' from namespace ' + namespaceLabel(activity);
|
|
312
437
|
|
|
438
|
+
case 'EXECUTION_STOP_SOFT':
|
|
439
|
+
case 'EXECUTION_STOP_HARD':
|
|
440
|
+
case 'EXECUTION_DESTROY':
|
|
441
|
+
case 'EXECUTION_RESUME':
|
|
442
|
+
case 'EXECUTION_START_NEW':
|
|
443
|
+
case 'EXECUTION_DATA_ACCESS':
|
|
444
|
+
case 'EXECUTION_DATA_ACCESS_DENIED':
|
|
445
|
+
case 'EXECUTION_RETENTION_UPDATE':
|
|
446
|
+
case 'EXECUTION_STOP_NOTICE_UPDATE':
|
|
447
|
+
return buildExecutionMessage(activity, 'en');
|
|
448
|
+
|
|
313
449
|
default:
|
|
314
450
|
return null;
|
|
315
451
|
}
|
|
@@ -332,5 +468,6 @@ module.exports = {
|
|
|
332
468
|
kbContentLabel,
|
|
333
469
|
resolveParticipantLabel,
|
|
334
470
|
buildDefaultActivityMessage,
|
|
471
|
+
buildExecutionMessage,
|
|
335
472
|
enrichActivityWithMessage
|
|
336
473
|
};
|
|
@@ -228,6 +228,8 @@ ActivitySchema.index({ id_project: 1, createdAt: -1 });
|
|
|
228
228
|
ActivitySchema.index({ id_project: 1, 'actor.id': 1, createdAt: -1 });
|
|
229
229
|
ActivitySchema.index({ id_project: 1, 'target.object.id_user._id': 1, createdAt: -1 });
|
|
230
230
|
ActivitySchema.index({ id_project: 1, involvedUserIds: 1, createdAt: -1 });
|
|
231
|
+
// Idempotency of the execution audit mirror (executions-publisher audit consumer).
|
|
232
|
+
ActivitySchema.index({ 'actionObj.audit_id': 1 }, { unique: true, sparse: true });
|
|
231
233
|
ActivitySchema.index({ createdAt: 1 }, { expireAfterSeconds: expireAfterSeconds });
|
|
232
234
|
|
|
233
235
|
|