@terreno/api 57.21.0 → 58.0.0-beta.2

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 (121) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +1 -1
  3. package/dist/api.d.ts +0 -13
  4. package/dist/api.js +0 -9
  5. package/dist/auth.d.ts +3 -2
  6. package/dist/auth.js +95 -5
  7. package/dist/authRecovery.d.ts +2 -1
  8. package/dist/authRecovery.js +35 -17
  9. package/dist/collectionRegistry.d.ts +3 -4
  10. package/dist/collectionRegistry.js +0 -1
  11. package/dist/consentApp.d.ts +1 -1
  12. package/dist/consentApp.js +58 -2
  13. package/dist/index.d.ts +4 -5
  14. package/dist/index.js +8 -20
  15. package/dist/mcp/adminTracking.js +1 -1
  16. package/dist/mcp/serviceTokens.d.ts +21 -1
  17. package/dist/mcp/serviceTokens.js +159 -183
  18. package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
  19. package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
  20. package/dist/models/mcpRequestLog.js +1 -1
  21. package/dist/models/mcpServiceToken.js +36 -4
  22. package/dist/openApiBuilder.d.ts +4 -0
  23. package/dist/openApiBuilder.js +2 -0
  24. package/dist/rbac/realtimeAccess.d.ts +5 -4
  25. package/dist/rbac/realtimeAccess.js +17 -64
  26. package/dist/realtime/changeStreamWatcher.d.ts +8 -63
  27. package/dist/realtime/changeStreamWatcher.js +32 -391
  28. package/dist/realtime/realtimeApp.d.ts +14 -27
  29. package/dist/realtime/realtimeApp.js +14 -220
  30. package/dist/realtime/types.d.ts +0 -64
  31. package/dist/sync/entityIds.d.ts +14 -0
  32. package/dist/sync/entityIds.js +17 -0
  33. package/dist/sync/executors.js +14 -2
  34. package/dist/sync/models.d.ts +1 -0
  35. package/dist/sync/models.js +4 -0
  36. package/dist/sync/mutationHandler.js +51 -2
  37. package/dist/sync/routes.js +12 -17
  38. package/dist/sync/socketHandlers.d.ts +1 -1
  39. package/dist/sync/socketHandlers.js +1 -1
  40. package/dist/sync/types.d.ts +8 -0
  41. package/dist/terrenoApp.d.ts +7 -5
  42. package/dist/terrenoApp.js +18 -14
  43. package/dist/tests/openApiResponseSchema.d.ts +39 -0
  44. package/dist/tests/openApiResponseSchema.js +56 -0
  45. package/dist/tests.d.ts +1 -0
  46. package/dist/tests.js +4 -1
  47. package/dist/types/mcpAdmin.d.ts +1 -1
  48. package/dist/types/mcpServiceToken.d.ts +7 -4
  49. package/dist/versionCheckPlugin.d.ts +1 -1
  50. package/dist/versionCheckPlugin.js +25 -2
  51. package/package.json +17 -6
  52. package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
  53. package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
  54. package/src/__tests__/openApiResponseSchema.test.ts +148 -0
  55. package/src/__tests__/versionCheckPlugin.test.ts +72 -0
  56. package/src/api.test.ts +9 -7
  57. package/src/api.ts +0 -24
  58. package/src/auth.ts +116 -5
  59. package/src/authOpenApi.test.ts +316 -0
  60. package/src/authRecovery.ts +47 -19
  61. package/src/betterAuthOAuthHandoff.test.ts +13 -5
  62. package/src/collectionRegistry.ts +3 -5
  63. package/src/consentApp.test.ts +98 -0
  64. package/src/consentApp.ts +67 -2
  65. package/src/index.ts +6 -28
  66. package/src/mcp/actionTools.test.ts +2 -2
  67. package/src/mcp/adminTracking.ts +1 -1
  68. package/src/mcp/auth.test.ts +7 -3
  69. package/src/mcp/oauth.test.ts +12 -12
  70. package/src/mcp/serviceTokens.sync.test.ts +230 -0
  71. package/src/mcp/serviceTokens.test.ts +112 -61
  72. package/src/mcp/serviceTokens.ts +193 -212
  73. package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
  74. package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
  75. package/src/models/mcpRequestLog.ts +1 -1
  76. package/src/models/mcpServiceToken.test.ts +52 -5
  77. package/src/models/mcpServiceToken.ts +51 -14
  78. package/src/openApiBuilder.test.ts +34 -1
  79. package/src/openApiBuilder.ts +5 -0
  80. package/src/rateLimit/rateLimit.test.ts +25 -10
  81. package/src/rbac/realtimeAccess.test.ts +20 -172
  82. package/src/rbac/realtimeAccess.ts +17 -82
  83. package/src/realtime/changeStreamWatcher.ts +43 -506
  84. package/src/realtime/realtime.test.ts +205 -2545
  85. package/src/realtime/realtimeApp.ts +16 -295
  86. package/src/realtime/types.ts +0 -72
  87. package/src/sync/entityIds.ts +18 -0
  88. package/src/sync/executors.test.ts +28 -0
  89. package/src/sync/executors.ts +23 -2
  90. package/src/sync/models.ts +6 -0
  91. package/src/sync/mutationHandler.test.ts +84 -0
  92. package/src/sync/mutationHandler.ts +57 -2
  93. package/src/sync/routes.ts +12 -17
  94. package/src/sync/socketHandlers.ts +1 -1
  95. package/src/sync/syncRoutes.test.ts +8 -4
  96. package/src/sync/syncSocket.test.ts +77 -113
  97. package/src/sync/types.ts +9 -0
  98. package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
  99. package/src/terrenoApp.ts +24 -18
  100. package/src/tests/openApiResponseSchema.ts +104 -0
  101. package/src/tests.ts +7 -0
  102. package/src/types/mcpAdmin.ts +1 -1
  103. package/src/types/mcpServiceToken.ts +7 -4
  104. package/src/versionCheckPlugin.ts +41 -2
  105. package/biome.jsonc +0 -22
  106. package/bunfig.toml +0 -10
  107. package/bunfig.unit.toml +0 -3
  108. package/dist/realtime/deprecation.d.ts +0 -13
  109. package/dist/realtime/deprecation.js +0 -31
  110. package/dist/realtime/queryStore.d.ts +0 -37
  111. package/dist/realtime/queryStore.js +0 -103
  112. package/dist/realtime/registry.d.ts +0 -15
  113. package/dist/realtime/registry.js +0 -52
  114. package/e2e/smoke.ts +0 -193
  115. package/src/realtime/deprecation.test.ts +0 -60
  116. package/src/realtime/deprecation.ts +0 -33
  117. package/src/realtime/queryStore.ts +0 -122
  118. package/src/realtime/registry.ts +0 -84
  119. package/tsconfig.json +0 -19
  120. package/tsconfig.typecheck.json +0 -14
  121. package/tsconfig.typedoc.json +0 -13
@@ -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
- };