@terreno/api 57.21.0 → 58.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +1 -1
  3. package/biome.jsonc +2 -2
  4. package/dist/api.d.ts +0 -13
  5. package/dist/api.js +0 -9
  6. package/dist/auth.d.ts +3 -2
  7. package/dist/auth.js +95 -5
  8. package/dist/authRecovery.d.ts +2 -1
  9. package/dist/authRecovery.js +35 -17
  10. package/dist/collectionRegistry.d.ts +3 -4
  11. package/dist/collectionRegistry.js +0 -1
  12. package/dist/consentApp.d.ts +1 -1
  13. package/dist/consentApp.js +58 -2
  14. package/dist/index.d.ts +4 -5
  15. package/dist/index.js +8 -20
  16. package/dist/mcp/adminTracking.js +1 -1
  17. package/dist/mcp/serviceTokens.d.ts +21 -1
  18. package/dist/mcp/serviceTokens.js +159 -183
  19. package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
  20. package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
  21. package/dist/models/mcpRequestLog.js +1 -1
  22. package/dist/models/mcpServiceToken.js +36 -4
  23. package/dist/openApiBuilder.d.ts +4 -0
  24. package/dist/openApiBuilder.js +2 -0
  25. package/dist/rbac/realtimeAccess.d.ts +5 -4
  26. package/dist/rbac/realtimeAccess.js +17 -64
  27. package/dist/realtime/changeStreamWatcher.d.ts +8 -63
  28. package/dist/realtime/changeStreamWatcher.js +32 -391
  29. package/dist/realtime/realtimeApp.d.ts +14 -27
  30. package/dist/realtime/realtimeApp.js +14 -220
  31. package/dist/realtime/types.d.ts +0 -64
  32. package/dist/sync/executors.js +14 -2
  33. package/dist/sync/socketHandlers.d.ts +1 -1
  34. package/dist/sync/socketHandlers.js +1 -1
  35. package/dist/terrenoApp.d.ts +7 -5
  36. package/dist/terrenoApp.js +18 -14
  37. package/dist/tests/openApiResponseSchema.d.ts +39 -0
  38. package/dist/tests/openApiResponseSchema.js +56 -0
  39. package/dist/tests.d.ts +1 -0
  40. package/dist/tests.js +4 -1
  41. package/dist/types/mcpAdmin.d.ts +1 -1
  42. package/dist/types/mcpServiceToken.d.ts +7 -4
  43. package/dist/versionCheckPlugin.d.ts +1 -1
  44. package/dist/versionCheckPlugin.js +25 -2
  45. package/package.json +10 -6
  46. package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
  47. package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
  48. package/src/__tests__/openApiResponseSchema.test.ts +148 -0
  49. package/src/__tests__/versionCheckPlugin.test.ts +72 -0
  50. package/src/api.test.ts +9 -7
  51. package/src/api.ts +0 -24
  52. package/src/auth.ts +116 -5
  53. package/src/authOpenApi.test.ts +316 -0
  54. package/src/authRecovery.ts +47 -19
  55. package/src/betterAuthOAuthHandoff.test.ts +13 -5
  56. package/src/collectionRegistry.ts +3 -5
  57. package/src/consentApp.test.ts +98 -0
  58. package/src/consentApp.ts +67 -2
  59. package/src/index.ts +6 -28
  60. package/src/mcp/actionTools.test.ts +2 -2
  61. package/src/mcp/adminTracking.ts +1 -1
  62. package/src/mcp/auth.test.ts +7 -3
  63. package/src/mcp/oauth.test.ts +12 -12
  64. package/src/mcp/serviceTokens.sync.test.ts +230 -0
  65. package/src/mcp/serviceTokens.test.ts +112 -61
  66. package/src/mcp/serviceTokens.ts +193 -212
  67. package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
  68. package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
  69. package/src/models/mcpRequestLog.ts +1 -1
  70. package/src/models/mcpServiceToken.test.ts +52 -5
  71. package/src/models/mcpServiceToken.ts +51 -14
  72. package/src/openApiBuilder.test.ts +34 -1
  73. package/src/openApiBuilder.ts +5 -0
  74. package/src/rateLimit/rateLimit.test.ts +25 -10
  75. package/src/rbac/realtimeAccess.test.ts +20 -172
  76. package/src/rbac/realtimeAccess.ts +17 -82
  77. package/src/realtime/changeStreamWatcher.ts +43 -506
  78. package/src/realtime/realtime.test.ts +205 -2545
  79. package/src/realtime/realtimeApp.ts +16 -295
  80. package/src/realtime/types.ts +0 -72
  81. package/src/sync/executors.test.ts +28 -0
  82. package/src/sync/executors.ts +23 -2
  83. package/src/sync/socketHandlers.ts +1 -1
  84. package/src/sync/syncSocket.test.ts +77 -113
  85. package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
  86. package/src/terrenoApp.ts +24 -18
  87. package/src/tests/openApiResponseSchema.ts +104 -0
  88. package/src/tests.ts +7 -0
  89. package/src/types/mcpAdmin.ts +1 -1
  90. package/src/types/mcpServiceToken.ts +7 -4
  91. package/src/versionCheckPlugin.ts +41 -2
  92. package/dist/realtime/deprecation.d.ts +0 -13
  93. package/dist/realtime/deprecation.js +0 -31
  94. package/dist/realtime/queryStore.d.ts +0 -37
  95. package/dist/realtime/queryStore.js +0 -103
  96. package/dist/realtime/registry.d.ts +0 -15
  97. package/dist/realtime/registry.js +0 -52
  98. package/src/realtime/deprecation.test.ts +0 -60
  99. package/src/realtime/deprecation.ts +0 -33
  100. package/src/realtime/queryStore.ts +0 -122
  101. package/src/realtime/registry.ts +0 -84
