@terreno/api 57.0.0 → 57.1.0

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.
Files changed (175) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +8 -0
  2. package/dist/actions.d.ts +7 -2
  3. package/dist/actions.js +60 -25
  4. package/dist/adminModelRouter.d.ts +14 -0
  5. package/dist/adminModelRouter.js +199 -0
  6. package/dist/adminTypes.d.ts +156 -0
  7. package/dist/adminTypes.js +5 -0
  8. package/dist/api.d.ts +44 -3
  9. package/dist/api.js +74 -26
  10. package/dist/auth.d.ts +18 -1
  11. package/dist/auth.js +122 -20
  12. package/dist/consentApp.d.ts +2 -0
  13. package/dist/consentApp.js +98 -0
  14. package/dist/index.d.ts +22 -1
  15. package/dist/index.js +51 -7
  16. package/dist/mcp/auth.d.ts +11 -0
  17. package/dist/mcp/auth.js +133 -0
  18. package/dist/mcp/createMCPRequest.d.ts +16 -0
  19. package/dist/mcp/createMCPRequest.js +26 -0
  20. package/dist/mcp/handlers.d.ts +8 -0
  21. package/dist/mcp/handlers.js +793 -0
  22. package/dist/mcp/query.d.ts +32 -0
  23. package/dist/mcp/query.js +232 -0
  24. package/dist/mcp/registry.d.ts +21 -0
  25. package/dist/mcp/registry.js +54 -0
  26. package/dist/mcp/schemaGenerator.d.ts +14 -0
  27. package/dist/mcp/schemaGenerator.js +379 -0
  28. package/dist/mcp/server.d.ts +8 -0
  29. package/dist/mcp/server.js +133 -0
  30. package/dist/mcp/toolGenerator.d.ts +14 -0
  31. package/dist/mcp/toolGenerator.js +246 -0
  32. package/dist/mcp/types.d.ts +85 -0
  33. package/dist/mcp/types.js +2 -0
  34. package/dist/openApi.d.ts +1 -1
  35. package/dist/openApi.js +26 -8
  36. package/dist/permissions.js +15 -15
  37. package/dist/rbac/access.d.ts +3 -0
  38. package/dist/rbac/access.js +294 -0
  39. package/dist/rbac/auditModel.d.ts +31 -0
  40. package/dist/rbac/auditModel.js +112 -0
  41. package/dist/rbac/backfillAdmins.d.ts +18 -0
  42. package/dist/rbac/backfillAdmins.js +139 -0
  43. package/dist/rbac/fieldViews.d.ts +3 -0
  44. package/dist/rbac/fieldViews.js +201 -0
  45. package/dist/rbac/middleware.d.ts +21 -0
  46. package/dist/rbac/middleware.js +108 -0
  47. package/dist/rbac/modelRouterAccess.d.ts +42 -0
  48. package/dist/rbac/modelRouterAccess.js +388 -0
  49. package/dist/rbac/permissionUtils.d.ts +8 -0
  50. package/dist/rbac/permissionUtils.js +209 -0
  51. package/dist/rbac/realtimeAccess.d.ts +18 -0
  52. package/dist/rbac/realtimeAccess.js +173 -0
  53. package/dist/rbac/resolve.d.ts +28 -0
  54. package/dist/rbac/resolve.js +387 -0
  55. package/dist/rbac/roleManager.d.ts +20 -0
  56. package/dist/rbac/roleManager.js +741 -0
  57. package/dist/rbac/roleModel.d.ts +42 -0
  58. package/dist/rbac/roleModel.js +267 -0
  59. package/dist/rbac/routes.d.ts +9 -0
  60. package/dist/rbac/routes.js +211 -0
  61. package/dist/rbac/scopes.d.ts +15 -0
  62. package/dist/rbac/scopes.js +155 -0
  63. package/dist/rbac/statements.d.ts +20 -0
  64. package/dist/rbac/statements.js +115 -0
  65. package/dist/rbac/types.d.ts +202 -0
  66. package/dist/rbac/types.js +2 -0
  67. package/dist/rbac/userPlugin.d.ts +12 -0
  68. package/dist/rbac/userPlugin.js +41 -0
  69. package/dist/realtime/changeStreamWatcher.d.ts +1 -1
  70. package/dist/realtime/changeStreamWatcher.js +48 -39
  71. package/dist/realtime/realtimeApp.js +4 -8
  72. package/dist/realtime/registry.d.ts +5 -0
  73. package/dist/realtime/registry.js +13 -1
  74. package/dist/scrubAdminFields.d.ts +17 -0
  75. package/dist/scrubAdminFields.js +192 -0
  76. package/dist/sync/executors.d.ts +1 -1
  77. package/dist/sync/executors.js +63 -40
  78. package/dist/sync/loadHarness.js +4 -5
  79. package/dist/sync/registry.d.ts +5 -0
  80. package/dist/sync/registry.js +13 -1
  81. package/dist/sync/routes.js +41 -36
  82. package/dist/sync/serialize.js +5 -6
  83. package/dist/terrenoApp.d.ts +18 -0
  84. package/dist/terrenoApp.js +46 -3
  85. package/dist/terrenoPlugin.d.ts +8 -1
  86. package/dist/tests/createTestData.js +8 -0
  87. package/dist/tests/models.d.ts +1 -0
  88. package/dist/tests/models.js +5 -0
  89. package/dist/tests/testHelper.js +1 -2
  90. package/dist/transformers.js +16 -1
  91. package/package.json +16 -12
  92. package/src/__snapshots__/openApi.test.ts.snap +192 -0
  93. package/src/actions.test.ts +194 -1
  94. package/src/actions.ts +65 -8
  95. package/src/adminModelRouter.ts +154 -0
  96. package/src/adminTypes.ts +183 -0
  97. package/src/api.test.ts +66 -1
  98. package/src/api.ts +131 -12
  99. package/src/auth.test.ts +135 -1
  100. package/src/auth.ts +81 -3
  101. package/src/consentApp.test.ts +24 -0
  102. package/src/consentApp.ts +100 -0
  103. package/src/index.ts +56 -0
  104. package/src/mcp/auth.test.ts +197 -0
  105. package/src/mcp/auth.ts +100 -0
  106. package/src/mcp/createMCPRequest.test.ts +47 -0
  107. package/src/mcp/createMCPRequest.ts +32 -0
  108. package/src/mcp/customTools.test.ts +54 -0
  109. package/src/mcp/handlers.ts +639 -0
  110. package/src/mcp/integration.test.ts +1493 -0
  111. package/src/mcp/query.test.ts +172 -0
  112. package/src/mcp/query.ts +179 -0
  113. package/src/mcp/registry.ts +70 -0
  114. package/src/mcp/schemaGenerator.test.ts +182 -0
  115. package/src/mcp/schemaGenerator.ts +354 -0
  116. package/src/mcp/server.test.ts +226 -0
  117. package/src/mcp/server.ts +86 -0
  118. package/src/mcp/toolGenerator.test.ts +284 -0
  119. package/src/mcp/toolGenerator.ts +199 -0
  120. package/src/mcp/types.ts +95 -0
  121. package/src/openApi.test.ts +107 -0
  122. package/src/openApi.ts +32 -1
  123. package/src/permissions.ts +3 -2
  124. package/src/rbac/access.test.ts +357 -0
  125. package/src/rbac/access.ts +201 -0
  126. package/src/rbac/auditModel.ts +103 -0
  127. package/src/rbac/backfillAdmins.ts +54 -0
  128. package/src/rbac/fieldViews.test.ts +39 -0
  129. package/src/rbac/fieldViews.ts +122 -0
  130. package/src/rbac/middleware.ts +55 -0
  131. package/src/rbac/modelRouterAccess.test.ts +336 -0
  132. package/src/rbac/modelRouterAccess.ts +331 -0
  133. package/src/rbac/permissionUtils.test.ts +112 -0
  134. package/src/rbac/permissionUtils.ts +83 -0
  135. package/src/rbac/realtimeAccess.test.ts +242 -0
  136. package/src/rbac/realtimeAccess.ts +138 -0
  137. package/src/rbac/resolve.test.ts +358 -0
  138. package/src/rbac/resolve.ts +285 -0
  139. package/src/rbac/roleManager.test.ts +915 -0
  140. package/src/rbac/roleManager.ts +440 -0
  141. package/src/rbac/roleModel.test.ts +114 -0
  142. package/src/rbac/roleModel.ts +196 -0
  143. package/src/rbac/routes.ts +170 -0
  144. package/src/rbac/scopes.test.ts +105 -0
  145. package/src/rbac/scopes.ts +81 -0
  146. package/src/rbac/statements.test.ts +65 -0
  147. package/src/rbac/statements.ts +62 -0
  148. package/src/rbac/types.ts +198 -0
  149. package/src/rbac/userPlugin.test.ts +55 -0
  150. package/src/rbac/userPlugin.ts +25 -0
  151. package/src/realtime/changeStreamWatcher.ts +20 -15
  152. package/src/realtime/realtime.test.ts +25 -1
  153. package/src/realtime/realtimeApp.ts +2 -5
  154. package/src/realtime/registry.ts +15 -0
  155. package/src/scrubAdminFields.test.ts +113 -0
  156. package/src/scrubAdminFields.ts +158 -0
  157. package/src/sync/executors.ts +31 -1
  158. package/src/sync/loadHarness.ts +8 -7
  159. package/src/sync/models.test.ts +262 -0
  160. package/src/sync/registry.ts +15 -0
  161. package/src/sync/routes.ts +25 -11
  162. package/src/sync/scripts/compactTombstones.test.ts +4 -6
  163. package/src/sync/serialize.ts +17 -9
  164. package/src/sync/sync.test.ts +52 -0
  165. package/src/sync/syncRoutes.test.ts +5 -2
  166. package/src/sync/syncSocket.test.ts +28 -0
  167. package/src/terrenoApp.test.ts +100 -0
  168. package/src/terrenoApp.ts +65 -3
  169. package/src/terrenoPlugin.ts +10 -1
  170. package/src/tests/bunSetup.ts +2 -0
  171. package/src/tests/createTestData.ts +5 -1
  172. package/src/tests/models.ts +6 -0
  173. package/src/tests/testHelper.ts +1 -3
  174. package/src/transformers.test.ts +12 -0
  175. package/src/transformers.ts +7 -1
