@hed-hog/core 0.0.373 → 0.0.375
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/README.md +954 -873
- package/dist/integration-profile/integration-profile.secrets.d.ts.map +1 -1
- package/dist/integration-profile/integration-profile.secrets.js +4 -0
- package/dist/integration-profile/integration-profile.secrets.js.map +1 -1
- package/dist/integration-profile/integration-profile.utils.d.ts +6 -0
- package/dist/integration-profile/integration-profile.utils.d.ts.map +1 -1
- package/dist/integration-profile/integration-profile.utils.js +1 -1
- package/dist/integration-profile/integration-profile.utils.js.map +1 -1
- package/dist/oauth/oauth.controller.d.ts +11 -3
- package/dist/oauth/oauth.controller.d.ts.map +1 -1
- package/dist/oauth/oauth.controller.js +52 -14
- package/dist/oauth/oauth.controller.js.map +1 -1
- package/dist/oauth/oauth.module.d.ts.map +1 -1
- package/dist/oauth/oauth.module.js +4 -0
- package/dist/oauth/oauth.module.js.map +1 -1
- package/dist/oauth/oauth.service.d.ts +38 -2
- package/dist/oauth/oauth.service.d.ts.map +1 -1
- package/dist/oauth/oauth.service.js +122 -5
- package/dist/oauth/oauth.service.js.map +1 -1
- package/dist/oauth/providers/apple.provider.d.ts +34 -0
- package/dist/oauth/providers/apple.provider.d.ts.map +1 -0
- package/dist/oauth/providers/apple.provider.js +197 -0
- package/dist/oauth/providers/apple.provider.js.map +1 -0
- package/dist/oauth/providers/facebook.provider.d.ts +1 -1
- package/dist/oauth/providers/facebook.provider.d.ts.map +1 -1
- package/dist/oauth/providers/facebook.provider.js +3 -2
- package/dist/oauth/providers/facebook.provider.js.map +1 -1
- package/dist/oauth/providers/google.provider.d.ts +1 -1
- package/dist/oauth/providers/google.provider.d.ts.map +1 -1
- package/dist/oauth/providers/google.provider.js +3 -2
- package/dist/oauth/providers/google.provider.js.map +1 -1
- package/dist/oauth/providers/linkedin.provider.d.ts +25 -0
- package/dist/oauth/providers/linkedin.provider.d.ts.map +1 -0
- package/dist/oauth/providers/linkedin.provider.js +99 -0
- package/dist/oauth/providers/linkedin.provider.js.map +1 -0
- package/dist/oauth/providers/microsoft-entra-id.provider.js +1 -1
- package/dist/oauth/providers/microsoft-entra-id.provider.js.map +1 -1
- package/dist/oauth/providers/microsoft.provider.d.ts +1 -1
- package/dist/oauth/providers/microsoft.provider.d.ts.map +1 -1
- package/dist/oauth/providers/microsoft.provider.js +3 -2
- package/dist/oauth/providers/microsoft.provider.js.map +1 -1
- package/dist/pdf/pdf.service.d.ts.map +1 -1
- package/dist/pdf/pdf.service.js +19 -2
- package/dist/pdf/pdf.service.js.map +1 -1
- package/dist/setting/setting.service.d.ts.map +1 -1
- package/dist/setting/setting.service.js +4 -1
- package/dist/setting/setting.service.js.map +1 -1
- package/hedhog/data/integration_provider.yaml +16 -0
- package/hedhog/data/setting_group.yaml +98 -0
- package/hedhog/data/setting_subgroup.yaml +16 -0
- package/hedhog/frontend/app/configurations/[slug]/components/setting-field.tsx.ejs +2 -0
- package/hedhog/frontend/app/dashboard/dashboard.css.ejs +11 -11
- package/hedhog/frontend/app/integration/profiles/page.tsx.ejs +42 -0
- package/hedhog/frontend/app/menu/page.tsx.ejs +1 -1
- package/hedhog/frontend/app/users/user-sheet.tsx.ejs +8 -0
- package/hedhog/frontend/e2e/core.spec.ts.ejs +28 -0
- package/hedhog/frontend/messages/en.json +35 -0
- package/hedhog/frontend/messages/pt.json +35 -0
- package/hedhog/table/user_account.yaml +1 -0
- package/package.json +3 -3
- package/src/access-log/access-log.service.spec.ts +235 -0
- package/src/ai-instruction/ai-prompt-builder.service.spec.ts +250 -0
- package/src/auth/auth.service.spec.ts +891 -0
- package/src/auth/guards/auth.guard.spec.ts +177 -0
- package/src/challenge/challenge.service.spec.ts +334 -0
- package/src/dashboard/dashboard-core/dashboard-core.service.spec.ts +193 -0
- package/src/file/image-optimization.service.spec.ts +283 -0
- package/src/file/provider/provider.factory.spec.ts +111 -0
- package/src/install/install.service.spec.ts +139 -0
- package/src/integration/README.md +2 -0
- package/src/integration/services/event-subscriber.registry.spec.ts +143 -0
- package/src/integration/services/inbox.service.spec.ts +183 -0
- package/src/integration/services/integration-link.service.spec.ts +217 -0
- package/src/integration/services/outbox.service.spec.ts +290 -0
- package/src/integration-profile/integration-credential-crypto.service.spec.ts +289 -0
- package/src/integration-profile/integration-profile.secrets.ts +4 -0
- package/src/integration-profile/integration-profile.utils.spec.ts +332 -0
- package/src/integration-profile/integration-profile.utils.ts +14 -1
- package/src/locale/locale.service.spec.ts +78 -0
- package/src/mail/mail.service.spec.ts +257 -0
- package/src/mcp/guards/mcp-auth.guard.spec.ts +87 -0
- package/src/mcp/guards/mcp-permission.guard.spec.ts +64 -0
- package/src/mcp/mcp-api-key.service.spec.ts +125 -0
- package/src/mcp/mcp-registry.service.spec.ts +96 -0
- package/src/mcp/mcp-server.service.spec.ts +187 -0
- package/src/menu/menu.service.spec.ts +76 -0
- package/src/notification/notification.service.spec.ts +297 -0
- package/src/oauth/oauth.controller.ts +53 -10
- package/src/oauth/oauth.module.ts +4 -0
- package/src/oauth/oauth.service.spec.ts +332 -0
- package/src/oauth/oauth.service.ts +156 -1
- package/src/oauth/providers/apple.provider.ts +175 -0
- package/src/oauth/providers/facebook.provider.ts +3 -2
- package/src/oauth/providers/google.provider.ts +3 -2
- package/src/oauth/providers/linkedin.provider.ts +96 -0
- package/src/oauth/providers/microsoft-entra-id.provider.ts +1 -1
- package/src/oauth/providers/microsoft.provider.ts +3 -2
- package/src/pdf/pdf.service.ts +20 -2
- package/src/role/guards/role.guard.spec.ts +157 -0
- package/src/role/role.service.spec.ts +179 -0
- package/src/session/session.service.spec.ts +376 -0
- package/src/setting/setting.service.spec.ts +316 -0
- package/src/setting/setting.service.ts +4 -1
- package/src/task/task.service.spec.ts +47 -0
- package/src/token/token.service.spec.ts +351 -0
- package/src/user/user.service.spec.ts +256 -0
- package/src/utils/locale-context.spec.ts +22 -0
- package/src/utils/webauthn-origin.spec.ts +73 -0
- package/src/webhook-integration/integration-event-catalog.service.spec.ts +149 -0
package/README.md
CHANGED
|
@@ -1,873 +1,954 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
| POST | `/ai/
|
|
27
|
-
|
|
|
28
|
-
| GET | `/ai/agent
|
|
29
|
-
| GET | `/ai/agent/:
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
| GET | `/auth/
|
|
40
|
-
|
|
|
41
|
-
| POST | `/auth/
|
|
42
|
-
| POST | `/auth/login
|
|
43
|
-
| POST | `/auth/login-email-verification
|
|
44
|
-
| POST | `/auth/
|
|
45
|
-
| POST | `/auth/
|
|
46
|
-
| POST | `/auth/login-
|
|
47
|
-
| POST | `/auth/
|
|
48
|
-
| POST | `/auth/
|
|
49
|
-
| POST | `/auth/webauthn/
|
|
50
|
-
| POST | `/auth/
|
|
51
|
-
| POST | `/auth/
|
|
52
|
-
| POST | `/auth/
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
|
63
|
-
|
|
64
|
-
| GET | `/
|
|
65
|
-
| GET | `/
|
|
66
|
-
| GET | `/
|
|
67
|
-
| GET | `/
|
|
68
|
-
| GET | `/
|
|
69
|
-
| GET | `/
|
|
70
|
-
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
|
75
|
-
|
|
76
|
-
| GET | `/
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
|
81
|
-
|
|
82
|
-
| GET | `/dashboard-core/
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
| GET | `/dashboard-core
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
|
91
|
-
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
|
101
|
-
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
| GET | `/dashboard-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
|
113
|
-
|
|
114
|
-
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
|
123
|
-
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
128
|
-
###
|
|
129
|
-
|
|
130
|
-
|
|
|
131
|
-
|
|
132
|
-
| GET | `/dashboard-role`
|
|
133
|
-
| POST | `/dashboard-role`
|
|
134
|
-
| POST | `/dashboard-role/batch` |
|
|
135
|
-
| DELETE | `/dashboard-role/:id` |
|
|
136
|
-
| DELETE | `/dashboard-role/
|
|
137
|
-
|
|
138
|
-
###
|
|
139
|
-
|
|
140
|
-
|
|
|
141
|
-
|
|
142
|
-
| GET | `/dashboard-
|
|
143
|
-
|
|
|
144
|
-
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
-
|
|
151
|
-
-
|
|
152
|
-
-
|
|
153
|
-
-
|
|
154
|
-
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
token: string; //
|
|
248
|
-
|
|
249
|
-
}
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
- **
|
|
253
|
-
|
|
254
|
-
```ts
|
|
255
|
-
{
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
code: string; //
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
- **
|
|
299
|
-
|
|
300
|
-
```ts
|
|
301
|
-
{
|
|
302
|
-
slug: string;
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
}
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
}
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
}
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
- **
|
|
351
|
-
|
|
352
|
-
```ts
|
|
353
|
-
{
|
|
354
|
-
|
|
355
|
-
role_id: number;
|
|
356
|
-
}
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
- **
|
|
360
|
-
|
|
361
|
-
```ts
|
|
362
|
-
{
|
|
363
|
-
|
|
364
|
-
role_ids: number[];
|
|
365
|
-
}
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
- **
|
|
369
|
-
|
|
370
|
-
```ts
|
|
371
|
-
{
|
|
372
|
-
component_id: number;
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
```
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
}
|
|
425
|
-
```
|
|
426
|
-
|
|
427
|
-
- **
|
|
428
|
-
|
|
429
|
-
```ts
|
|
430
|
-
{
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
-
|
|
459
|
-
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
-
|
|
469
|
-
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
-
|
|
474
|
-
-
|
|
475
|
-
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
###
|
|
493
|
-
|
|
494
|
-
```yaml
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
- id: integer, PK, auto-increment
|
|
498
|
-
-
|
|
499
|
-
-
|
|
500
|
-
-
|
|
501
|
-
-
|
|
502
|
-
-
|
|
503
|
-
|
|
504
|
-
-
|
|
505
|
-
|
|
506
|
-
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
-
|
|
516
|
-
-
|
|
517
|
-
|
|
518
|
-
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
- id
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
- FK
|
|
545
|
-
|
|
546
|
-
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
- id
|
|
555
|
-
|
|
556
|
-
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
- id
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
-
|
|
574
|
-
|
|
575
|
-
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
-
|
|
589
|
-
-
|
|
590
|
-
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
-
|
|
605
|
-
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
-
|
|
620
|
-
-
|
|
621
|
-
|
|
622
|
-
-
|
|
623
|
-
|
|
624
|
-
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
-
|
|
636
|
-
|
|
637
|
-
-
|
|
638
|
-
-
|
|
639
|
-
|
|
640
|
-
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
-
|
|
649
|
-
|
|
650
|
-
-
|
|
651
|
-
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
-
|
|
665
|
-
|
|
666
|
-
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
-
|
|
675
|
-
-
|
|
676
|
-
|
|
677
|
-
-
|
|
678
|
-
|
|
679
|
-
-
|
|
680
|
-
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
-
|
|
691
|
-
|
|
692
|
-
-
|
|
693
|
-
-
|
|
694
|
-
|
|
695
|
-
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
-
|
|
710
|
-
|
|
711
|
-
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
-
|
|
722
|
-
-
|
|
723
|
-
-
|
|
724
|
-
-
|
|
725
|
-
-
|
|
726
|
-
|
|
727
|
-
-
|
|
728
|
-
-
|
|
729
|
-
|
|
730
|
-
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
```
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
-
|
|
776
|
-
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
"
|
|
807
|
-
"
|
|
808
|
-
}
|
|
809
|
-
```
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
```
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
"
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
1
|
+
# @hed-hog/core
|
|
2
|
+
|
|
3
|
+
> **License**: MIT (Open Source) — Core is the only Open Source module of the HedHog Framework; the other modules are Enterprise and require a commercial license. See [LICENSE.md](./LICENSE.md).
|
|
4
|
+
|
|
5
|
+
Learn more about the HedHog Framework at **[hedhog.com](https://hedhog.com)**.
|
|
6
|
+
|
|
7
|
+
## 1. Module overview
|
|
8
|
+
|
|
9
|
+
The `@hed-hog/core` module is the core of the HedHog monorepo, responsible for providing essential core functionality for the system, including authentication, artificial intelligence, dashboard, system information, and management of users, roles, permissions and UI components. It integrates several submodules covering everything from security and authentication to management of customizable dashboards and AI agents.
|
|
10
|
+
|
|
11
|
+
## 2. Scope and responsibilities
|
|
12
|
+
|
|
13
|
+
- Authentication and authorization management, including MFA, WebAuthn, password recovery, sessions, and social login via OAuth (Google, Facebook, GitHub, Microsoft, Microsoft Entra ID, Apple, LinkedIn) with a multi-app callback hub.
|
|
14
|
+
- Artificial intelligence services for chat and AI agents with support for OpenAI and Gemini.
|
|
15
|
+
- Management of dashboards, components, roles, and associated users.
|
|
16
|
+
- Operating system, hardware, database, and installed-module information.
|
|
17
|
+
- Data validation and handling via DTOs and integration with the Prisma ORM.
|
|
18
|
+
- Internationalization and pagination support.
|
|
19
|
+
|
|
20
|
+
## 3. Endpoints
|
|
21
|
+
|
|
22
|
+
### AI Module (`/ai`)
|
|
23
|
+
|
|
24
|
+
| Method | Path | Auth | Description | Parameters / Query / Body | Response | Common Errors |
|
|
25
|
+
|--------|-------------------------|--------------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------|
|
|
26
|
+
| POST | `/ai/chat` | Authenticated | Chats with AI, optionally sending a file. | Body: `ChatDTO` (message: string, provider?: 'openai'|'gemini', model?: string, systemPrompt?: string, file_id?: number)<br>File: optional | `{ provider: string, model: string, content: string }` | 400: API key not configured |
|
|
27
|
+
| POST | `/ai/agent` | Authenticated | Creates an AI agent. | Body: `CreateAgentDTO` (slug: string, provider?: 'openai'|'gemini', model?: string, instructions?: string) | Created or existing agent object | 400: Slug already exists |
|
|
28
|
+
| GET | `/ai/agent` | Authenticated | Lists AI agents with pagination. | Query: pagination (page?: number, pageSize?: number, search?: string) | Paginated list of agents | - |
|
|
29
|
+
| GET | `/ai/agent/id/:agentId` | Authenticated | Gets an AI agent by ID. | Path param: `agentId` (int) | Agent object | 404: Agent not found |
|
|
30
|
+
| GET | `/ai/agent/:slug` | Authenticated | Gets an AI agent by slug. | Path param: `slug` (string) | Agent object | 404: Agent not found |
|
|
31
|
+
| PATCH | `/ai/agent/:agentId` | Authenticated | Updates an AI agent. | Path param: `agentId` (int)<br>Body: `UpdateAgentDTO` (slug?: string, provider?: 'openai'|'gemini', model?: string, instructions?: string) | Updated agent object | 404: Agent not found<br>400: Duplicate slug |
|
|
32
|
+
| DELETE | `/ai/agent` | Authenticated | Bulk-deletes AI agents. | Body: `DeleteDTO` (ids: number[]) | `{ count: number }` | 404: One or more agents not found |
|
|
33
|
+
| POST | `/ai/agent/:slug/chat` | Authenticated | Chats with a specific AI agent, with an optional file. | Path param: `slug` (string)<br>Body: `ChatAgentDTO` (message: string, file_id?: number)<br>File: optional | `{ slug: string, provider: string, model: string, content: string }` | 404: Agent not found |
|
|
34
|
+
|
|
35
|
+
### Auth Module (`/auth`)
|
|
36
|
+
|
|
37
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
38
|
+
|--------|-------------------------------------|--------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------|
|
|
39
|
+
| GET | `/auth/verify` | Authenticated | Verifies the authenticated user. | - | Authenticated user data | - |
|
|
40
|
+
| GET | `/auth/roles` | Public | Returns the user's roles (if authenticated). | - | `{ roles: string[] }` | - |
|
|
41
|
+
| POST | `/auth/refresh` | Public | Refreshes the access token using the refresh token. | Body: `{ refreshToken?: string }`<br>Cookies: `rt` optional | `{ accessToken: string, refreshToken?: string }` | 400: Refresh token not provided |
|
|
42
|
+
| POST | `/auth/login` | Public | Login with email and password. | Body: `LoginDTO` (email: string, password: string, refreshToken?: boolean) | Access and refresh tokens, or MFA required | 400: Access denied |
|
|
43
|
+
| POST | `/auth/login-email-verification` | Public | Login via email verification and code. | Body: `LoginEmailVerificationDTO` (token: string, code: string) | Access and refresh tokens | 400: Invalid code or challenge not found |
|
|
44
|
+
| POST | `/auth/login-email-verification-resend` | Public | Resends the email verification code. | Body: `LoginEmailVerificationResendDTO` (token: string) | New token for verification | 400: Invalid or expired token |
|
|
45
|
+
| POST | `/auth/signup` | Public | Sign-up with email and password. | Body: `CreateWithEmailAndPasswordDTO` | User created | - |
|
|
46
|
+
| POST | `/auth/login-code` | Public | Login with an MFA code. | Body: `LoginWithCodeDTO` (token: string, code: string, methodType?: 'totp'|'email'|'recovery') | Access and refresh tokens | 400: Invalid MFA code |
|
|
47
|
+
| POST | `/auth/login-recovery-code` | Public | Login with an MFA recovery code. | Body: `LoginWithRecoveryCodeDTO` (token: string, code: string) | Access and refresh tokens | 400: Invalid recovery code|
|
|
48
|
+
| POST | `/auth/resend-mfa-code` | Public | Resends the MFA code by email. | Body: `ResendMfaCodeDTO` (token: string) | `{ success: true, hasEmailMfa: true }` | 400: No email MFA method configured |
|
|
49
|
+
| POST | `/auth/webauthn/generate` | Public | Generates options for WebAuthn authentication. | Body: `{ mfaToken: string }` | WebAuthn options | 400: WebAuthn not configured |
|
|
50
|
+
| POST | `/auth/webauthn/verify` | Public | Verifies WebAuthn authentication. | Body: `{ mfaToken: string, assertionResponse: any }` | Access and refresh tokens | 400: Verification failed |
|
|
51
|
+
| POST | `/auth/forgot` | Public | Requests password recovery via email. | Body: `ForgetDTO` (email: string) | `{ success: true }` | - |
|
|
52
|
+
| POST | `/auth/logout` | Public | Logs out and invalidates the refresh token. | Body: `{ refreshToken?: string }`<br>Cookies: `rt` optional | `{ success: true }` | 400: Refresh token not provided |
|
|
53
|
+
| POST | `/auth/forgot-reset` | Public | Resets the password using a recovery code. | Body: `ResetDTO` (password: string, code: string) | Access and refresh tokens | 400: Invalid or expired code |
|
|
54
|
+
|
|
55
|
+
### OAuth Module (`/oauth`)
|
|
56
|
+
|
|
57
|
+
> **Multi-app hub pattern**: each provider only needs **one registered callback URL** (`${url}/callback/:provider`, with no flow suffix — GitHub uses `${api-url}/oauth/github/callback`, and Apple uses `${api-url}/oauth/apple/callback`, both because they only accept a single callback URL). The flow (`login`/`register`/`connect`) and the app that started the authentication (e.g. `training`) travel signed in the `state` parameter (`hhweb.<app>.<flow>.<signature>`, HMAC via `SecurityService`), never in the path. The app configured in the `url` setting acts as the **hub**: when it receives the callback from the provider, it either handles the flow locally or forwards the browser to the callback page of the app that started the flow, resolving the origin via the `app-urls` setting. Supported providers: Google, Facebook, GitHub, Microsoft, Microsoft Entra ID, Apple (Sign in with Apple), and LinkedIn.
|
|
58
|
+
|
|
59
|
+
| Method | Path | Auth | Description | Parameters / Query / Body | Response | Common Errors |
|
|
60
|
+
|--------|----------------------------------|--------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------|----------------------------------------------------------------------|
|
|
61
|
+
| GET | `/oauth/github/callback` | Public | Exclusive GitHub bounce (the only callback URL accepted by the provider); forwards the `code` to the correct frontend. | Query: `code`, `state?` | 302 redirect to `${origin}/callback/github/<flow>?code=...&state=...` | - |
|
|
62
|
+
| POST | `/oauth/apple/callback` | Public | Exclusive Apple bounce: Apple requires `response_mode=form_post` when `scope` is requested, so it POSTs `code`/`state` instead of a GET redirect. This is converted back to a GET redirect, the same as the GitHub bounce. | Body: `code`, `state?` | 302 redirect to `${origin}/callback/apple/<flow>?code=...&state=...` | - |
|
|
63
|
+
| GET | `/oauth/:provider/login` | Public | Starts the login flow, redirecting to the provider's authorization screen. | Path: `provider`<br>Query: `redirectApp?` (key in the initiating app's `app-urls`) | 302 redirect to the provider's authorization URL | 400: provider not enabled or not supported |
|
|
64
|
+
| GET | `/oauth/:provider/register` | Public | Starts the sign-up flow via OAuth. | Path: `provider`<br>Query: `redirectApp?` | 302 redirect to the provider's authorization URL | 400: provider not enabled or not supported |
|
|
65
|
+
| GET | `/oauth/:provider/connect` | Public | Starts the flow to link an account to a user already authenticated in the target app. | Path: `provider`<br>Query: `redirectApp?` | 302 redirect to the provider's authorization URL | 400: provider not enabled or not supported |
|
|
66
|
+
| GET | `/oauth/:provider/mobile/auth-url` | Public | Returns the authorization URL for native apps (Electron/React Native) to intercept the redirect. | Path: `provider`<br>Query: `redirectUri` (native app's custom scheme) | `{ authUrl: string }` | 400: invalid redirect URI or provider not enabled |
|
|
67
|
+
| GET | `/oauth/:provider/callback/login` | Public | Exchanges the `code` for access tokens after the hub forwards to the app's login page. | Path: `provider`<br>Query: `code`, `state?`, `redirectUri?` | `{ accessToken: string, refreshToken?: string }` + `rt` cookie (httpOnly) | 400: missing code, invalid origin, or callback already processed<br>409: callback being processed<br>503: provider failure |
|
|
68
|
+
| GET | `/oauth/:provider/callback/register` | Public | Exchanges the `code` for tokens after signing up via OAuth. | Path: `provider`<br>Query: `code` | `{ accessToken: string, refreshToken?: string }` + `rt` cookie | 400/409/503 — same cases as the login callback |
|
|
69
|
+
| GET | `/oauth/:provider/callback/connect` | Authenticated | Links the provider account to the authenticated user. | Path: `provider`<br>Query: `code` | `{ accessToken: string, refreshToken?: string }` + `rt` cookie | 400/409/503 — same cases as the login callback |
|
|
70
|
+
| DELETE | `/oauth/:provider` | Authenticated | Unlinks the provider account from the user. | Path: `provider`<br>Body: `{ email: string }` | Disconnection result | - |
|
|
71
|
+
|
|
72
|
+
### System Module (`/system`)
|
|
73
|
+
|
|
74
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
75
|
+
|--------|------------|--------------|---------------------------------|-------------------|--------------------------------------------------------------------------------------------|--------------|
|
|
76
|
+
| GET | `/system` | Authenticated | Returns system information. | - | Detailed information about the operating system, hardware, database, modules, and users | - |
|
|
77
|
+
|
|
78
|
+
### Dashboard Core Module (`/dashboard-core`)
|
|
79
|
+
|
|
80
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
81
|
+
|--------|---------------------------|--------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------|
|
|
82
|
+
| GET | `/dashboard-core/home` | Authenticated | Returns the user's home dashboard. | - | Dashboard object or null | 400: User not found |
|
|
83
|
+
| GET | `/dashboard-core/stats/overview/users` | Authenticated | User statistics. | - | Aggregated user and session statistics | - |
|
|
84
|
+
| GET | `/dashboard-core/stats/overview/mails` | Authenticated | Sent-email statistics. | - | Aggregated statistics on sent emails | - |
|
|
85
|
+
| GET | `/dashboard-core/stats/overview/system` | Authenticated | System statistics (menus and routes). | - | Aggregated system statistics | - |
|
|
86
|
+
| GET | `/dashboard-core/config/overview` | Authenticated | Overview of the system settings. | - | Object with configuration | - |
|
|
87
|
+
| GET | `/dashboard-core/widgets/me` | Authenticated | Widget data for the user. | - | Aggregated data for the user's widgets | - |
|
|
88
|
+
| GET | `/dashboard-core/user-dashboards` | Authenticated | Lists the user's dashboards. | - | List of dashboards associated with the user | - |
|
|
89
|
+
| GET | `/dashboard-core/templates` | Authenticated | Lists templates available for dashboards. | - | List of templates | - |
|
|
90
|
+
| POST | `/dashboard-core/dashboard` | Authenticated | Creates a dashboard for the user. | Body: `{ name?: string; slug?: string; icon?: string | null; templateSlug?: string }` | Created dashboard | - |
|
|
91
|
+
| PATCH | `/dashboard-core/dashboard/order` | Authenticated | Reorders the user's dashboards. | Body: `{ slugs?: string[] }` | Reordered dashboard | - |
|
|
92
|
+
| PATCH | `/dashboard-core/dashboard/:slug` | Authenticated | Renames the user's dashboard. | Path param: `slug` (string)<br>Body: `{ name?: string; icon?: string | null }` | Updated dashboard | - |
|
|
93
|
+
| POST | `/dashboard-core/dashboard/:slug/home` | Authenticated | Sets the dashboard as the user's home dashboard. | Path param: `slug` (string) | Success | - |
|
|
94
|
+
| GET | `/dashboard-core/dashboard/:slug/shares` | Authenticated | Lists the dashboard's shares. | Path param: `slug` (string) | List of users with access | - |
|
|
95
|
+
| GET | `/dashboard-core/shareable-users/:slug` | Authenticated | Lists users the dashboard can be shared with. | Path param: `slug` (string)<br>Query: search?: string, page?: string, pageSize?: string | Paginated list of users | - |
|
|
96
|
+
| POST | `/dashboard-core/dashboard/:slug/share` | Authenticated | Shares the dashboard with users. | Path param: `slug` (string)<br>Body: `{ userId?: number; userIds?: number[] }` | Success | - |
|
|
97
|
+
| DELETE | `/dashboard-core/dashboard/:slug/share/:sharedUserId` | Authenticated | Revokes a dashboard share. | Path params: `slug` (string), `sharedUserId` (int) | Success | - |
|
|
98
|
+
| DELETE | `/dashboard-core/dashboard/:slug` | Authenticated | Removes the dashboard from the user. | Path param: `slug` (string) | Success | - |
|
|
99
|
+
| GET | `/dashboard-core/access/:slug` | Authenticated | Checks the user's access to the dashboard. | Path param: `slug` (string) | `{ hasAccess: boolean, dashboard: object|null }` | - |
|
|
100
|
+
| GET | `/dashboard-core/layout/:slug` | Authenticated | Gets the user's layout for the dashboard. | Path param: `slug` (string) | Array of widgets with positions and sizes | - |
|
|
101
|
+
| POST | `/dashboard-core/layout/:slug` | Authenticated | Saves the user's layout for the dashboard. | Body: `{ layout: Array<{ i: string; x: number; y: number; w: number; h: number }> }` | `{ success: true }` | 403: Access denied |
|
|
102
|
+
| POST | `/dashboard-core/widget/:slug` | Authenticated | Adds a widget to the user's dashboard. | Body: `{ componentSlug: string }` | Data for the added widget | 403: Access denied |
|
|
103
|
+
| DELETE | `/dashboard-core/widget/:slug/:widgetId` | Authenticated | Removes a widget from the user's dashboard. | Path params: `slug` (string), `widgetId` (string) | "Not implemented yet" error | - |
|
|
104
|
+
| GET | `/dashboard-core/:slug` | Authenticated | Gets dashboard items by slug. | Path param: `slug` (string), Query param: `locale?: string` | List of dashboard items | - |
|
|
105
|
+
|
|
106
|
+
### Dashboard Module (`/dashboard`)
|
|
107
|
+
|
|
108
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
109
|
+
|--------|----------------|--------------|------------------------------------|---------------------------------------------------------|------------------------------|----------------------------|
|
|
110
|
+
| GET | `/dashboard` | Authenticated | Lists dashboards with pagination | Query: pagination (page?: number, pageSize?: number, search?: string) | Paginated list of dashboards | - |
|
|
111
|
+
| GET | `/dashboard/:id` | Authenticated | Gets a dashboard by ID | Path param: `id` (int) | Dashboard object | 404: Dashboard not found |
|
|
112
|
+
| POST | `/dashboard` | Authenticated | Creates a dashboard | Body: `CreateDashboardDTO` (slug: string, locale: Record<string, { name: string }>) | Created dashboard | - |
|
|
113
|
+
| PATCH | `/dashboard/:id` | Authenticated | Updates a dashboard | Path param: `id` (int), Body: `UpdateDashboardDTO` | Updated dashboard | 404: Dashboard not found |
|
|
114
|
+
| DELETE | `/dashboard/:id` | Authenticated | Deletes a dashboard | Path param: `id` (int) | `{ success: true }` | 404: Dashboard not found |
|
|
115
|
+
|
|
116
|
+
### Dashboard Component Module (`/dashboard-component`)
|
|
117
|
+
|
|
118
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
119
|
+
|--------|------------------------|--------------|------------------------------------|------------------------------------------------------------------|------------------------------|-------------------------------|
|
|
120
|
+
| GET | `/dashboard-component` | Authenticated | Lists components with pagination | Query: pagination (page?: number, pageSize?: number, search?: string) | Paginated list of components | - |
|
|
121
|
+
| GET | `/dashboard-component/user` | Authenticated | Lists components by the user's roles | Query: pagination (page?: number, pageSize?: number, search?: string), User ID via token | Paginated list of components | - |
|
|
122
|
+
| GET | `/dashboard-component/:id` | Authenticated | Gets a component by ID | Path param: `id` (int) | Component object | 404: Component not found |
|
|
123
|
+
| POST | `/dashboard-component` | Authenticated | Creates a component | Body: `CreateDashboardComponentDTO` | Created component | - |
|
|
124
|
+
| PATCH | `/dashboard-component/:id` | Authenticated | Updates a component | Path param: `id` (int), Body: `UpdateDashboardComponentDTO` | Updated component | 404: Component not found |
|
|
125
|
+
| DELETE | `/dashboard-component/:id` | Authenticated | Deletes a component | Path param: `id` (int) | `{ success: true }` | 404: Component not found |
|
|
126
|
+
| POST | `/dashboard-component/:id/preview` | Authenticated | Saves a component preview (image) | Path param: `id` (int), File: image (image/*) | `{ success: true, componentId: number, slug: string, library_slug: string, fileName: string, relativeUrl: string }` | 400: Invalid file<br>403: Dev environment only |
|
|
127
|
+
|
|
128
|
+
### Dashboard Component Role Module (`/dashboard-component-role`)
|
|
129
|
+
|
|
130
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
131
|
+
|--------|-------------------------------|--------------|---------------------------------------|------------------------------------------------------------------|------------------------------|-------------------------------|
|
|
132
|
+
| GET | `/dashboard-component-role` | Authenticated | Lists relations with pagination or by component | Query: pagination (page?: number, pageSize?: number), Query param: componentId?: number | Paginated or list of relations | - |
|
|
133
|
+
| POST | `/dashboard-component-role` | Authenticated | Creates a component-role relation | Body: `CreateDashboardComponentRoleDTO` | Created relation | Error if the relation already exists |
|
|
134
|
+
| POST | `/dashboard-component-role/batch` | Authenticated | Bulk-creates relations | Body: `CreateDashboardComponentRoleBatchDTO` | { success: boolean, created: number, skipped: number, message: string } | - |
|
|
135
|
+
| DELETE | `/dashboard-component-role/:id` | Authenticated | Deletes a relation by ID | Path param: `id` (int) | `{ success: true }` | 404: Relation not found |
|
|
136
|
+
| DELETE | `/dashboard-component-role/component/:componentId/role/:roleId` | Authenticated | Deletes a relation by component and role | Path params: `componentId` (int), `roleId` (int) | `{ success: true }` | 404: Relation not found |
|
|
137
|
+
|
|
138
|
+
### Dashboard Item Module (`/dashboard-item`)
|
|
139
|
+
|
|
140
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
141
|
+
|--------|--------------------|--------------|------------------------------------|------------------------------------------------------------------|------------------------------|-------------------------------|
|
|
142
|
+
| GET | `/dashboard-item` | Authenticated | Lists items with pagination and filter by dashboard | Query: pagination (page?: number, pageSize?: number), Query param: dashboardId?: number | Paginated list of items | - |
|
|
143
|
+
| POST | `/dashboard-item` | Authenticated | Creates an item | Body: `CreateDashboardItemDTO` | Created item | - |
|
|
144
|
+
| DELETE | `/dashboard-item/:id` | Authenticated | Deletes an item by ID | Path param: `id` (int) | `{ success: true }` | 404: Item not found |
|
|
145
|
+
|
|
146
|
+
### Dashboard Role Module (`/dashboard-role`)
|
|
147
|
+
|
|
148
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
149
|
+
|--------|--------------------|--------------|---------------------------------------|------------------------------------------------------------------|------------------------------|-------------------------------|
|
|
150
|
+
| GET | `/dashboard-role` | Authenticated | Lists relations with pagination or by dashboard | Query: pagination (page?: number, pageSize?: number), Query param: dashboardId?: number | Paginated or list of relations | - |
|
|
151
|
+
| POST | `/dashboard-role` | Authenticated | Creates a dashboard-role relation | Body: `CreateDashboardRoleDTO` | Created relation | Error if the relation already exists |
|
|
152
|
+
| POST | `/dashboard-role/batch` | Authenticated | Bulk-creates relations | Body: `CreateDashboardRoleBatchDTO` | { success: boolean, created: number, skipped: number, message: string } | - |
|
|
153
|
+
| DELETE | `/dashboard-role/:id` | Authenticated | Deletes a relation by ID | Path param: `id` (int) | `{ success: true }` | 404: Relation not found |
|
|
154
|
+
| DELETE | `/dashboard-role/dashboard/:dashboardId/role/:roleId` | Authenticated | Deletes a relation by dashboard and role | Path params: `dashboardId` (int), `roleId` (int) | `{ success: true }` | 404: Relation not found |
|
|
155
|
+
|
|
156
|
+
### Dashboard User Module (`/dashboard-user`)
|
|
157
|
+
|
|
158
|
+
| Method | Path | Auth | Description | Parameters / Body | Response | Common Errors |
|
|
159
|
+
|--------|--------------------|--------------|------------------------------------|------------------------------------------------------------------|------------------------------|-------------------------------|
|
|
160
|
+
| GET | `/dashboard-user` | Authenticated | Lists relations with pagination | Query: pagination (page?: number, pageSize?: number) | Paginated list of relations | - |
|
|
161
|
+
| GET | `/dashboard-user/:id` | Authenticated | Gets a relation by ID | Path param: `id` (int) | Relation object | - |
|
|
162
|
+
| POST | `/dashboard-user` | Authenticated | Creates a relation | Body: `CreateDTO` (dashboard_id: number, user_id: number) | Created relation | - |
|
|
163
|
+
| PATCH | `/dashboard-user/:id` | Authenticated | Updates a relation | Path param: `id` (int), Body: `UpdateDTO` | Updated relation | - |
|
|
164
|
+
| DELETE | `/dashboard-user` | Authenticated | Bulk-deletes relations | Body: `DeleteDTO` (ids: number[]) | `{ count: number }` | 400: No id provided |
|
|
165
|
+
|
|
166
|
+
## 4. Authentication and authorization rules
|
|
167
|
+
|
|
168
|
+
- Most endpoints require authentication via a JWT token.
|
|
169
|
+
- Public endpoints are explicitly marked.
|
|
170
|
+
- Access control is based on roles and permissions.
|
|
171
|
+
- MFA (Multi-Factor Authentication) is supported via TOTP, email, and recovery codes.
|
|
172
|
+
- WebAuthn is supported for strong authentication.
|
|
173
|
+
- Refresh tokens are managed via HTTP-only cookies or in the request body.
|
|
174
|
+
- Sensitive operations (create, update, delete) require authentication and the appropriate permissions.
|
|
175
|
+
|
|
176
|
+
## 5. Request/response structures
|
|
177
|
+
|
|
178
|
+
### Main DTOs of the AI module
|
|
179
|
+
|
|
180
|
+
- **ChatDTO**
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
{
|
|
184
|
+
message: string; // required
|
|
185
|
+
provider?: 'openai' | 'gemini'; // optional, default 'openai'
|
|
186
|
+
model?: string; // optional
|
|
187
|
+
systemPrompt?: string; // optional
|
|
188
|
+
file_id?: number; // optional
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
- **ChatAgentDTO**
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
{
|
|
196
|
+
message: string; // required
|
|
197
|
+
file_id?: number; // optional
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
- **CreateAgentDTO**
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
{
|
|
205
|
+
slug: string; // required
|
|
206
|
+
provider?: 'openai' | 'gemini'; // optional, default 'openai'
|
|
207
|
+
model?: string; // optional
|
|
208
|
+
instructions?: string; // optional
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
- **UpdateAgentDTO**
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
{
|
|
216
|
+
slug?: string;
|
|
217
|
+
provider?: 'openai' | 'gemini';
|
|
218
|
+
model?: string;
|
|
219
|
+
instructions?: string;
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
- **DeleteDTO**
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
{
|
|
227
|
+
ids: number[]; // array of IDs to delete, minimum 1 item
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Main DTOs of the Auth module
|
|
232
|
+
|
|
233
|
+
- **LoginDTO**
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
{
|
|
237
|
+
email: string; // required, valid email
|
|
238
|
+
password: string; // required, strong password, minimum 6 characters
|
|
239
|
+
refreshToken?: boolean; // optional, default false
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
- **LoginEmailVerificationDTO**
|
|
244
|
+
|
|
245
|
+
```ts
|
|
246
|
+
{
|
|
247
|
+
token: string; // required
|
|
248
|
+
code: string; // required, PIN code
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
- **LoginEmailVerificationResendDTO**
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
{
|
|
256
|
+
token: string; // required
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- **LoginWithCodeDTO**
|
|
261
|
+
|
|
262
|
+
```ts
|
|
263
|
+
{
|
|
264
|
+
code: string; // required
|
|
265
|
+
token: string; // required, JWT
|
|
266
|
+
methodType?: 'totp' | 'email' | 'recovery'; // optional
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
- **LoginWithRecoveryCodeDTO**
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
{
|
|
274
|
+
code: string; // required
|
|
275
|
+
token: string; // required, JWT
|
|
276
|
+
}
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
- **ForgetDTO**
|
|
280
|
+
|
|
281
|
+
```ts
|
|
282
|
+
{
|
|
283
|
+
email: string; // required, valid email
|
|
284
|
+
}
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
- **ResetDTO**
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
{
|
|
291
|
+
password: string; // required, minimum 8 characters
|
|
292
|
+
code: string; // required
|
|
293
|
+
}
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Main DTOs of the Dashboard module
|
|
297
|
+
|
|
298
|
+
- **CreateDashboardDTO**
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
{
|
|
302
|
+
slug: string; // required
|
|
303
|
+
locale: Record<string, { name: string }>; // required
|
|
304
|
+
}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
- **UpdateDashboardDTO**
|
|
308
|
+
|
|
309
|
+
```ts
|
|
310
|
+
{
|
|
311
|
+
slug?: string;
|
|
312
|
+
locale?: Record<string, { name: string }>;
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
- **CreateDashboardComponentDTO**
|
|
317
|
+
|
|
318
|
+
```ts
|
|
319
|
+
{
|
|
320
|
+
slug: string;
|
|
321
|
+
library_slug?: string;
|
|
322
|
+
min_width?: number;
|
|
323
|
+
max_width?: number;
|
|
324
|
+
min_height?: number;
|
|
325
|
+
max_height?: number;
|
|
326
|
+
width: number;
|
|
327
|
+
height: number;
|
|
328
|
+
is_resizable?: boolean;
|
|
329
|
+
locale: Record<string, { name: string; description?: string }>;
|
|
330
|
+
}
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
- **UpdateDashboardComponentDTO**
|
|
334
|
+
|
|
335
|
+
```ts
|
|
336
|
+
{
|
|
337
|
+
slug?: string;
|
|
338
|
+
library_slug?: string;
|
|
339
|
+
min_width?: number;
|
|
340
|
+
max_width?: number;
|
|
341
|
+
min_height?: number;
|
|
342
|
+
max_height?: number;
|
|
343
|
+
width?: number;
|
|
344
|
+
height?: number;
|
|
345
|
+
is_resizable?: boolean;
|
|
346
|
+
locale?: Record<string, { name: string; description?: string }>;
|
|
347
|
+
}
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
- **CreateDashboardRoleDTO**
|
|
351
|
+
|
|
352
|
+
```ts
|
|
353
|
+
{
|
|
354
|
+
dashboard_id: number;
|
|
355
|
+
role_id: number;
|
|
356
|
+
}
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
- **CreateDashboardRoleBatchDTO**
|
|
360
|
+
|
|
361
|
+
```ts
|
|
362
|
+
{
|
|
363
|
+
dashboard_id: number;
|
|
364
|
+
role_ids: number[];
|
|
365
|
+
}
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
- **CreateDashboardComponentRoleDTO**
|
|
369
|
+
|
|
370
|
+
```ts
|
|
371
|
+
{
|
|
372
|
+
component_id: number;
|
|
373
|
+
role_id: number;
|
|
374
|
+
}
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
- **CreateDashboardComponentRoleBatchDTO**
|
|
378
|
+
|
|
379
|
+
```ts
|
|
380
|
+
{
|
|
381
|
+
component_id: number;
|
|
382
|
+
role_ids: number[];
|
|
383
|
+
}
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
- **CreateDashboardItemDTO**
|
|
387
|
+
|
|
388
|
+
```ts
|
|
389
|
+
{
|
|
390
|
+
component_id: number;
|
|
391
|
+
dashboard_id: number;
|
|
392
|
+
width: number;
|
|
393
|
+
height: number;
|
|
394
|
+
x_axis: number;
|
|
395
|
+
y_axis: number;
|
|
396
|
+
}
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
- **UpdateDashboardLayoutDTO**
|
|
400
|
+
|
|
401
|
+
```ts
|
|
402
|
+
{
|
|
403
|
+
dashboard_id: number;
|
|
404
|
+
items: Array<{
|
|
405
|
+
id: number;
|
|
406
|
+
width: number;
|
|
407
|
+
height: number;
|
|
408
|
+
x_axis: number;
|
|
409
|
+
y_axis: number;
|
|
410
|
+
}>;
|
|
411
|
+
}
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
- **UpdateDashboardItemDTO**
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
{
|
|
418
|
+
component_id?: number;
|
|
419
|
+
dashboard_id?: number;
|
|
420
|
+
width?: number;
|
|
421
|
+
height?: number;
|
|
422
|
+
x_axis?: number;
|
|
423
|
+
y_axis?: number;
|
|
424
|
+
}
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
- **CreateDTO (DashboardUser)**
|
|
428
|
+
|
|
429
|
+
```ts
|
|
430
|
+
{
|
|
431
|
+
dashboard_id: number;
|
|
432
|
+
user_id: number;
|
|
433
|
+
}
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
- **UpdateDTO (DashboardUser)**
|
|
437
|
+
|
|
438
|
+
```ts
|
|
439
|
+
{
|
|
440
|
+
dashboard_id?: number;
|
|
441
|
+
user_id?: number;
|
|
442
|
+
}
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
- **DeleteDTO**
|
|
446
|
+
|
|
447
|
+
```ts
|
|
448
|
+
{
|
|
449
|
+
ids: number[];
|
|
450
|
+
}
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
## 6. Common errors
|
|
454
|
+
|
|
455
|
+
- **400 Bad Request**
|
|
456
|
+
|
|
457
|
+
- API key not configured for OpenAI or Gemini.
|
|
458
|
+
- AI agent slug already exists.
|
|
459
|
+
- Invalid or expired verification code.
|
|
460
|
+
- Refresh token not provided.
|
|
461
|
+
- Access denied due to invalid credentials.
|
|
462
|
+
- MFA not configured or invalid code.
|
|
463
|
+
- Attempt to delete non-existent items.
|
|
464
|
+
- Invalid request to create duplicate relations.
|
|
465
|
+
- Invalid file for component preview.
|
|
466
|
+
- Preview operation available only in the development environment.
|
|
467
|
+
- OAuth: provider not enabled (`oauth-<provider>-enabled` off) or not supported.
|
|
468
|
+
- OAuth: integration profile not configured (`oauth-<provider>-profile-id` empty) or not found.
|
|
469
|
+
- OAuth: missing authorization code, invalid mobile redirect URI, invalid callback origin (hub origin binding), or callback already processed.
|
|
470
|
+
|
|
471
|
+
- **404 Not Found**
|
|
472
|
+
|
|
473
|
+
- AI agent not found by ID or slug.
|
|
474
|
+
- Dashboard, component, or relation not found.
|
|
475
|
+
- Verification challenge not found or expired.
|
|
476
|
+
|
|
477
|
+
- **403 Forbidden**
|
|
478
|
+
|
|
479
|
+
- Access denied to dashboards or protected resources.
|
|
480
|
+
- Attempt to save a preview outside the development environment.
|
|
481
|
+
|
|
482
|
+
- **409 Conflict**
|
|
483
|
+
|
|
484
|
+
- OAuth: callback already being processed (idempotency lock by code).
|
|
485
|
+
|
|
486
|
+
- **503 Service Unavailable**
|
|
487
|
+
|
|
488
|
+
- OAuth: failure communicating with the provider (upstream).
|
|
489
|
+
|
|
490
|
+
## 7. Database (YAML tables)
|
|
491
|
+
|
|
492
|
+
### ai_agent
|
|
493
|
+
|
|
494
|
+
```yaml
|
|
495
|
+
purpose: Stores AI agents configured in the system.
|
|
496
|
+
columns:
|
|
497
|
+
- id: integer, PK, auto-increment
|
|
498
|
+
- slug: string, unique, not null
|
|
499
|
+
- provider: enum('openai', 'gemini'), not null
|
|
500
|
+
- model: string, nullable
|
|
501
|
+
- instructions: string, nullable
|
|
502
|
+
- external_agent_id: string, nullable
|
|
503
|
+
- created_at: timestamp, not null, default NOW()
|
|
504
|
+
- updated_at: timestamp, not null, default NOW()
|
|
505
|
+
defaults:
|
|
506
|
+
- created_at: NOW()
|
|
507
|
+
- updated_at: NOW()
|
|
508
|
+
nullability:
|
|
509
|
+
- model: nullable
|
|
510
|
+
- instructions: nullable
|
|
511
|
+
- external_agent_id: nullable
|
|
512
|
+
integrity:
|
|
513
|
+
- unique slug
|
|
514
|
+
indexes:
|
|
515
|
+
- id (PK)
|
|
516
|
+
- slug (unique)
|
|
517
|
+
enums:
|
|
518
|
+
- provider: ['openai', 'gemini']
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
### user
|
|
522
|
+
|
|
523
|
+
```yaml
|
|
524
|
+
purpose: Stores the system's users.
|
|
525
|
+
columns:
|
|
526
|
+
- id: integer, PK, auto-increment
|
|
527
|
+
- name: string, not null
|
|
528
|
+
- photo_id: integer, nullable
|
|
529
|
+
- last_login_at: timestamp, nullable
|
|
530
|
+
- created_at: timestamp, not null, default NOW()
|
|
531
|
+
- updated_at: timestamp, not null, default NOW()
|
|
532
|
+
integrity:
|
|
533
|
+
- PK on id
|
|
534
|
+
indexes:
|
|
535
|
+
- id (PK)
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
### user_mfa
|
|
539
|
+
|
|
540
|
+
```yaml
|
|
541
|
+
purpose: Stores users' multi-factor authentication methods.
|
|
542
|
+
columns:
|
|
543
|
+
- id: integer, PK, auto-increment
|
|
544
|
+
- user_id: integer, FK to user.id, not null
|
|
545
|
+
- name: string, not null
|
|
546
|
+
- type: enum('totp', 'email', 'webauthn'), not null
|
|
547
|
+
- verified_at: timestamp, nullable
|
|
548
|
+
- suspended_until: timestamp, nullable
|
|
549
|
+
- created_at: timestamp, not null, default NOW()
|
|
550
|
+
- updated_at: timestamp, not null, default NOW()
|
|
551
|
+
integrity:
|
|
552
|
+
- FK user_id references user.id
|
|
553
|
+
indexes:
|
|
554
|
+
- id (PK)
|
|
555
|
+
enums:
|
|
556
|
+
- type: ['totp', 'email', 'webauthn']
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
### user_identifier
|
|
560
|
+
|
|
561
|
+
```yaml
|
|
562
|
+
purpose: User identifiers, such as emails.
|
|
563
|
+
columns:
|
|
564
|
+
- id: integer, PK, auto-increment
|
|
565
|
+
- user_id: integer, FK to user.id, not null
|
|
566
|
+
- type: string, not null (e.g.: 'email')
|
|
567
|
+
- value: string, not null
|
|
568
|
+
- verified_at: timestamp, nullable
|
|
569
|
+
- enabled: boolean, not null, default true
|
|
570
|
+
- created_at: timestamp, not null, default NOW()
|
|
571
|
+
- updated_at: timestamp, not null, default NOW()
|
|
572
|
+
integrity:
|
|
573
|
+
- FK user_id references user.id
|
|
574
|
+
indexes:
|
|
575
|
+
- id (PK)
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
### user_session
|
|
579
|
+
|
|
580
|
+
```yaml
|
|
581
|
+
purpose: Sessions of authenticated users.
|
|
582
|
+
columns:
|
|
583
|
+
- id: integer, PK, auto-increment
|
|
584
|
+
- user_id: integer, FK to user.id, not null
|
|
585
|
+
- token: string, not null
|
|
586
|
+
- ip_address: string, nullable
|
|
587
|
+
- user_agent: string, nullable
|
|
588
|
+
- created_at: timestamp, not null, default NOW()
|
|
589
|
+
- expires_at: timestamp, not null
|
|
590
|
+
- revoked_at: timestamp, nullable
|
|
591
|
+
integrity:
|
|
592
|
+
- FK user_id references user.id
|
|
593
|
+
indexes:
|
|
594
|
+
- id (PK)
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
### user_activity
|
|
598
|
+
|
|
599
|
+
```yaml
|
|
600
|
+
purpose: Log of user activities.
|
|
601
|
+
columns:
|
|
602
|
+
- id: integer, PK, auto-increment
|
|
603
|
+
- user_id: integer, FK to user.id, not null
|
|
604
|
+
- action: string, not null
|
|
605
|
+
- created_at: timestamp, not null, default NOW()
|
|
606
|
+
integrity:
|
|
607
|
+
- FK user_id references user.id
|
|
608
|
+
indexes:
|
|
609
|
+
- id (PK)
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
### role
|
|
613
|
+
|
|
614
|
+
```yaml
|
|
615
|
+
purpose: System roles for access control.
|
|
616
|
+
columns:
|
|
617
|
+
- id: integer, PK, auto-increment
|
|
618
|
+
- slug: string, unique, not null
|
|
619
|
+
- created_at: timestamp, not null, default NOW()
|
|
620
|
+
- updated_at: timestamp, not null, default NOW()
|
|
621
|
+
integrity:
|
|
622
|
+
- unique slug
|
|
623
|
+
indexes:
|
|
624
|
+
- id (PK)
|
|
625
|
+
- slug (unique)
|
|
626
|
+
```
|
|
627
|
+
|
|
628
|
+
### role_user
|
|
629
|
+
|
|
630
|
+
```yaml
|
|
631
|
+
purpose: Many-to-many relation between users and roles.
|
|
632
|
+
columns:
|
|
633
|
+
- id: integer, PK, auto-increment
|
|
634
|
+
- user_id: integer, FK to user.id, not null
|
|
635
|
+
- role_id: integer, FK to role.id, not null
|
|
636
|
+
integrity:
|
|
637
|
+
- FK user_id references user.id
|
|
638
|
+
- FK role_id references role.id
|
|
639
|
+
indexes:
|
|
640
|
+
- id (PK)
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
### dashboard
|
|
644
|
+
|
|
645
|
+
```yaml
|
|
646
|
+
purpose: The system's configurable dashboards.
|
|
647
|
+
columns:
|
|
648
|
+
- id: integer, PK, auto-increment
|
|
649
|
+
- slug: string, unique, not null
|
|
650
|
+
- created_at: timestamp, not null, default NOW()
|
|
651
|
+
- updated_at: timestamp, not null, default NOW()
|
|
652
|
+
integrity:
|
|
653
|
+
- unique slug
|
|
654
|
+
indexes:
|
|
655
|
+
- id (PK)
|
|
656
|
+
- slug (unique)
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
### dashboard_component
|
|
660
|
+
|
|
661
|
+
```yaml
|
|
662
|
+
purpose: Components that can be used in dashboards.
|
|
663
|
+
columns:
|
|
664
|
+
- id: integer, PK, auto-increment
|
|
665
|
+
- slug: string, unique, not null
|
|
666
|
+
- library_slug: string, nullable
|
|
667
|
+
- min_width: integer, nullable
|
|
668
|
+
- max_width: integer, nullable
|
|
669
|
+
- min_height: integer, nullable
|
|
670
|
+
- max_height: integer, nullable
|
|
671
|
+
- width: integer, not null
|
|
672
|
+
- height: integer, not null
|
|
673
|
+
- is_resizable: boolean, not null, default true
|
|
674
|
+
- created_at: timestamp, not null, default NOW()
|
|
675
|
+
- updated_at: timestamp, not null, default NOW()
|
|
676
|
+
integrity:
|
|
677
|
+
- unique slug
|
|
678
|
+
indexes:
|
|
679
|
+
- id (PK)
|
|
680
|
+
- slug (unique)
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
### dashboard_role
|
|
684
|
+
|
|
685
|
+
```yaml
|
|
686
|
+
purpose: Relation between dashboards and roles for access control.
|
|
687
|
+
columns:
|
|
688
|
+
- id: integer, PK, auto-increment
|
|
689
|
+
- dashboard_id: integer, FK to dashboard.id, not null
|
|
690
|
+
- role_id: integer, FK to role.id, not null
|
|
691
|
+
integrity:
|
|
692
|
+
- FK dashboard_id references dashboard.id
|
|
693
|
+
- FK role_id references role.id
|
|
694
|
+
indexes:
|
|
695
|
+
- id (PK)
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
### dashboard_user
|
|
699
|
+
|
|
700
|
+
```yaml
|
|
701
|
+
purpose: Relation between dashboards and users.
|
|
702
|
+
columns:
|
|
703
|
+
- id: integer, PK, auto-increment
|
|
704
|
+
- dashboard_id: integer, FK to dashboard.id, not null
|
|
705
|
+
- user_id: integer, FK to user.id, not null
|
|
706
|
+
- is_home: boolean, not null, default false
|
|
707
|
+
integrity:
|
|
708
|
+
- FK dashboard_id references dashboard.id
|
|
709
|
+
- FK user_id references user.id
|
|
710
|
+
indexes:
|
|
711
|
+
- id (PK)
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
### dashboard_item
|
|
715
|
+
|
|
716
|
+
```yaml
|
|
717
|
+
purpose: Items (widgets) within dashboards.
|
|
718
|
+
columns:
|
|
719
|
+
- id: integer, PK, auto-increment
|
|
720
|
+
- dashboard_id: integer, FK to dashboard.id, not null
|
|
721
|
+
- component_id: integer, FK to dashboard_component.id, not null
|
|
722
|
+
- width: integer, not null
|
|
723
|
+
- height: integer, not null
|
|
724
|
+
- x_axis: integer, not null
|
|
725
|
+
- y_axis: integer, not null
|
|
726
|
+
integrity:
|
|
727
|
+
- FK dashboard_id references dashboard.id
|
|
728
|
+
- FK component_id references dashboard_component.id
|
|
729
|
+
indexes:
|
|
730
|
+
- id (PK)
|
|
731
|
+
```
|
|
732
|
+
|
|
733
|
+
### dashboard_component_role
|
|
734
|
+
|
|
735
|
+
```yaml
|
|
736
|
+
purpose: Relation between dashboard components and roles.
|
|
737
|
+
columns:
|
|
738
|
+
- id: integer, PK, auto-increment
|
|
739
|
+
- component_id: integer, FK to dashboard_component.id, not null
|
|
740
|
+
- role_id: integer, FK to role.id, not null
|
|
741
|
+
integrity:
|
|
742
|
+
- FK component_id references dashboard_component.id
|
|
743
|
+
- FK role_id references role.id
|
|
744
|
+
indexes:
|
|
745
|
+
- id (PK)
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
### oauth_mobile_state_token
|
|
749
|
+
|
|
750
|
+
```yaml
|
|
751
|
+
purpose: Single-use signed state for the OAuth flow started by native apps (mobile/desktop), binding the app's redirect URI to the provider and the flow.
|
|
752
|
+
columns:
|
|
753
|
+
- id: bigint, PK, auto-increment
|
|
754
|
+
- token_hash: string, unique, not null
|
|
755
|
+
- provider: string, not null
|
|
756
|
+
- redirect_uri: string, not null (native app's custom scheme)
|
|
757
|
+
- flow_type: string, not null ('login' | 'register' | 'connect')
|
|
758
|
+
- expires_at: timestamptz, not null
|
|
759
|
+
- consumed_at: timestamptz, nullable (marks single use)
|
|
760
|
+
- created_at: timestamptz, not null, default NOW()
|
|
761
|
+
integrity:
|
|
762
|
+
- unique token_hash
|
|
763
|
+
indexes:
|
|
764
|
+
- id (PK)
|
|
765
|
+
- expires_at
|
|
766
|
+
- (provider, redirect_uri)
|
|
767
|
+
```
|
|
768
|
+
|
|
769
|
+
> Used only by the mobile flow (`GET /oauth/:provider/mobile/auth-url`). The multi-app web hub (signed `state`, `hhweb.<app>.<flow>.<sig>`) is stateless — the HMAC signature is verified without database persistence.
|
|
770
|
+
|
|
771
|
+
## 8. Relevant business rules
|
|
772
|
+
|
|
773
|
+
- AI agents can be created, updated, and deleted, with direct integration with the OpenAI and Gemini APIs.
|
|
774
|
+
- AI chat supports file attachments, with text extraction for PDFs and text files.
|
|
775
|
+
- Mandatory MFA can be configured, with support for email, TOTP, and WebAuthn.
|
|
776
|
+
- Access and refresh tokens are managed securely, including HTTP-only cookies.
|
|
777
|
+
- Dashboards are personalized per user, with role-based access control.
|
|
778
|
+
- Dashboard and widget layouts can be saved and retrieved per user.
|
|
779
|
+
- The system collects usage statistics, sessions, sent emails, and account security data.
|
|
780
|
+
- Strict validations are applied via DTOs and validation classes.
|
|
781
|
+
- Batch create operations avoid duplication and return counts of created and skipped items.
|
|
782
|
+
- Removing widgets from a user's dashboard is not yet implemented.
|
|
783
|
+
- Dashboard component previews are allowed only in the development environment and accept images only.
|
|
784
|
+
- Email MFA sends codes to all email addresses associated with the user.
|
|
785
|
+
- WebAuthn is supported for strong authentication with challenge generation and verification.
|
|
786
|
+
- **OAuth — one callback URL per provider**: the flow (login/register/connect) and the initiating app travel signed in the `state`, never in the path; each provider is enabled/disabled individually via the `oauth-<provider>-enabled` setting, without removing the configured credentials (`oauth-<provider>-profile-id`, pointing to an `integration_profile`).
|
|
787
|
+
- **OAuth — multi-app hub**: the app in the `url` setting (e.g. admin) receives the callback from the provider and, if the `state` indicates a different initiating app, forwards the browser to that app's corresponding callback page, resolving the origin via `app-urls`. Exchanging the `code` for tokens is only accepted when the request's `Origin`/`Referer` header matches the origin signed in the `state` (origin binding), preventing code interception between apps.
|
|
788
|
+
- **OAuth — email auto-linking**: on login, if no `user_account` exists for the provider but an enabled email `user_identifier` matching the OAuth profile's email already exists, the flow becomes an automatic connection (`connect`) to the existing account instead of creating a new user; a new account (`register`) is only created when no user matches the email.
|
|
789
|
+
- **OAuth — roles on sign-up**: new users registered via OAuth receive the roles configured in the `oauth-role-assignment` setting.
|
|
790
|
+
- **OAuth — mobile**: native apps use `/oauth/:provider/mobile/auth-url` with a signed state persisted in `oauth_mobile_state_token` (10-minute TTL, single use).
|
|
791
|
+
- **OAuth — Apple (Sign in with Apple)**: no static `client_secret` — the `private_key` (EC `.p8` key) signs a `client_secret` JWT (ES256, `iss`=team ID, `sub`=Services ID, `kid`=key ID, short TTL) on each code exchange. Since scopes require `response_mode=form_post`, the callback is `POST /oauth/apple/callback` (a single URL, on the backend), converted to the same GET redirect used by the other providers. Identity comes from the `id_token` (decoded JWT, without signature verification — delivered directly by Apple in the server-to-server exchange); the name is only sent by Apple on the first authorization and is not captured, so the user's name falls back to the local part of the email.
|
|
792
|
+
- **OAuth — LinkedIn**: uses "Sign In with LinkedIn using OpenID Connect" (`scope=openid profile email`), with identity obtained in a single call to `GET /v2/userinfo` (standard OIDC claims), without the legacy pair of calls `/v2/me` + `/v2/emailAddress`.
|
|
793
|
+
|
|
794
|
+
## 9. Quick usage guide (examples)
|
|
795
|
+
|
|
796
|
+
### Create an AI agent
|
|
797
|
+
|
|
798
|
+
```http
|
|
799
|
+
POST /ai/agent
|
|
800
|
+
Authorization: Bearer <token>
|
|
801
|
+
Content-Type: application/json
|
|
802
|
+
|
|
803
|
+
{
|
|
804
|
+
"slug": "my-agent",
|
|
805
|
+
"provider": "openai",
|
|
806
|
+
"model": "gpt-4o-mini",
|
|
807
|
+
"instructions": "Be a friendly assistant."
|
|
808
|
+
}
|
|
809
|
+
```
|
|
810
|
+
|
|
811
|
+
Response:
|
|
812
|
+
|
|
813
|
+
```json
|
|
814
|
+
{
|
|
815
|
+
"id": 1,
|
|
816
|
+
"slug": "my-agent",
|
|
817
|
+
"provider": "openai",
|
|
818
|
+
"model": "gpt-4o-mini",
|
|
819
|
+
"instructions": "Be a friendly assistant.",
|
|
820
|
+
"external_agent_id": "abc123",
|
|
821
|
+
"created_at": "2024-06-01T12:00:00Z",
|
|
822
|
+
"updated_at": "2024-06-01T12:00:00Z"
|
|
823
|
+
}
|
|
824
|
+
```
|
|
825
|
+
|
|
826
|
+
### Chat with an AI agent
|
|
827
|
+
|
|
828
|
+
```http
|
|
829
|
+
POST /ai/agent/my-agent/chat
|
|
830
|
+
Authorization: Bearer <token>
|
|
831
|
+
Content-Type: multipart/form-data
|
|
832
|
+
|
|
833
|
+
Form-data:
|
|
834
|
+
- message: "Hi, how are you?"
|
|
835
|
+
- file: (optional file)
|
|
836
|
+
```
|
|
837
|
+
|
|
838
|
+
Response:
|
|
839
|
+
|
|
840
|
+
```json
|
|
841
|
+
{
|
|
842
|
+
"slug": "my-agent",
|
|
843
|
+
"provider": "openai",
|
|
844
|
+
"model": "gpt-4o-mini",
|
|
845
|
+
"content": "Hello! I'm doing well, thanks for asking."
|
|
846
|
+
}
|
|
847
|
+
```
|
|
848
|
+
|
|
849
|
+
### Login with email and password
|
|
850
|
+
|
|
851
|
+
```http
|
|
852
|
+
POST /auth/login
|
|
853
|
+
Content-Type: application/json
|
|
854
|
+
|
|
855
|
+
{
|
|
856
|
+
"email": "user@example.com",
|
|
857
|
+
"password": "strongPassword123"
|
|
858
|
+
}
|
|
859
|
+
```
|
|
860
|
+
|
|
861
|
+
Response:
|
|
862
|
+
|
|
863
|
+
```json
|
|
864
|
+
{
|
|
865
|
+
"accessToken": "<jwt_access_token>",
|
|
866
|
+
"refreshToken": "<jwt_refresh_token>"
|
|
867
|
+
}
|
|
868
|
+
```
|
|
869
|
+
|
|
870
|
+
### OAuth login started by another app (multi-app hub)
|
|
871
|
+
|
|
872
|
+
An app other than the hub (e.g. `training`, key `training` in the `app-urls` setting) starts the login by redirecting the browser to:
|
|
873
|
+
|
|
874
|
+
```http
|
|
875
|
+
GET /oauth/google/login?redirectApp=training
|
|
876
|
+
```
|
|
877
|
+
|
|
878
|
+
The backend responds with a 302 `redirect` to Google's authorization URL, containing `state=hhweb.training.login.<signature>`. After consent, Google redirects to the single registered callback (`${url}/callback/google`, the hub). The hub reads the `state`, resolves `training` via `app-urls`, and forwards the browser to `${training-origin}/callback/google/login?code=...&state=...`. The `training` app then exchanges the code:
|
|
879
|
+
|
|
880
|
+
```http
|
|
881
|
+
GET /oauth/google/callback/login?code=<code>&state=hhweb.training.login.<signature>
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
Response:
|
|
885
|
+
|
|
886
|
+
```json
|
|
887
|
+
{
|
|
888
|
+
"accessToken": "<jwt_access_token>"
|
|
889
|
+
}
|
|
890
|
+
```
|
|
891
|
+
|
|
892
|
+
The `refreshToken` is set in the httpOnly `rt` cookie (it is not returned in the body, except when the call provides `redirectUri`, used by the mobile flow).
|
|
893
|
+
|
|
894
|
+
### Get system information
|
|
895
|
+
|
|
896
|
+
```http
|
|
897
|
+
GET /system
|
|
898
|
+
Authorization: Bearer <token>
|
|
899
|
+
```
|
|
900
|
+
|
|
901
|
+
Response (abbreviated example):
|
|
902
|
+
|
|
903
|
+
```json
|
|
904
|
+
{
|
|
905
|
+
"os": {
|
|
906
|
+
"name": "Linux",
|
|
907
|
+
"platform": "linux",
|
|
908
|
+
"version": "5.15.0",
|
|
909
|
+
"architecture": "x64",
|
|
910
|
+
"uptime": 123456,
|
|
911
|
+
"cpu": {
|
|
912
|
+
"model": "Intel(R) Xeon(R)",
|
|
913
|
+
"speed": 2400,
|
|
914
|
+
"physicalCores": 4,
|
|
915
|
+
"virtualCores": 8
|
|
916
|
+
},
|
|
917
|
+
"memory": {
|
|
918
|
+
"total": 17179869184,
|
|
919
|
+
"free": 8589934592
|
|
920
|
+
},
|
|
921
|
+
"disk": [
|
|
922
|
+
{
|
|
923
|
+
"filesystem": "/dev/sda1",
|
|
924
|
+
"size": 500107862016,
|
|
925
|
+
"free": 250053931008,
|
|
926
|
+
"mountpoint": "/"
|
|
927
|
+
}
|
|
928
|
+
]
|
|
929
|
+
},
|
|
930
|
+
"modules": [
|
|
931
|
+
{
|
|
932
|
+
"name": "@hedhog/core",
|
|
933
|
+
"version": "^1.0.0",
|
|
934
|
+
"latestVersion": "1.0.1",
|
|
935
|
+
"upToDate": false
|
|
936
|
+
}
|
|
937
|
+
],
|
|
938
|
+
"users": {
|
|
939
|
+
"total": 100,
|
|
940
|
+
"admin": 5,
|
|
941
|
+
"active": 80,
|
|
942
|
+
"activities": []
|
|
943
|
+
},
|
|
944
|
+
"database": {
|
|
945
|
+
"connections": 10,
|
|
946
|
+
"size": 104857600,
|
|
947
|
+
"queriesPerSecond": 50
|
|
948
|
+
}
|
|
949
|
+
}
|
|
950
|
+
```
|
|
951
|
+
|
|
952
|
+
---
|
|
953
|
+
|
|
954
|
+
This README documents the `@hed-hog/core` module based on the current source code and definitions, providing a detailed technical overview for developers and integrators of the system.
|