@@ -3,14 +3,9 @@ import mongoose from "mongoose";
3
3
 
4
4
  import type {User} from "../auth";
5
5
  import {Permissions} from "../permissions";
6
- import type {RealtimeRegistryEntry} from "../realtime/registry";
7
6
  import {setupDb} from "../tests";
8
7
  import {createAccess} from "./access";
9
- import {
10
- canReadDocumentRealtime,
11
- canSubscribeRealtime,
12
- maskRealtimeDocument,
13
- } from "./realtimeAccess";
8
+ import {canReadDocumentRealtime} from "./realtimeAccess";
14
9
  import {OwnerScope} from "./scopes";
15
10
  import {terrenoStatements} from "./statements";
16
11
  import type {
@@ -39,14 +34,9 @@ const createTestUser = (
39
34
  };
40
35
  };
41
36
 
42
- // Realtime access reads only access/permissions; tests omit the rest of ModelRouterOptions.
43
- const makeEntry = (options: Partial<RealtimeRegistryEntry["options"]>): RealtimeRegistryEntry => ({
44
- collectionName: "todos",
45
- config: {methods: ["create", "update", "delete"], roomStrategy: "owner"},
46
- modelName: "Todo",
47
- options: options as RealtimeRegistryEntry["options"],
48
- routePath: "/todos",
49
- });
37
+ type RealtimeAccessEntry = Parameters<typeof canReadDocumentRealtime>[0];
38
+
39
+ const makeEntry = (options: RealtimeAccessEntry["options"]): RealtimeAccessEntry => ({options});
50
40
 