package/src/actions.ts CHANGED
@@ -9,6 +9,8 @@ import {loadDocOr404} from "./docLoader";
9
9
  import {APIError, ForbiddenError, ValidationError} from "./errors";
10
10
  import {defaultOpenApiErrorResponses} from "./openApi";
11
11
  import {checkPermissions, type PermissionMethod} from "./permissions";
12
+ import {createIsPermitted} from "./rbac/middleware";
13
+ import type {AnyTerrenoAccess, ModelRouterAccessOptions} from "./rbac/types";
12
14
 
13
15
  // At least two characters: leading letter plus one or more alphanumeric/_/- chars.
14
16
  export const ACTION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]+$/;
@@ -24,7 +26,8 @@ export interface ActionContext<TDoc, TBody, TQuery> {
24
26
 
25
27
  interface BaseActionConfig<TBody, TQuery, TResponse> {
26
28
  method: "GET" | "POST";
27
- permissions: PermissionMethod<unknown>[];
29
+ permissions?: PermissionMethod<unknown>[];
30
+ access?: {resource: string; action: string};
28
31
  body?: ZodSchema<TBody>;
29
32
  query?: ZodSchema<TQuery>;
30
33
  response?: ZodSchema<TResponse>;
@@ -71,15 +74,50 @@ const mapActionToCrudMethod = (scope: ActionScope, httpMethod: "GET" | "POST"):
71
74
  return httpMethod === "GET" ? "list" : "create";
72
75
  };
73
76
 
77
+ const resolveActionAccess = (
78
+ action: BaseActionConfig<unknown, unknown, unknown>,
79
+ scope: ActionScope,
80
+ routerAccess?: ModelRouterAccessOptions
81
+ ): {action: string; resource: string} | null | undefined => {
82
+ if (action.access) {
83
+ return action.access;
84
+ }
85
+ if (!routerAccess?.resource) {
86
+ return undefined;
87
+ }
88
+ const crud = mapActionToCrudMethod(scope, action.method);
89
+ const mapped = routerAccess.actions?.[crud];
90
+ if (mapped === null) {
91
+ return null;
92
+ }
93
+ return {action: mapped ?? crud, resource: routerAccess.resource};
94
+ };
95
+
74
96
  export const runActionPermissions = async <T>(
75
97
  action: BaseActionConfig<unknown, unknown, unknown>,
76
98
  scope: ActionScope,
77
99
  model: Model<T>,
78
100
  req: Request,
79
- doc?: T
101
+ doc?: T,
102
+ accessControl?: AnyTerrenoAccess,
103
+ routerAccess?: ModelRouterAccessOptions
80
104
  ): Promise<void> => {
81
105
  const method = mapActionToCrudMethod(scope, action.method);
82
- const allowed = await checkPermissions(method, action.permissions, req.user, doc);
106
+ let permissions = action.permissions;
107
+ const rbacAccess = resolveActionAccess(action, scope, routerAccess);
108
+ if (rbacAccess === null || permissions?.length === 0) {
109
+ permissions = [];
110
+ } else if (rbacAccess && accessControl) {
111
+ const isPermitted = createIsPermitted({can: accessControl.can});
112
+ const rbacCheck = isPermitted({
113
+ [rbacAccess.resource]: [rbacAccess.action],
114
+ }) as PermissionMethod<unknown>;
115
+ permissions = [...(action.permissions ?? []), rbacCheck];
116
+ }
117
+ if (!permissions) {
118
+ throw new APIError({status: 500, title: "Action missing permissions configuration"});
119
+ }
120
+ const allowed = await checkPermissions(method, permissions, req.user, doc);
83
121
  if (allowed) {
84
122
  return;
85
123
  }
@@ -301,12 +339,15 @@ const validateActionConfig = (
301
339
  `Invalid action name "${name}". Action names must match ${ACTION_NAME_PATTERN.toString()}`
302
340
  );
303
341
  }
304
- if (config.permissions === undefined) {
342
+ if (config.permissions === undefined && !config.access) {
305
343
  throw new Error(
306
- `Action "${name}" (${scope}) is missing required "permissions". ` +
307
- "Provide at least one permission function, or [] to disable the action."
344
+ `Action "${name}" (${scope}) is missing required "permissions" or "access". ` +
345
+ "Provide at least one permission function, an access descriptor, or [] to disable the action."
308
346
  );
309
347
  }
348
+ if (config.permissions !== undefined && config.permissions.length === 0 && !config.access) {
349
+ return;
350
+ }
310
351
  if (config.method !== "GET" && config.method !== "POST") {
311
352
  throw new Error(`Action "${name}" (${scope}) only supports GET and POST methods`);
312
353
  }
@@ -353,7 +394,15 @@ const buildActionMiddleware = <T>(
353
394
 
354
395
  const preDocPermissions = async (req: Request, _res: Response, next: NextFunction) => {
355
396
  try {
356
- await runActionPermissions(action, scope, model, req);
397
+ await runActionPermissions(
398
+ action,
399
+ scope,
400
+ model,
401
+ req,
402
+ undefined,
403
+ options.accessControl,
404
+ options.access
405
+ );
357
406
  return next();
358
407
  } catch (error) {
359
408
  return next(error);
@@ -370,7 +419,15 @@ const buildActionMiddleware = <T>(
370
419
  options.populatePaths
371
420
  );
372
421
  (req as Request & {obj?: T}).obj = doc;
373
- await runActionPermissions(action, scope, model, req, doc);
422
+ await runActionPermissions(
423
+ action,
424
+ scope,
425
+ model,
426
+ req,
427
+ doc,
428
+ options.accessControl,
429
+ options.access
430
+ );
374
431
  return next();
375
432
  } catch (error) {
376
433
  return next(error);
@@ -0,0 +1,154 @@
1
+ import {DateTime} from "luxon";
2
+ import type {Document, Model} from "mongoose";
3
+
4
+ import type {AdminChangeEvent, AdminConfig} from "./adminTypes";
5
+ import type {ModelRouterOptions} from "./api";
6
+ import type {AnyTerrenoAccess} from "./rbac/types";
7
+ import {scrubAdminFields, stripAdminBodyFields} from "./scrubAdminFields";
8
+ import type {TerrenoApp} from "./terrenoApp";
9
+
10
+ export interface ModelRouterBuildContext {
11
+ accessControl?: AnyTerrenoAccess;
12
+ openApi?: ModelRouterOptions<unknown>["openApi"];
13
+ routePath?: string;
14
+ terrenoApp?: TerrenoApp;
15
+ }
16
+
17
+ const emitAdminModelChanged = <T>({
18
+ admin,
19
+ doc,
20
+ model,
21
+ req,
22
+ routePath,
23
+ terrenoApp,
24
+ type,
25
+ }: {
26
+ admin: AdminConfig;
27
+ doc: Document<unknown, unknown, unknown> & T;
28
+ model: Model<T>;
29
+ req: import("express").Request;
30
+ routePath: string;
31
+ terrenoApp: TerrenoApp;
32
+ type: AdminChangeEvent["type"];
33
+ }): void => {
34
+ const userId = req.user?._id ?? req.user?.id;
35
+ if (!userId) {
36
+ return;
37
+ }
38
+
39
+ const event: AdminChangeEvent = {
40
+ at: DateTime.utc().toISO(),
41
+ documentId: String(doc._id),
42
+ modelName: model.modelName,
43
+ routePath,
44
+ type,
45
+ user: {id: String(userId)},
46
+ };
47
+
48
+ if (type !== "delete") {
49
+ event.document = scrubAdminFields(doc, {
50
+ admin,
51
+ schema: model.schema,
52
+ });
53
+ }
54
+
55
+ terrenoApp.emitAdminModelChanged(event);
56
+ };
57
+
58
+ /**
59
+ * Wraps modelRouter lifecycle hooks to enforce admin body scrubbing and optional realtime emits.
60
+ */
61
+ export const enrichModelRouterOptions = <T>(
62
+ model: Model<T>,
63
+ options: ModelRouterOptions<T>,
64
+ context: ModelRouterBuildContext
65
+ ): ModelRouterOptions<T> => {
66
+ const openApi = context.openApi ?? options.openApi;
67
+ const admin = options.admin;
68
+ const routePath = context.routePath;
69
+ const terrenoApp = context.terrenoApp;
70
+
71
+ if (!admin) {
72
+ return openApi ? {...options, openApi} : options;
73
+ }
74
+
75
+ const userPreCreate = options.preCreate;
76
+ const userPreUpdate = options.preUpdate;
77
+ const userPostCreate = options.postCreate;
78
+ const userPostUpdate = options.postUpdate;
79
+ const userPostDelete = options.postDelete;
80
+
81
+ return {
82
+ ...options,
83
+ openApi,
84
+ postCreate: async (value, request) => {
85
+ if (userPostCreate) {
86
+ await userPostCreate(value, request);
87
+ }
88
+ if (admin.realtime && terrenoApp && routePath) {
89
+ emitAdminModelChanged({
90
+ admin,
91
+ doc: value as Document<unknown, unknown, unknown> & T,
92
+ model,
93
+ req: request,
94
+ routePath,
95
+ terrenoApp,
96
+ type: "create",
97
+ });
98
+ }
99
+ },
100
+ postDelete: async (request, value) => {
101
+ if (userPostDelete) {
102
+ await userPostDelete(request, value);
103
+ }
104
+ if (admin.realtime && terrenoApp && routePath) {
105
+ emitAdminModelChanged({
106
+ admin,
107
+ doc: value as Document<unknown, unknown, unknown> & T,
108
+ model,
109
+ req: request,
110
+ routePath,
111
+ terrenoApp,
112
+ type: "delete",
113
+ });
114
+ }
115
+ },
116
+ postUpdate: async (value, cleanedBody, request, prevValue) => {
117
+ if (userPostUpdate) {
118
+ await userPostUpdate(value, cleanedBody, request, prevValue);
119
+ }
120
+ if (admin.realtime && terrenoApp && routePath) {
121
+ emitAdminModelChanged({
122
+ admin,
123
+ doc: value as Document<unknown, unknown, unknown> & T,
124
+ model,
125
+ req: request,
126
+ routePath,
127
+ terrenoApp,
128
+ type: "update",
129
+ });
130
+ }
131
+ },
132
+ preCreate: async (value, request) => {
133
+ let body = stripAdminBodyFields(
134
+ value as Record<string, unknown> | Record<string, unknown>[] | null | undefined,
135
+ admin
136
+ ) as typeof value;
137
+ if (userPreCreate) {
138
+ body = await userPreCreate(body, request);
139
+ }
140
+ return body;
141
+ },
142
+ preUpdate: async (value, request) => {
143
+ let body = stripAdminBodyFields(value, admin) as Partial<T>;
144
+ if (userPreUpdate) {
145
+ const next = await userPreUpdate(body, request);
146
+ if (next === null) {
147
+ return null;
148
+ }
149
+ body = next;
150
+ }
151
+ return body;
152
+ },
153
+ } as ModelRouterOptions<T>;
154
+ };
@@ -0,0 +1,183 @@
1
+ import type express from "express";
2
+ import type {Model} from "mongoose";
3
+
4
+ import type {PermissionMethod, RESTPermissions} from "./permissions";
5
+ import type {PopulatePath} from "./populate";
6
+ import type {ScriptArgDef, ScriptRunner} from "./scriptRunner";
7
+
8
+ /** Server-side cap on bulk action id lists (v2 bulk-patch). */
9
+ export const MAX_BULK_PATCH_IDS = 1000;
10
+
11
+ export type AdminFilterKind = "boolean" | "choice" | "dateRange" | "ref" | "text";
12
+
13
+ export interface AdminFilterBoolean {
14
+ field: string;
15
+ kind: "boolean";
16
+ label?: string;
17
+ }
18
+
19
+ export interface AdminFilterChoice {
20
+ choices: {label: string; value: string}[];
21
+ field: string;
22
+ kind: "choice";
23
+ label?: string;
24
+ }
25
+
26
+ export interface AdminFilterDateRange {
27
+ field: string;
28
+ kind: "dateRange";
29
+ label?: string;
30
+ }
31
+
32
+ export interface AdminFilterRef {
33
+ field: string;
34
+ kind: "ref";
35
+ label?: string;
36
+ refModel?: string;
37
+ }
38
+
39
+ export interface AdminFilterText {
40
+ field: string;
41
+ kind: "text";
42
+ label?: string;
43
+ }
44
+
45
+ export type AdminFilter =
46
+ | AdminFilterBoolean
47
+ | AdminFilterChoice
48
+ | AdminFilterDateRange
49
+ | AdminFilterRef
50
+ | AdminFilterText;
51
+
52
+ export interface AdminFieldset {
53
+ collapsed?: boolean;
54
+ description?: string;
55
+ fields: string[];
56
+ title: string;
57
+ }
58
+
59
+ export interface AdminFieldOverride {
60
+ helpText?: string;
61
+ label?: string;
62
+ widget?: string;
63
+ }
64
+
65
+ /** Declarative bulk action (v2 bulk-patch / background-tasks — no imperative run handler). */
66
+ export interface AdminAction {
67
+ background?: boolean;
68
+ confirm?: string;
69
+ id: string;
70
+ label: string;
71
+ /** Keys allowed for synchronous bulk-patch actions */
72
+ patchKeys?: string[];
73
+ }
74
+
75
+ export interface AdminModelPermissions {
76
+ create?: boolean;
77
+ delete?: boolean;
78
+ update?: boolean;
79
+ }
80
+
81
+ export interface AdminConfig {
82
+ displayName: string;
83
+ group?: string;
84
+ icon?: string;
85
+ listFields: string[];
86
+ listDisplay?: string[];
87
+ listDisplayLinks?: string[];
88
+ searchFields?: string[];
89
+ sortableFields?: string[];
90
+ defaultSort?: string | string[];
91
+ pageSize?: number;
92
+ filters?: AdminFilter[];
93
+ fieldsets?: AdminFieldset[];
94
+ fieldOrder?: string[];
95
+ readonlyFields?: string[];
96
+ excludeFields?: string[];
97
+ hiddenFields?: string[];
98
+ autocompleteFields?: string[];
99
+ fieldOverrides?: Record<string, AdminFieldOverride>;
100
+ adminPermissions?: Partial<{
101
+ create: PermissionMethod<unknown>[];
102
+ delete: PermissionMethod<unknown>[];
103
+ list: PermissionMethod<unknown>[];
104
+ read: PermissionMethod<unknown>[];
105
+ update: PermissionMethod<unknown>[];
106
+ }>;
107
+ adminFilter?: (
108
+ req: express.Request
109
+ ) => Record<string, unknown> | Promise<Record<string, unknown>>;
110
+ actions?: AdminAction[];
111
+ /** When true, scrubbed `admin:model.changed` events fire after mutations (no socket transport). */
112
+ realtime?: boolean;
113
+ /** Forward-compat placeholder — no behavior in v1. */
114
+ includeDeleted?: boolean;
115
+ bulkPatchAllowlist?: string[];
116
+ recordTitleField?: string;
117
+ }
118
+
119
+ export interface AdminScriptContribution {
120
+ args?: ScriptArgDef[];
121
+ description: string;
122
+ name: string;
123
+ runner: ScriptRunner;
124
+ }
125
+
126
+ export interface AdminCustomScreen {
127
+ displayName: string;
128
+ group?: string;
129
+ icon?: string;
130
+ name: string;
131
+ }
132
+
133
+ export interface AdminHomeSlots {
134
+ contentTop?: string[];
135
+ main?: string[];
136
+ navGlobal?: string[];
137
+ sidebar?: string[];
138
+ }
139
+
140
+ export interface AdminHomeConfig {
141
+ slots?: AdminHomeSlots;
142
+ title?: string;
143
+ /** Legacy widget ids; normalized to `slots.main` by admin-backend when slots omitted. */
144
+ widgets?: string[];
145
+ }
146
+
147
+ export interface AdminHomeWidgetContribution {
148
+ displayName: string;
149
+ icon?: string;
150
+ id: string;
151
+ watches?: string[];
152
+ }
153
+
154
+ export interface AdminModelContribution<T = unknown> {
155
+ admin: AdminConfig;
156
+ model: Model<T>;
157
+ permissions?: RESTPermissions<T>;
158
+ populatePaths?: PopulatePath[];
159
+ routePath: string;
160
+ }
161
+
162
+ export interface AdminContribution {
163
+ customScreens?: AdminCustomScreen[];
164
+ homeWidgets?: AdminHomeWidgetContribution[];
165
+ models?: AdminModelContribution[];
166
+ scripts?: AdminScriptContribution[];
167
+ }
168
+
169
+ export type AdminChangeType = "create" | "delete" | "update";
170
+
171
+ export interface AdminChangeEvent {
172
+ at: string;
173
+ document?: unknown;
174
+ documentId: string;
175
+ modelName: string;
176
+ routePath: string;
177
+ type: AdminChangeType;
178
+ user: {id: string};
179
+ }
180
+
181
+ export type AdminModelAdminMap = Record<string, AdminConfig>;
182
+
183
+ export type TerrenoAppAdminEvent = "admin:model.changed";
package/src/api.test.ts CHANGED
@@ -11,6 +11,7 @@ import type TestAgent from "supertest/lib/agent";
11
11
  import {addPopulateToQuery, modelRouter} from "./api";
12
12
  import {addAuthRoutes, setupAuth} from "./auth";
13
13
  import {APIError} from "./errors";
14
+ import {clearMCPRegistry, getMCPRegistry} from "./mcp/registry";
14
15
  import {Permissions} from "./permissions";
15
16
  import {
16
17
  authAsUser,
@@ -2131,7 +2132,71 @@ describe("@terreno/api", () => {
2131
2132
  expect(registration).toHaveProperty("__type", "modelRouter");
2132
2133
  expect(registration).toHaveProperty("path", "/food");
2133
2134
  expect(registration).toHaveProperty("router");
2134
- expect(registration).toHaveProperty("_buildWithOpenApi");
2135
+ expect(registration).toHaveProperty("_buildWithContext");
2136
+ expect(registration).toHaveProperty("model");
2137
+ expect(registration).toHaveProperty("options");
2138
+ });
2139
+
2140
+ it("refreshes MCP registry options when rebuilt with accessControl", () => {
2141
+ clearMCPRegistry();
2142
+ const registration = modelRouter("/food", FoodModel, {
2143
+ access: {resource: "food"},
2144
+ mcp: {methods: ["list"]},
2145
+ permissions: {
2146
+ create: [Permissions.IsAny],
2147
+ delete: [Permissions.IsAny],
2148
+ list: [Permissions.IsAny],
2149
+ read: [Permissions.IsAny],
2150
+ update: [Permissions.IsAny],
2151
+ },
2152
+ });
2153
+ const before = getMCPRegistry()[0]?.options.permissions.list;
2154
+ expect(before).toEqual([Permissions.IsAny]);
2155
+
2156
+ const accessControl = {
2157
+ can: async (): Promise<{allowed: boolean}> => ({allowed: true}),
2158
+ fieldMask: async (): Promise<{omit: string[]; read: "*"; write: "*"}> => ({
2159
+ omit: [],
2160
+ read: "*",
2161
+ write: "*",
2162
+ }),
2163
+ queryFilter: async (): Promise<Record<string, unknown>> => ({}),
2164
+ statements: {food: ["list", "read", "create", "update", "delete"]},
2165
+ };
2166
+ registration._buildWithContext({accessControl: accessControl as never});
2167
+
2168
+ const after = getMCPRegistry()[0];
2169
+ expect(after?.options.accessControl).toBe(accessControl);
2170
+ expect(after?.options.permissions.list).not.toBe(before);
2171
+ });
2172
+
2173
+ it("resolves MCP permissions when accessControl is passed to modelRouter", () => {
2174
+ clearMCPRegistry();
2175
+ const accessControl = {
2176
+ can: async (): Promise<{allowed: boolean}> => ({allowed: true}),
2177
+ fieldMask: async (): Promise<{omit: string[]; read: "*"; write: "*"}> => ({
2178
+ omit: [],
2179
+ read: "*",
2180
+ write: "*",
2181
+ }),
2182
+ queryFilter: async (): Promise<Record<string, unknown>> => ({}),
2183
+ statements: {food: ["list", "read", "create", "update", "delete"]},
2184
+ };
2185
+ modelRouter(FoodModel, {
2186
+ access: {resource: "food"},
2187
+ accessControl: accessControl as never,
2188
+ mcp: {methods: ["list"]},
2189
+ permissions: {
2190
+ create: [Permissions.IsAny],
2191
+ delete: [Permissions.IsAny],
2192
+ list: [Permissions.IsAny],
2193
+ read: [Permissions.IsAny],
2194
+ update: [Permissions.IsAny],
2195
+ },
2196
+ });
2197
+ const registered = getMCPRegistry()[0];
2198
+ expect(registered?.options.accessControl).toBe(accessControl);
2199
+ expect(registered?.options.permissions.list).not.toEqual([Permissions.IsAny]);
2135
2200
  });
2136
2201
 
2137
2202
  it("logs a warning when realtime config is used without the path form", () => {