@terreno/api 57.0.0-beta.1 → 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
@@ -0,0 +1,242 @@
1
+ import {describe, expect, it} from "bun:test";
2
+ import mongoose from "mongoose";
3
+
4
+ import type {User} from "../auth";
5
+ import {Permissions} from "../permissions";
6
+ import type {RealtimeRegistryEntry} from "../realtime/registry";
7
+ import {setupDb} from "../tests";
8
+ import {createAccess} from "./access";
9
+ import {
10
+ canReadDocumentRealtime,
11
+ canSubscribeRealtime,
12
+ maskRealtimeDocument,
13
+ } from "./realtimeAccess";
14
+ import {OwnerScope} from "./scopes";
15
+ import {terrenoStatements} from "./statements";
16
+ import type {AnyTerrenoAccess} from "./types";
17
+
18
+ const appStatements = {
19
+ ...terrenoStatements,
20
+ todo: ["create", "read", "update", "delete", "list"],
21
+ } as const;
22
+
23
+ const createTestUser = (
24
+ overrides: Partial<User & {roles: string[]}> = {}
25
+ ): User & {roles: string[]} => {
26
+ const id = new mongoose.Types.ObjectId();
27
+ return {
28
+ _id: id as unknown as User["_id"],
29
+ admin: false,
30
+ id: id.toString(),
31
+ roles: [],
32
+ ...overrides,
33
+ };
34
+ };
35
+
36
+ const makeEntry = (options: RealtimeRegistryEntry["options"]): RealtimeRegistryEntry => ({
37
+ collectionName: "todos",
38
+ config: {methods: ["create", "update", "delete"], roomStrategy: "owner"},
39
+ modelName: "Todo",
40
+ options,
41
+ routePath: "/todos",
42
+ });
43
+
44
+ describe("realtimeAccess", () => {
45
+ it("uses accessControl permissions for subscriptions", async () => {
46
+ await setupDb();
47
+ const access = createAccess({
48
+ connection: mongoose.connection,
49
+ defaultRoles: [
50
+ {
51
+ displayName: "Reader",
52
+ name: "reader",
53
+ permissions: {todo: ["read", "list"]},
54
+ },
55
+ ],
56
+ statements: appStatements,
57
+ });
58
+ await access.roles.seedDefaults();
59
+
60
+ const user = createTestUser({roles: ["reader"]});
61
+ const entry = makeEntry({
62
+ access: {resource: "todo"},
63
+ accessControl: access as AnyTerrenoAccess,
64
+ });
65
+
66
+ expect(await canSubscribeRealtime(entry, "list", user)).toBe(true);
67
+ expect(await canSubscribeRealtime(entry, "read", user)).toBe(true);
68
+ });
69
+
70
+ it("returns false when the realtime action override is null", async () => {
71
+ await setupDb();
72
+ const access = createAccess({
73
+ connection: mongoose.connection,
74
+ statements: appStatements,
75
+ });
76
+ await access.roles.seedDefaults();
77
+
78
+ const user = createTestUser({roles: ["superadmin"]});
79
+ const entry = makeEntry({
80
+ access: {actions: {list: null}, resource: "todo"},
81
+ accessControl: access as AnyTerrenoAccess,
82
+ });
83
+
84
+ expect(await canSubscribeRealtime(entry, "list", user)).toBe(false);
85
+ });
86
+
87
+ it("honors custom action overrides for realtime subscriptions", async () => {
88
+ await setupDb();
89
+ const access = createAccess({
90
+ connection: mongoose.connection,
91
+ defaultRoles: [
92
+ {
93
+ displayName: "Updater",
94
+ name: "updater",
95
+ permissions: {todo: ["update"]},
96
+ },
97
+ ],
98
+ statements: appStatements,
99
+ });
100
+ await access.roles.seedDefaults();
101
+
102
+ const user = createTestUser({roles: ["updater"]});
103
+ const entry = makeEntry({
104
+ access: {actions: {list: "update"}, resource: "todo"},
105
+ accessControl: access as AnyTerrenoAccess,
106
+ });
107
+
108
+ expect(await canSubscribeRealtime(entry, "list", user)).toBe(true);
109
+ });
110
+
111
+ it("falls back to legacy permissions when access config is absent", async () => {
112
+ const user = createTestUser({admin: true});
113
+ const entry = makeEntry({
114
+ permissions: {
115
+ create: [Permissions.IsAdmin],
116
+ delete: [Permissions.IsAdmin],
117
+ list: [Permissions.IsAdmin],
118
+ read: [Permissions.IsAdmin],
119
+ update: [Permissions.IsAdmin],
120
+ },
121
+ });
122
+
123
+ expect(await canSubscribeRealtime(entry, "list", user)).toBe(true);
124
+ expect(await canSubscribeRealtime(entry, "list", createTestUser())).toBe(false);
125
+ });
126
+
127
+ it("checks document-level access with scopes", async () => {
128
+ await setupDb();
129
+ const access = createAccess({
130
+ connection: mongoose.connection,
131
+ defaultRoles: [
132
+ {
133
+ displayName: "Reader",
134
+ name: "reader",
135
+ permissions: {todo: ["read"]},
136
+ },
137
+ ],
138
+ scopes: {
139
+ "todo.read": OwnerScope(),
140
+ },
141
+ statements: appStatements,
142
+ });
143
+ await access.roles.seedDefaults();
144
+
145
+ const user = createTestUser({roles: ["reader"]});
146
+ const entry = makeEntry({
147
+ access: {resource: "todo"},
148
+ accessControl: access as AnyTerrenoAccess,
149
+ });
150
+
151
+ expect(await canReadDocumentRealtime(entry, user, {ownerId: user.id, title: "Mine"})).toBe(
152
+ true
153
+ );
154
+ expect(
155
+ await canReadDocumentRealtime(entry, user, {
156
+ ownerId: new mongoose.Types.ObjectId().toString(),
157
+ title: "Other",
158
+ })
159
+ ).toBe(false);
160
+ });
161
+
162
+ it("applies per-router access.scope on realtime document reads", async () => {
163
+ await setupDb();
164
+ const access = createAccess({
165
+ connection: mongoose.connection,
166
+ defaultRoles: [
167
+ {
168
+ displayName: "Reader",
169
+ name: "reader",
170
+ permissions: {todo: ["read"]},
171
+ },
172
+ ],
173
+ statements: appStatements,
174
+ });
175
+ await access.roles.seedDefaults();
176
+
177
+ const user = createTestUser({roles: ["reader"]});
178
+ const entry = makeEntry({
179
+ access: {
180
+ resource: "todo",
181
+ scope: {
182
+ check: ({doc}) => (doc as {ownerId?: string} | undefined)?.ownerId === user.id,
183
+ },
184
+ },
185
+ accessControl: access as AnyTerrenoAccess,
186
+ });
187
+
188
+ expect(await canReadDocumentRealtime(entry, user, {ownerId: user.id, title: "Mine"})).toBe(
189
+ true
190
+ );
191
+ expect(
192
+ await canReadDocumentRealtime(entry, user, {
193
+ ownerId: new mongoose.Types.ObjectId().toString(),
194
+ title: "Other",
195
+ })
196
+ ).toBe(false);
197
+ });
198
+
199
+ it("masks realtime documents using field views", async () => {
200
+ await setupDb();
201
+ const access = createAccess({
202
+ connection: mongoose.connection,
203
+ defaultRoles: [
204
+ {
205
+ displayName: "Reader",
206
+ name: "reader",
207
+ permissions: {todo: ["read"]},
208
+ },
209
+ ],
210
+ fieldViews: {
211
+ todo: {
212
+ select: () => "public",
213
+ views: {
214
+ public: {omit: [], read: ["title"], write: ["title"]},
215
+ },
216
+ },
217
+ },
218
+ statements: appStatements,
219
+ });
220
+ await access.roles.seedDefaults();
221
+
222
+ const user = createTestUser({roles: ["reader"]});
223
+ const entry = makeEntry({
224
+ access: {resource: "todo"},
225
+ accessControl: access as AnyTerrenoAccess,
226
+ });
227
+
228
+ const masked = await maskRealtimeDocument(
229
+ entry,
230
+ user,
231
+ {secret: "hidden", title: "Visible"},
232
+ "read"
233
+ );
234
+ expect(masked).toEqual({title: "Visible"});
235
+ });
236
+
237
+ it("returns documents unchanged when access config is missing", async () => {
238
+ const entry = makeEntry({});
239
+ const doc = {title: "Plain"};
240
+ expect(await maskRealtimeDocument(entry, undefined, doc, "read")).toBe(doc);
241
+ });
242
+ });
@@ -0,0 +1,138 @@
1
+ import type {RESTMethod} from "../api";
2
+ import type {User} from "../auth";
3
+ import {checkPermissions, type PermissionMethod} from "../permissions";
4
+ import {applyReadMask} from "./fieldViews";
5
+ import type {AnyTerrenoAccess, ModelRouterAccessOptions} from "./types";
6
+
7
+ interface RealtimeAccessEntry {
8
+ options: {
9
+ access?: ModelRouterAccessOptions;
10
+ accessControl?: AnyTerrenoAccess;
11
+ permissions?: {read?: PermissionMethod<unknown>[]; list?: PermissionMethod<unknown>[]};
12
+ };
13
+ }
14
+
15
+ const DEFAULT_METHOD_ACTIONS: Record<"list" | "read", string> = {
16
+ list: "list",
17
+ read: "read",
18
+ };
19
+
20
+ const resolveActionForMethod = (
21
+ method: "list" | "read",
22
+ access: ModelRouterAccessOptions,
23
+ statements: Record<string, readonly string[]>
24
+ ): string | null => {
25
+ const override = access.actions?.[method];
26
+ if (override === null) {
27
+ return null;
28
+ }
29
+ if (override) {
30
+ return override;
31
+ }
32
+
33
+ const resourceActions = statements[access.resource] ?? [];
34
+ if (method === "list" && resourceActions.includes("list")) {
35
+ return "list";
36
+ }
37
+ if (method === "list") {
38
+ return "read";
39
+ }
40
+ return DEFAULT_METHOD_ACTIONS[method];
41
+ };
42
+
43
+ export const canSubscribeRealtime = async (
44
+ entry: RealtimeAccessEntry,
45
+ method: "list" | "read",
46
+ user?: User
47
+ ): Promise<boolean> => {
48
+ const access = entry.options.access;
49
+ const accessControl = entry.options.accessControl;
50
+ if (access && accessControl) {
51
+ const statements = accessControl.statements as Record<string, readonly string[]>;
52
+ const action = resolveActionForMethod(method, access, statements);
53
+ if (!action) {
54
+ return false;
55
+ }
56
+ const result = await accessControl.can({
57
+ context: {transport: "socket"},
58
+ permissions: {[access.resource]: [action]},
59
+ user,
60
+ });
61
+ return result.allowed;
62
+ }
63
+
64
+ const permissions = entry.options.permissions?.[method] ?? [];
65
+ return checkPermissions(method, permissions, user);
66
+ };
67
+
68
+ export const canReadDocumentRealtime = async (
69
+ entry: RealtimeAccessEntry,
70
+ user?: User,
71
+ doc?: Record<string, unknown>
72
+ ): Promise<boolean> => {
73
+ const access = entry.options.access;
74
+ const accessControl = entry.options.accessControl;
75
+ if (access && accessControl) {
76
+ const statements = accessControl.statements as Record<string, readonly string[]>;
77
+ const action = resolveActionForMethod("read", access, statements);
78
+ if (!action) {
79
+ return false;
80
+ }
81
+ const result = await accessControl.can({
82
+ context: {transport: "socket"},
83
+ doc,
84
+ permissions: {[access.resource]: [action]},
85
+ user,
86
+ });
87
+ if (!result.allowed) {
88
+ return false;
89
+ }
90
+ if (access.scope?.check) {
91
+ if (!user) {
92
+ return false;
93
+ }
94
+ const scopeResult = await access.scope.check({
95
+ action,
96
+ doc,
97
+ user,
98
+ });
99
+ if (scopeResult === false) {
100
+ return false;
101
+ }
102
+ if (scopeResult && typeof scopeResult === "object") {
103
+ const extra = await accessControl.can({
104
+ context: {transport: "socket"},
105
+ doc,
106
+ permissions: scopeResult as never,
107
+ user,
108
+ });
109
+ return extra.allowed;
110
+ }
111
+ }
112
+ return true;
113
+ }
114
+
115
+ return checkPermissions("read", entry.options.permissions?.read ?? [], user, doc);
116
+ };
117
+
118
+ export const maskRealtimeDocument = async (
119
+ entry: RealtimeAccessEntry,
120
+ user: User | undefined,
121
+ doc: unknown,
122
+ _method: RESTMethod
123
+ ): Promise<unknown> => {
124
+ const access = entry.options.access;
125
+ const accessControl = entry.options.accessControl;
126
+ if (!access || !accessControl) {
127
+ return doc;
128
+ }
129
+
130
+ const phase = "read";
131
+ const mask = await accessControl.fieldMask({
132
+ doc,
133
+ phase,
134
+ resource: access.resource,
135
+ user,
136
+ });
137
+ return applyReadMask(doc, mask);
138
+ };