51
41
  const makeStubAccess = ({
52
42
  allowed,
@@ -62,86 +52,29 @@ const makeStubAccess = ({
62
52
  }) as unknown as AnyTerrenoAccess;
63
53
 
64
54
  describe("realtimeAccess", () => {
65
- it("uses accessControl permissions for subscriptions", async () => {
66
- await setupDb();
67
- const access = createAccess({
68
- connection: mongoose.connection,
69
- defaultRoles: [
70
- {
71
- displayName: "Reader",
72
- name: "reader",
73
- permissions: {todo: ["read", "list"]},
74
- },
75
- ],
76
- statements: appStatements,
77
- });
78
- await access.roles.seedDefaults();
79
-
80
- const user = createTestUser({roles: ["reader"]});
81
- const entry = makeEntry({
82
- access: {resource: "todo"},
83
- accessControl: access as AnyTerrenoAccess,
84
- });
55
+ it("falls back to router read permissions when access config is absent", async () => {
56
+ const user = createTestUser({admin: true});
57
+ const entry = makeEntry({permissions: {read: [Permissions.IsAdmin]}});
85
58
 
86
- expect(await canSubscribeRealtime(entry, "list", user)).toBe(true);
87
- expect(await canSubscribeRealtime(entry, "read", user)).toBe(true);
59
+ expect(await canReadDocumentRealtime(entry, user, {title: "Any"})).toBe(true);
60
+ expect(await canReadDocumentRealtime(entry, createTestUser(), {title: "Any"})).toBe(false);
88
61
  });
89
62
 
90
- it("returns false when the realtime action override is null", async () => {
91
- await setupDb();
92
- const access = createAccess({
93
- connection: mongoose.connection,
94
- statements: appStatements,
95
- });
96
- await access.roles.seedDefaults();
97
-
98
- const user = createTestUser({roles: ["superadmin"]});
63
+ it("uses a custom read action override for document reads", async () => {
64
+ const permissionRequests: PermissionRequest<Statements>[] = [];
99
65
  const entry = makeEntry({
100
- access: {actions: {list: null}, resource: "todo"},
101
- accessControl: access as AnyTerrenoAccess,
102
- });
103
-
104
- expect(await canSubscribeRealtime(entry, "list", user)).toBe(false);
105
- });
106
-
107
- it("honors custom action overrides for realtime subscriptions", async () => {
108
- await setupDb();
109
- const access = createAccess({
110
- connection: mongoose.connection,
111
- defaultRoles: [
112
- {
113
- displayName: "Updater",
114
- name: "updater",
115
- permissions: {todo: ["update"]},
66
+ access: {actions: {read: "list"}, resource: "todo"},
67
+ accessControl: makeStubAccess({
68
+ allowed: true,
69
+ onCheck: (args) => {
70
+ permissionRequests.push(args.permissions);
71
+ return undefined;
116
72
  },
117
- ],
118
- statements: appStatements,
119
- });
120
- await access.roles.seedDefaults();
121
-
122
- const user = createTestUser({roles: ["updater"]});
123
- const entry = makeEntry({
124
- access: {actions: {list: "update"}, resource: "todo"},
125
- accessControl: access as AnyTerrenoAccess,
126
- });
127
-
128
- expect(await canSubscribeRealtime(entry, "list", user)).toBe(true);
129
- });
130
-
131
- it("falls back to legacy permissions when access config is absent", async () => {
132
- const user = createTestUser({admin: true});
133
- const entry = makeEntry({
134
- permissions: {
135
- create: [Permissions.IsAdmin],
136
- delete: [Permissions.IsAdmin],
137
- list: [Permissions.IsAdmin],
138
- read: [Permissions.IsAdmin],
139
- update: [Permissions.IsAdmin],
140
- },
73
+ }),
141
74
  });
142
75
 
143
- expect(await canSubscribeRealtime(entry, "list", user)).toBe(true);
144
- expect(await canSubscribeRealtime(entry, "list", createTestUser())).toBe(false);
76
+ expect(await canReadDocumentRealtime(entry, createTestUser(), {title: "Any"})).toBe(true);
77
+ expect(permissionRequests).toEqual([{todo: ["list"]}]);
145
78
  });
146
79
 
147
80
  it("checks document-level access with scopes", async () => {
@@ -216,78 +149,6 @@ describe("realtimeAccess", () => {
216
149
  ).toBe(false);
217
150
  });
218
151
 
219
- it("masks realtime documents using field views", async () => {
220
- await setupDb();
221
- const access = createAccess({
222
- connection: mongoose.connection,
223
- defaultRoles: [
224
- {
225
- displayName: "Reader",
226
- name: "reader",
227
- permissions: {todo: ["read"]},
228
- },
229
- ],
230
- fieldViews: {
231
- todo: {
232
- select: () => "public",
233
- views: {
234
- public: {omit: [], read: ["title"], write: ["title"]},
235
- },
236
- },
237
- },
238
- statements: appStatements,
239
- });
240
- await access.roles.seedDefaults();
241
-
242
- const user = createTestUser({roles: ["reader"]});
243
- const entry = makeEntry({
244
- access: {resource: "todo"},
245
- accessControl: access as AnyTerrenoAccess,
246
- });
247
-
248
- const masked = await maskRealtimeDocument(
249
- entry,
250
- user,
251
- {secret: "hidden", title: "Visible"},
252
- "read"
253
- );
254
- expect(masked).toEqual({title: "Visible"});
255
- });
256
-
257
- it("returns documents unchanged when access config is missing", async () => {
258
- const entry = makeEntry({});
259
- const doc = {title: "Plain"};
260
- expect(await maskRealtimeDocument(entry, undefined, doc, "read")).toBe(doc);
261
- });
262
-
263
- it("falls back to the read action when the resource has no list statement", async () => {
264
- await setupDb();
265
- const readOnlyStatements = {
266
- ...terrenoStatements,
267
- note: ["create", "read", "update", "delete"],
268
- } as const;
269
- const access = createAccess({
270
- connection: mongoose.connection,
271
- defaultRoles: [
272
- {
273
- displayName: "Note Reader",
274
- name: "note-reader",
275
- permissions: {note: ["read"]},
276
- },
277
- ],
278
- statements: readOnlyStatements,
279
- });
280
- await access.roles.seedDefaults();
281
-
282
- const user = createTestUser({roles: ["note-reader"]});
283
- const entry = makeEntry({
284
- access: {resource: "note"},
285
- accessControl: access as AnyTerrenoAccess,
286
- });
287
-
288
- expect(await canSubscribeRealtime(entry, "list", user)).toBe(true);
289
- });
290
-
291
152
  it("returns false for document reads when the read action override is null", async () => {
292
153
  const user = createTestUser();
293
154
  const entry = makeEntry({
@@ -378,17 +239,4 @@ describe("realtimeAccess", () => {
378
239
  expect(await canReadDocumentRealtime(entry, owner, doc)).toBe(true);
379
240
  expect(await canReadDocumentRealtime(entry, other, doc)).toBe(false);
380
241
  });
381
-
382
- it("applies access.also to realtime subscriptions", async () => {
383
- const admin = createTestUser({admin: true});
384
- const member = createTestUser();
385
- const entry = makeEntry({
386
- access: {also: {list: [Permissions.IsAdmin]}, resource: "todo"},
387
- accessControl: makeStubAccess({allowed: true}),
388
- });
389
-
390
- expect(await canSubscribeRealtime(entry, "list", admin)).toBe(true);
391
- expect(await canSubscribeRealtime(entry, "list", member)).toBe(false);
392
- expect(await canSubscribeRealtime(entry, "read", member)).toBe(true);
393
- });
394
242
  });
@@ -1,47 +1,19 @@
1
- import type {RESTMethod} from "../api";
2
1
  import type {User} from "../auth";
3
2
  import {checkPermissions, type PermissionMethod} from "../permissions";
4
- import {applyReadMask} from "./fieldViews";
5
3
  import type {AnyTerrenoAccess, ModelRouterAccessOptions} from "./types";
6
4
 
7
5
  interface RealtimeAccessEntry {
8
6
  options: {
9
7
  access?: ModelRouterAccessOptions;
10
8
  accessControl?: AnyTerrenoAccess;
11
- permissions?: {read?: PermissionMethod<unknown>[]; list?: PermissionMethod<unknown>[]};
9
+ permissions?: {read?: PermissionMethod<unknown>[]};
12
10
  };
13
11
  }
14
12
 
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
- // REST and snapshot permissions append access.also[method] to the RBAC role and scope checks
44
- // (buildAccessPermissions), so realtime decisions must apply them too.
13
+ /**
14
+ * REST `access.also[method]` still applies to socket document reads. An empty list allows
15
+ * the read; any listed permission must pass.
16
+ */
45
17
  const checkAlsoPermissions = async (
46
18
  access: ModelRouterAccessOptions,
47
19
  method: "list" | "read",
@@ -55,34 +27,20 @@ const checkAlsoPermissions = async (
55
27
  return checkPermissions(method, also, user, doc);
56
28
  };
57
29
 
58
- export const canSubscribeRealtime = async (
59
- entry: RealtimeAccessEntry,
60
- method: "list" | "read",
61
- user?: User
62
- ): Promise<boolean> => {
63
- const access = entry.options.access;
64
- const accessControl = entry.options.accessControl;
65
- if (access && accessControl) {
66
- const statements = accessControl.statements as Record<string, readonly string[]>;
67
- const action = resolveActionForMethod(method, access, statements);
68
- if (!action) {
69
- return false;
70
- }
71
- const result = await accessControl.can({
72
- context: {transport: "socket"},
73
- permissions: {[access.resource]: [action]},
74
- user,
75
- });
76
- if (!result.allowed) {
77
- return false;
78
- }
79
- return checkAlsoPermissions(access, method, user);
30
+ /** The RBAC action for socket document reads: the router's `read` override, else `read`. */
31
+ const resolveReadAction = (access: ModelRouterAccessOptions): string | null => {
32
+ const override = access.actions?.read;
33
+ if (override === null) {
34
+ return null;
80
35
  }
81
-
82
- const permissions = entry.options.permissions?.[method] ?? [];
83
- return checkPermissions(method, permissions, user);
36
+ return override ?? "read";
84
37
  };
85
38
 
39
+ /**
40
+ * Socket-side read check for one document, used before emitting `sync:delta` to each
41
+ * socket in a sync stream room. Uses RBAC (`access` + `accessControl`, including
42
+ * `access.scope.check`) when configured, else the router's `permissions.read`.
43
+ */
86
44
  export const canReadDocumentRealtime = async (
87
45
  entry: RealtimeAccessEntry,
88
46
  user?: User,
@@ -91,8 +49,7 @@ export const canReadDocumentRealtime = async (
91
49
  const access = entry.options.access;
92
50
  const accessControl = entry.options.accessControl;
93
51
  if (access && accessControl) {
94
- const statements = accessControl.statements as Record<string, readonly string[]>;
95
- const action = resolveActionForMethod("read", access, statements);
52
+ const action = resolveReadAction(access);
96
53
  if (!action) {
97
54
  return false;
98
55
  }
@@ -134,25 +91,3 @@ export const canReadDocumentRealtime = async (
134
91
 
135
92
  return checkPermissions("read", entry.options.permissions?.read ?? [], user, doc);
136
93
  };
137
-
138
- export const maskRealtimeDocument = async (
139
- entry: RealtimeAccessEntry,
140
- user: User | undefined,
141
- doc: unknown,
142
- _method: RESTMethod
143
- ): Promise<unknown> => {
144
- const access = entry.options.access;
145
- const accessControl = entry.options.accessControl;
146
- if (!access || !accessControl) {
147
- return doc;
148
- }
149
-
150
- const phase = "read";
151
- const mask = await accessControl.fieldMask({
152
- doc,
153
- phase,
154
- resource: access.resource,
155
- user,
156
- });
157
- return applyReadMask(doc, mask);
158
- };