@terreno/api 57.16.2 → 57.18.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 (184) hide show
  1. package/dist/actions.d.ts +26 -3
  2. package/dist/actions.js +102 -16
  3. package/dist/api.d.ts +7 -0
  4. package/dist/api.js +59 -3
  5. package/dist/auth.d.ts +28 -4
  6. package/dist/auth.js +140 -15
  7. package/dist/authRecovery.d.ts +31 -0
  8. package/dist/authRecovery.js +86 -6
  9. package/dist/betterAuth.d.ts +86 -0
  10. package/dist/betterAuthApp.d.ts +17 -0
  11. package/dist/betterAuthApp.js +12 -1
  12. package/dist/betterAuthOAuthHandoff.d.ts +24 -0
  13. package/dist/betterAuthOAuthHandoff.js +305 -0
  14. package/dist/betterAuthSetup.d.ts +37 -2
  15. package/dist/betterAuthSetup.js +304 -24
  16. package/dist/expressServer.d.ts +16 -0
  17. package/dist/expressServer.js +61 -14
  18. package/dist/githubAuth.d.ts +9 -0
  19. package/dist/githubAuth.js +230 -31
  20. package/dist/index.d.ts +9 -1
  21. package/dist/index.js +27 -3
  22. package/dist/mcp/actionTools.d.ts +4 -0
  23. package/dist/mcp/actionTools.js +158 -0
  24. package/dist/mcp/auth.d.ts +30 -0
  25. package/dist/mcp/auth.js +83 -28
  26. package/dist/mcp/createMCPRequest.d.ts +5 -1
  27. package/dist/mcp/createMCPRequest.js +3 -3
  28. package/dist/mcp/handlers.d.ts +3 -0
  29. package/dist/mcp/handlers.js +43 -27
  30. package/dist/mcp/oauth.d.ts +14 -0
  31. package/dist/mcp/oauth.js +618 -0
  32. package/dist/mcp/oauthMetadata.d.ts +89 -0
  33. package/dist/mcp/oauthMetadata.js +137 -0
  34. package/dist/mcp/registry.d.ts +5 -0
  35. package/dist/mcp/registry.js +9 -1
  36. package/dist/mcp/server.d.ts +6 -0
  37. package/dist/mcp/server.js +44 -7
  38. package/dist/mcp/serviceTokens.js +12 -2
  39. package/dist/mcp/toolExecution.d.ts +12 -0
  40. package/dist/mcp/toolExecution.js +60 -0
  41. package/dist/mcp/toolGenerator.d.ts +4 -1
  42. package/dist/mcp/toolGenerator.js +26 -60
  43. package/dist/mcp/types.d.ts +4 -4
  44. package/dist/models/mcpOAuthAuthorization.d.ts +2 -0
  45. package/dist/models/mcpOAuthAuthorization.js +86 -0
  46. package/dist/models/mcpOAuthClient.d.ts +2 -0
  47. package/dist/models/mcpOAuthClient.js +42 -0
  48. package/dist/models/mcpOAuthRevokedFamily.d.ts +2 -0
  49. package/dist/models/mcpOAuthRevokedFamily.js +36 -0
  50. package/dist/models/mcpOAuthToken.d.ts +12 -0
  51. package/dist/models/mcpOAuthToken.js +159 -0
  52. package/dist/models/mcpServiceToken.d.ts +1 -0
  53. package/dist/models/mcpServiceToken.js +21 -4
  54. package/dist/permissions.d.ts +7 -0
  55. package/dist/permissions.js +18 -1
  56. package/dist/rateLimit/policies.d.ts +4 -0
  57. package/dist/rateLimit/policies.js +46 -7
  58. package/dist/rbac/access.js +1 -0
  59. package/dist/rbac/membershipOrgAdminSource.d.ts +4 -0
  60. package/dist/rbac/membershipOrgAdminSource.js +5 -0
  61. package/dist/rbac/modelRouterAccess.d.ts +7 -1
  62. package/dist/rbac/modelRouterAccess.js +37 -24
  63. package/dist/rbac/realtimeAccess.js +17 -3
  64. package/dist/rbac/resolve.js +66 -9
  65. package/dist/rbac/roleManager.js +60 -5
  66. package/dist/rbac/roleModel.js +1 -1
  67. package/dist/rbac/statements.d.ts +1 -1
  68. package/dist/rbac/statements.js +13 -1
  69. package/dist/rbac/types.d.ts +12 -0
  70. package/dist/rbac/userWriteGuards.d.ts +50 -0
  71. package/dist/rbac/userWriteGuards.js +156 -0
  72. package/dist/realtime/changeStreamWatcher.d.ts +4 -1
  73. package/dist/realtime/changeStreamWatcher.js +157 -73
  74. package/dist/realtime/queryMatcher.d.ts +3 -0
  75. package/dist/realtime/queryMatcher.js +25 -10
  76. package/dist/realtime/realtimeApp.d.ts +16 -1
  77. package/dist/realtime/realtimeApp.js +76 -8
  78. package/dist/realtime/socketAuth.d.ts +17 -6
  79. package/dist/realtime/socketAuth.js +77 -16
  80. package/dist/realtime/types.d.ts +8 -5
  81. package/dist/requestContext.d.ts +22 -0
  82. package/dist/requestContext.js +22 -1
  83. package/dist/seedRunner.js +3 -1
  84. package/dist/sortFields.d.ts +33 -0
  85. package/dist/sortFields.js +55 -0
  86. package/dist/sync/executors.js +140 -2
  87. package/dist/sync/models.d.ts +2 -0
  88. package/dist/sync/models.js +5 -0
  89. package/dist/sync/mutationHandler.js +70 -7
  90. package/dist/sync/routes.js +4 -2
  91. package/dist/sync/syncSeqPlugin.js +6 -5
  92. package/dist/terrenoApp.d.ts +14 -0
  93. package/dist/terrenoApp.js +21 -6
  94. package/dist/types/mcpOAuth.d.ts +101 -0
  95. package/dist/types/mcpOAuth.js +2 -0
  96. package/dist/types/mcpServiceToken.d.ts +8 -0
  97. package/package.json +3 -3
  98. package/src/actions.test.ts +118 -0
  99. package/src/actions.ts +139 -17
  100. package/src/api.arrayOperations.test.ts +78 -0
  101. package/src/api.test.ts +36 -0
  102. package/src/api.ts +76 -4
  103. package/src/auth.test.ts +521 -3
  104. package/src/auth.ts +171 -17
  105. package/src/authRecovery.test.ts +99 -0
  106. package/src/authRecovery.ts +117 -5
  107. package/src/authVerification.test.ts +3 -3
  108. package/src/betterAuth.ts +104 -1
  109. package/src/betterAuthApp.test.ts +634 -1
  110. package/src/betterAuthApp.ts +28 -0
  111. package/src/betterAuthOAuthHandoff.test.ts +946 -0
  112. package/src/betterAuthOAuthHandoff.ts +375 -0
  113. package/src/betterAuthSetup.test.ts +393 -4
  114. package/src/betterAuthSetup.ts +402 -29
  115. package/src/expressServer.test.ts +93 -0
  116. package/src/expressServer.ts +81 -14
  117. package/src/githubAuth.test.ts +448 -6
  118. package/src/githubAuth.ts +276 -34
  119. package/src/index.ts +35 -1
  120. package/src/mcp/actionTools.test.ts +498 -0
  121. package/src/mcp/actionTools.ts +220 -0
  122. package/src/mcp/auth.test.ts +114 -1
  123. package/src/mcp/auth.ts +122 -35
  124. package/src/mcp/createMCPRequest.ts +8 -2
  125. package/src/mcp/handlers.test.ts +27 -0
  126. package/src/mcp/handlers.ts +21 -6
  127. package/src/mcp/oauth.test.ts +1026 -0
  128. package/src/mcp/oauth.ts +798 -0
  129. package/src/mcp/oauthMetadata.ts +234 -0
  130. package/src/mcp/registry.ts +11 -0
  131. package/src/mcp/server.ts +54 -14
  132. package/src/mcp/serviceTokens.ts +16 -3
  133. package/src/mcp/toolExecution.ts +67 -0
  134. package/src/mcp/toolGenerator.ts +27 -83
  135. package/src/mcp/types.ts +4 -4
  136. package/src/models/mcpOAuthAuthorization.ts +97 -0
  137. package/src/models/mcpOAuthClient.ts +49 -0
  138. package/src/models/mcpOAuthRevokedFamily.ts +47 -0
  139. package/src/models/mcpOAuthToken.test.ts +82 -0
  140. package/src/models/mcpOAuthToken.ts +195 -0
  141. package/src/models/mcpServiceToken.ts +26 -2
  142. package/src/permissions.ts +17 -0
  143. package/src/rateLimit/policies.ts +54 -10
  144. package/src/rateLimit/rateLimit.test.ts +41 -0
  145. package/src/rbac/access.ts +1 -0
  146. package/src/rbac/membershipOrgAdminSource.ts +5 -0
  147. package/src/rbac/modelRouterAccess.ts +40 -23
  148. package/src/rbac/realtimeAccess.test.ts +43 -0
  149. package/src/rbac/realtimeAccess.ts +23 -3
  150. package/src/rbac/resolve.test.ts +179 -1
  151. package/src/rbac/resolve.ts +78 -9
  152. package/src/rbac/roleManager.test.ts +132 -0
  153. package/src/rbac/roleManager.ts +69 -5
  154. package/src/rbac/roleModel.ts +1 -1
  155. package/src/rbac/statements.ts +14 -1
  156. package/src/rbac/types.ts +12 -0
  157. package/src/rbac/userWriteGuards.test.ts +407 -0
  158. package/src/rbac/userWriteGuards.ts +185 -0
  159. package/src/realtime/changeStreamWatcher.ts +203 -75
  160. package/src/realtime/queryMatcher.ts +30 -13
  161. package/src/realtime/realtime.test.ts +132 -0
  162. package/src/realtime/realtimeApp.ts +94 -10
  163. package/src/realtime/realtimeAppSetup.test.ts +282 -1
  164. package/src/realtime/socketAuth.test.ts +140 -8
  165. package/src/realtime/socketAuth.ts +90 -19
  166. package/src/realtime/types.ts +8 -5
  167. package/src/requestContext.ts +52 -1
  168. package/src/requestCredential.test.ts +89 -0
  169. package/src/seedRunner.test.ts +21 -0
  170. package/src/seedRunner.ts +3 -1
  171. package/src/sortFields.ts +69 -0
  172. package/src/sync/executors.test.ts +382 -3
  173. package/src/sync/executors.ts +179 -4
  174. package/src/sync/models.ts +8 -0
  175. package/src/sync/mutationHandler.test.ts +166 -2
  176. package/src/sync/mutationHandler.ts +97 -5
  177. package/src/sync/routes.ts +4 -2
  178. package/src/sync/syncFrontier.test.ts +11 -0
  179. package/src/sync/syncPhaseC.test.ts +18 -0
  180. package/src/sync/syncSeqPlugin.ts +6 -5
  181. package/src/sync/syncSocket.test.ts +92 -0
  182. package/src/terrenoApp.ts +36 -21
  183. package/src/types/mcpOAuth.ts +129 -0
  184. package/src/types/mcpServiceToken.ts +6 -1
@@ -145,6 +145,12 @@ describe("HTTP rate limiting", () => {
145
145
  "/api/auth/send-verification-email",
146
146
  "/api/auth/verify-email?token=secret",
147
147
  "/api/auth/callback/github",
148
+ "/api/auth/oauth-handoff/start?provider=google",
149
+ "/api/auth/one-time-token/verify",
150
+ "/oauth/register",
151
+ "/oauth/authorize?client_id=abc",
152
+ "/oauth/token",
153
+ "/oauth/revoke",
148
154
  ];
149
155
  for (const originalUrl of authPaths) {
150
156
  assert.equal(
@@ -154,6 +160,13 @@ describe("HTTP rate limiting", () => {
154
160
  );
155
161
  }
156
162
  assert.equal(classifyRateLimitPolicy({method: "GET", originalUrl: "/auth/me"} as never), "api");
163
+ assert.equal(
164
+ classifyRateLimitPolicy({
165
+ method: "POST",
166
+ originalUrl: "/oauth/authorize/req/approve",
167
+ } as never),
168
+ "api"
169
+ );
157
170
  assert.equal(
158
171
  classifyRateLimitPolicy({method: "PATCH", originalUrl: "/auth/me"} as never),
159
172
  "api"
@@ -202,6 +215,34 @@ describe("HTTP rate limiting", () => {
202
215
  );
203
216
  });
204
217
 
218
+ it("classifies dot-segment variants of credential paths as auth", () => {
219
+ const variants = [
220
+ "/api/auth/%2e/sign-in/email",
221
+ "/api/auth/%2E/sign-in/email",
222
+ "/api/auth/./sign-in/email",
223
+ "/api/auth/x/../sign-in/email",
224
+ "/api/auth/x/%2e%2e/reset-password",
225
+ "/auth/./login",
226
+ "/x/../oauth/token",
227
+ ];
228
+ for (const path of variants) {
229
+ assert.equal(classifyRateLimitPolicy({method: "POST", path} as never), "auth", path);
230
+ }
231
+ });
232
+
233
+ it("does not skip rate limiting for non-canonical paths that resolve elsewhere", () => {
234
+ assert.isFalse(
235
+ shouldSkipRateLimit({
236
+ method: "POST",
237
+ path: "/openapi.json/../api/auth/sign-in/email",
238
+ } as never)
239
+ );
240
+ assert.isFalse(
241
+ shouldSkipRateLimit({method: "POST", path: "/swagger/%2e%2e/api/auth/sign-in/email"} as never)
242
+ );
243
+ assert.isTrue(shouldSkipRateLimit({method: "GET", path: "/openapi.json"} as never));
244
+ });
245
+
205
246
  it("honors rateLimit.skip for extra paths", async () => {
206
247
  const app = buildApp({
207
248
  limits: {apiMax: 1, authMax: 1},
@@ -209,5 +209,6 @@ export const createAccess = <S extends Statements>(options: AccessOptions<S>): T
209
209
  queryFilter,
210
210
  roles: roleManager,
211
211
  statements: mergedStatements,
212
+ userModel: options.userModel,
212
213
  };
213
214
  };
@@ -36,7 +36,12 @@ const shellOnlyOrgAdminGrants = (): PermissionSourceGrants => ({
36
36
  },
37
37
  });
38
38
 
39
+ /**
40
+ * Additive-only: it never returns `deny`, so an outage drops only its org-admin grants and does
41
+ * not fail resolution closed.
42
+ */
39
43
  export const membershipOrgAdminPermissionSource = (): PermissionSource => ({
44
+ failClosedWhenDenyUnknown: false,
40
45
  getGrants: async ({user}): Promise<PermissionSourceGrants | null> => {
41
46
  const contextMembership = getOrgContext()?.membership;
42
47
  if (contextMembership) {
@@ -62,6 +62,43 @@ const buildPermissionRequest = (resource: string, action: string): Record<string
62
62
  [resource]: [action],
63
63
  });
64
64
 
65
+ /**
66
+ * Per-document check for a router-level `access.scope`, shared by CRUD permissions and modelRouter
67
+ * actions. Returns undefined when the router has no scope check.
68
+ * @internal
69
+ */
70
+ export const buildAccessScopeCheck = <T>(
71
+ accessControl: AnyTerrenoAccess,
72
+ access: ModelRouterAccessOptions,
73
+ action: string
74
+ ): PermissionMethod<T> | undefined => {
75
+ if (!access.scope?.check) {
76
+ return undefined;
77
+ }
78
+ return async (_method, user, obj) => {
79
+ if (!user) {
80
+ return false;
81
+ }
82
+ const result = await access.scope?.check?.({
83
+ action,
84
+ doc: obj,
85
+ user,
86
+ });
87
+ if (result === false) {
88
+ return false;
89
+ }
90
+ if (result && typeof result === "object") {
91
+ const extra = await accessControl.can({
92
+ doc: obj,
93
+ permissions: result as never,
94
+ user,
95
+ });
96
+ return extra.allowed;
97
+ }
98
+ return true;
99
+ };
100
+ };
101
+
65
102
  /** @internal */
66
103
  export const buildAccessPermissions = <T>(
67
104
  accessControl: AnyTerrenoAccess,
@@ -79,29 +116,9 @@ export const buildAccessPermissions = <T>(
79
116
  const checks: PermissionMethod<T>[] = [
80
117
  isPermitted(buildPermissionRequest(access.resource, action)) as PermissionMethod<T>,
81
118
  ];
82
- if (access.scope?.check) {
83
- checks.push(async (_method, user, obj) => {
84
- if (!user) {
85
- return false;
86
- }
87
- const result = await access.scope?.check?.({
88
- action,
89
- doc: obj,
90
- user,
91
- });
92
- if (result === false) {
93
- return false;
94
- }
95
- if (result && typeof result === "object") {
96
- const extra = await accessControl.can({
97
- doc: obj,
98
- permissions: result as never,
99
- user,
100
- });
101
- return extra.allowed;
102
- }
103
- return true;
104
- });
119
+ const scopeCheck = buildAccessScopeCheck<T>(accessControl, access, action);
120
+ if (scopeCheck) {
121
+ checks.push(scopeCheck);
105
122
  }
106
123
  const also = access.also?.[method] ?? [];
107
124
  return [...checks, ...(also as PermissionMethod<T>[])];
@@ -347,4 +347,47 @@ describe("realtimeAccess", () => {
347
347
 
348
348
  expect(await canReadDocumentRealtime(entry, user, {title: "Any"})).toBe(false);
349
349
  });
350
+
351
+ it("applies access.also.read to realtime document reads", async () => {
352
+ const owner = createTestUser();
353
+ const other = createTestUser();
354
+ const doc = {ownerId: owner.id, text: "dummy-owner-only"};
355
+ const entry = makeEntry({
356
+ access: {also: {read: [Permissions.IsOwner]}, resource: "todo"},
357
+ accessControl: makeStubAccess({allowed: true}),
358
+ });
359
+
360
+ expect(await canReadDocumentRealtime(entry, owner, doc)).toBe(true);
361
+ expect(await canReadDocumentRealtime(entry, other, doc)).toBe(false);
362
+ });
363
+
364
+ it("applies access.also.read after a scope check returns extra permissions", async () => {
365
+ const owner = createTestUser();
366
+ const other = createTestUser();
367
+ const doc = {ownerId: owner.id, text: "dummy-owner-only"};
368
+ const entry = makeEntry({
369
+ access: {
370
+ also: {read: [Permissions.IsOwner]},
371
+ resource: "todo",
372
+ scope: {check: () => ({todo: ["read"]})},
373
+ },
374
+ accessControl: makeStubAccess({allowed: true}),
375
+ });
376
+
377
+ expect(await canReadDocumentRealtime(entry, owner, doc)).toBe(true);
378
+ expect(await canReadDocumentRealtime(entry, other, doc)).toBe(false);
379
+ });
380
+
381
+ it("applies access.also to realtime subscriptions", async () => {
382
+ const admin = createTestUser({admin: true});
383
+ const member = createTestUser();
384
+ const entry = makeEntry({
385
+ access: {also: {list: [Permissions.IsAdmin]}, resource: "todo"},
386
+ accessControl: makeStubAccess({allowed: true}),
387
+ });
388
+
389
+ expect(await canSubscribeRealtime(entry, "list", admin)).toBe(true);
390
+ expect(await canSubscribeRealtime(entry, "list", member)).toBe(false);
391
+ expect(await canSubscribeRealtime(entry, "read", member)).toBe(true);
392
+ });
350
393
  });
@@ -40,6 +40,21 @@ const resolveActionForMethod = (
40
40
  return DEFAULT_METHOD_ACTIONS[method];
41
41
  };
42
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.
45
+ const checkAlsoPermissions = async (
46
+ access: ModelRouterAccessOptions,
47
+ method: "list" | "read",
48
+ user?: User,
49
+ doc?: Record<string, unknown>
50
+ ): Promise<boolean> => {
51
+ const also = access.also?.[method] ?? [];
52
+ if (also.length === 0) {
53
+ return true;
54
+ }
55
+ return checkPermissions(method, also, user, doc);
56
+ };
57
+
43
58
  export const canSubscribeRealtime = async (
44
59
  entry: RealtimeAccessEntry,
45
60
  method: "list" | "read",
@@ -58,7 +73,10 @@ export const canSubscribeRealtime = async (
58
73
  permissions: {[access.resource]: [action]},
59
74
  user,
60
75
  });
61
- return result.allowed;
76
+ if (!result.allowed) {
77
+ return false;
78
+ }
79
+ return checkAlsoPermissions(access, method, user);
62
80
  }
63
81
 
64
82
  const permissions = entry.options.permissions?.[method] ?? [];
@@ -106,10 +124,12 @@ export const canReadDocumentRealtime = async (
106
124
  permissions: scopeResult as never,
107
125
  user,
108
126
  });
109
- return extra.allowed;
127
+ if (!extra.allowed) {
128
+ return false;
129
+ }
110
130
  }
111
131
  }
112
- return true;
132
+ return checkAlsoPermissions(access, "read", user, doc);
113
133
  }
114
134
 
115
135
  return checkPermissions("read", entry.options.permissions?.read ?? [], user, doc);
@@ -3,6 +3,7 @@ import mongoose from "mongoose";
3
3
 
4
4
  import type {User} from "../auth";
5
5
  import {setupDb} from "../tests";
6
+ import {membershipOrgAdminPermissionSource} from "./membershipOrgAdminSource";
6
7
  import {createPermissionResolver} from "./resolve";
7
8
  import {createRbacRoleModel} from "./roleModel";
8
9
  import {terrenoStatements} from "./statements";
@@ -329,12 +330,13 @@ describe("createPermissionResolver", () => {
329
330
  expect(afterFailure.todo ?? []).not.toContain("list");
330
331
  });
331
332
 
332
- it("skips failed sources when stale policy is deny", async () => {
333
+ it("skips failed additive-only sources when stale policy is deny", async () => {
333
334
  await setupDb();
334
335
  const RbacRole = createRbacRoleModel(mongoose.connection);
335
336
  await RbacRole.seedDefaults({statements: appStatements});
336
337
 
337
338
  const source: PermissionSource = {
339
+ failClosedWhenDenyUnknown: false,
338
340
  getGrants: mock(async () => {
339
341
  throw new Error("source unavailable");
340
342
  }),
@@ -387,4 +389,180 @@ describe("createPermissionResolver", () => {
387
389
  const refreshed = await resolver.resolvePermissionsForUser(userA);
388
390
  expect(refreshed.todo).toEqual(["read"]);
389
391
  });
392
+
393
+ describe("deny-capable sources during an outage", () => {
394
+ const seedWriter = async () => {
395
+ await setupDb();
396
+ const RbacRole = createRbacRoleModel(mongoose.connection);
397
+ await RbacRole.seedDefaults({statements: appStatements});
398
+ await RbacRole.findOneAndUpdate(
399
+ {name: "writer"},
400
+ {$set: {displayName: "Writer", name: "writer", permissions: {todo: ["read", "update"]}}},
401
+ {upsert: true}
402
+ );
403
+ return RbacRole;
404
+ };
405
+
406
+ const flakyDenySource = (
407
+ overrides: Partial<PermissionSource> = {}
408
+ ): {source: PermissionSource; setDown: (down: boolean) => void} => {
409
+ let down = false;
410
+ return {
411
+ setDown: (next: boolean): void => {
412
+ down = next;
413
+ },
414
+ source: {
415
+ getGrants: async () => {
416
+ if (down) {
417
+ throw new Error("idp down");
418
+ }
419
+ return {deny: {todo: ["update"]}};
420
+ },
421
+ name: "idp-deny",
422
+ staleOnFailure: "deny",
423
+ ...overrides,
424
+ },
425
+ };
426
+ };
427
+
428
+ it("keeps the last-known deny after invalidateCache during an outage", async () => {
429
+ const RbacRole = await seedWriter();
430
+ const {source, setDown} = flakyDenySource();
431
+ const resolver = createPermissionResolver({
432
+ cacheTtlMs: 0,
433
+ rbacRoleModel: RbacRole,
434
+ sources: [source],
435
+ statements: appStatements,
436
+ });
437
+ const user = createTestUser({roles: ["writer"]});
438
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(["read"]);
439
+
440
+ setDown(true);
441
+ resolver.invalidateCache();
442
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(["read"]);
443
+ resolver.invalidateCache({userId: user.id});
444
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(["read"]);
445
+ expect((await resolver.resolvePermissionsForUserUncached(user)).todo).toEqual(["read"]);
446
+ });
447
+
448
+ it("keeps the last-known deny when other users churn the cache", async () => {
449
+ const RbacRole = await seedWriter();
450
+ const {source, setDown} = flakyDenySource();
451
+ const resolver = createPermissionResolver({
452
+ cacheTtlMs: 0,
453
+ maxCacheEntries: 1,
454
+ rbacRoleModel: RbacRole,
455
+ sources: [source],
456
+ statements: appStatements,
457
+ });
458
+ const userA = createTestUser({roles: ["writer"]});
459
+ expect((await resolver.resolvePermissionsForUser(userA)).todo).toEqual(["read"]);
460
+
461
+ setDown(true);
462
+ await expect(
463
+ resolver.resolvePermissionsForUser(createTestUser({roles: ["writer"]}))
464
+ ).rejects.toMatchObject({status: 503});
465
+ expect((await resolver.resolvePermissionsForUser(userA)).todo).toEqual(["read"]);
466
+ });
467
+
468
+ it("does not cache a set computed while a source was failing", async () => {
469
+ const RbacRole = await seedWriter();
470
+ const {source, setDown} = flakyDenySource({failClosedWhenDenyUnknown: false});
471
+ const resolver = createPermissionResolver({
472
+ cacheTtlMs: 60_000,
473
+ rbacRoleModel: RbacRole,
474
+ sources: [{...source, ttlMs: 0}],
475
+ statements: appStatements,
476
+ });
477
+ const user = createTestUser({roles: ["writer"]});
478
+
479
+ setDown(true);
480
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(["read", "update"]);
481
+ setDown(false);
482
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(["read"]);
483
+ });
484
+
485
+ it("fails closed on a cold failure by default", async () => {
486
+ const RbacRole = await seedWriter();
487
+ const {source, setDown} = flakyDenySource();
488
+ const resolver = createPermissionResolver({
489
+ cacheTtlMs: 0,
490
+ rbacRoleModel: RbacRole,
491
+ sources: [source],
492
+ statements: appStatements,
493
+ });
494
+ setDown(true);
495
+ await expect(
496
+ resolver.resolvePermissionsForUser(createTestUser({roles: ["writer"]}))
497
+ ).rejects.toMatchObject({status: 503, title: "Permission source unavailable"});
498
+ await expect(
499
+ resolver.resolvePermissionsForUserUncached(createTestUser({roles: ["writer"]}))
500
+ ).rejects.toMatchObject({status: 503, title: "Permission source unavailable"});
501
+ });
502
+
503
+ it("resolves local roles on a cold failure when the source opts out", async () => {
504
+ const RbacRole = await seedWriter();
505
+ const {source, setDown} = flakyDenySource({failClosedWhenDenyUnknown: false});
506
+ const resolver = createPermissionResolver({
507
+ cacheTtlMs: 0,
508
+ rbacRoleModel: RbacRole,
509
+ sources: [source],
510
+ statements: appStatements,
511
+ });
512
+ setDown(true);
513
+ expect(
514
+ (await resolver.resolvePermissionsForUser(createTestUser({roles: ["writer"]}))).todo
515
+ ).toEqual(["read", "update"]);
516
+ });
517
+
518
+ it("keeps the built-in membership source open on a cold failure", () => {
519
+ expect(membershipOrgAdminPermissionSource().failClosedWhenDenyUnknown).toBe(false);
520
+ });
521
+
522
+ it("fails closed on a cold failure when the source opts in", async () => {
523
+ const RbacRole = await seedWriter();
524
+ const {source, setDown} = flakyDenySource({failClosedWhenDenyUnknown: true});
525
+ const resolver = createPermissionResolver({
526
+ cacheTtlMs: 0,
527
+ rbacRoleModel: RbacRole,
528
+ sources: [source],
529
+ statements: appStatements,
530
+ });
531
+ setDown(true);
532
+ await expect(
533
+ resolver.resolvePermissionsForUser(createTestUser({roles: ["writer"]}))
534
+ ).rejects.toMatchObject({status: 503, title: "Permission source unavailable"});
535
+ });
536
+
537
+ it("lifts the deny once the source stops returning it, and keeps additive-only sources open", async () => {
538
+ const RbacRole = await seedWriter();
539
+ let deny = true;
540
+ let down = false;
541
+ const source: PermissionSource = {
542
+ getGrants: async () => {
543
+ if (down) {
544
+ throw new Error("idp down");
545
+ }
546
+ return deny ? {deny: {todo: ["update"]}} : {permissions: {todo: ["list"]}};
547
+ },
548
+ name: "idp-changing",
549
+ staleOnFailure: "deny",
550
+ };
551
+ const resolver = createPermissionResolver({
552
+ cacheTtlMs: 0,
553
+ rbacRoleModel: RbacRole,
554
+ sources: [{...source, ttlMs: 0}],
555
+ statements: appStatements,
556
+ });
557
+ const user = createTestUser({roles: ["writer"]});
558
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(["read"]);
559
+ deny = false;
560
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(
561
+ expect.arrayContaining(["read", "update", "list"])
562
+ );
563
+ down = true;
564
+ resolver.invalidateCache();
565
+ expect((await resolver.resolvePermissionsForUser(user)).todo).toEqual(["read", "update"]);
566
+ });
567
+ });
390
568
  });
@@ -2,6 +2,7 @@ import {createAccessControl} from "better-auth/plugins/access";
2
2
  import {DateTime} from "luxon";
3
3
 
4
4
  import type {User} from "../auth";
5
+ import {APIError} from "../errors";
5
6
  import {logger} from "../logger";
6
7
  import {getOrgContext} from "../orgs/orgContext";
7
8
  import {unionPermissionSets} from "./permissionUtils";
@@ -19,7 +20,17 @@ interface SourceCacheEntry {
19
20
  fetchedAt: number;
20
21
  }
21
22
 
23
+ interface SourceFetchResult {
24
+ grants: PermissionSourceGrants | null;
25
+ failed: boolean;
26
+ }
27
+
22
28
  const DEFAULT_CACHE_TTL_MS = 30_000;
29
+
30
+ /** Sources fail closed on a cold failure unless they opt out (additive-only sources). */
31
+ const failsClosedWhenDenyUnknown = (source: PermissionSource): boolean => {
32
+ return source.failClosedWhenDenyUnknown !== false;
33
+ };
23
34
  const DEFAULT_MAX_CACHE_ENTRIES = 10_000;
24
35
 
25
36
  const getUserRoles = (user: User): string[] => {
@@ -64,6 +75,12 @@ export const createPermissionResolver = <S extends Statements>(args: {
64
75
  const ac = createAccessControl(statements);
65
76
  const permissionCache = new Map<string, CacheEntry>();
66
77
  const sourceCache = new Map<string, Map<string, SourceCacheEntry>>();
78
+ // Last-known deny set per user and source from the last successful fetch. Kept apart from the
79
+ // grant caches so role edits (invalidateCache) and permission-cache eviction cannot lift an
80
+ // IdP/ABAC restriction while its source is down. Only users with a deny set (or a source that
81
+ // fails closed when the deny is unknown, the default, which needs a "no deny" marker) take an
82
+ // entry.
83
+ const denyPosture = new Map<string, Map<string, PermissionSet | null>>();
67
84
 
68
85
  const enforceCacheBound = (): void => {
69
86
  const now = DateTime.now().toMillis();
@@ -95,6 +112,33 @@ export const createPermissionResolver = <S extends Statements>(args: {
95
112
  enforceCacheBound();
96
113
  };
97
114
 
115
+ const recordDenyPosture = (
116
+ userId: string,
117
+ source: PermissionSource,
118
+ grants: PermissionSourceGrants | null
119
+ ): void => {
120
+ const deny = grants?.deny && Object.keys(grants.deny).length > 0 ? grants.deny : null;
121
+ const userPosture = denyPosture.get(userId);
122
+ if (!deny && !failsClosedWhenDenyUnknown(source)) {
123
+ userPosture?.delete(source.name);
124
+ if (userPosture?.size === 0) {
125
+ denyPosture.delete(userId);
126
+ }
127
+ return;
128
+ }
129
+ const next = userPosture ?? new Map<string, PermissionSet | null>();
130
+ next.set(source.name, deny);
131
+ denyPosture.delete(userId);
132
+ denyPosture.set(userId, next);
133
+ while (denyPosture.size > maxCacheEntries) {
134
+ const oldestUserId = denyPosture.keys().next().value;
135
+ if (oldestUserId === undefined) {
136
+ break;
137
+ }
138
+ denyPosture.delete(oldestUserId);
139
+ }
140
+ };
141
+
98
142
  const invalidateCache = (invalidateArgs?: {userId?: string}): void => {
99
143
  if (invalidateArgs?.userId) {
100
144
  deletePermissionCacheForUser(permissionCache, invalidateArgs.userId);
@@ -162,6 +206,7 @@ export const createPermissionResolver = <S extends Statements>(args: {
162
206
  };
163
207
 
164
208
  const grantsAfterSourceFailure = (
209
+ user: User,
165
210
  source: PermissionSource,
166
211
  cached: SourceCacheEntry | undefined,
167
212
  now: number
@@ -170,27 +215,44 @@ export const createPermissionResolver = <S extends Statements>(args: {
170
215
  if (stale) {
171
216
  return stale;
172
217
  }
173
- return denyOnlyFromCache(cached);
218
+ if (cached) {
219
+ return denyOnlyFromCache(cached);
220
+ }
221
+ const userPosture = denyPosture.get(user.id);
222
+ if (userPosture?.has(source.name)) {
223
+ const deny = userPosture.get(source.name);
224
+ return deny ? {deny} : null;
225
+ }
226
+ if (failsClosedWhenDenyUnknown(source)) {
227
+ throw new APIError({
228
+ detail: `Permission source ${source.name} failed before its deny set was known`,
229
+ status: 503,
230
+ title: "Permission source unavailable",
231
+ });
232
+ }
233
+ return null;
174
234
  };
175
235
 
176
236
  const fetchSourceGrants = async (
177
237
  user: User,
178
238
  source: PermissionSource,
179
239
  shouldCache = true
180
- ): Promise<PermissionSourceGrants | null> => {
240
+ ): Promise<SourceFetchResult> => {
181
241
  const now = DateTime.now().toMillis();
182
242
  const cached = sourceCache.get(user.id)?.get(source.name);
183
243
 
184
244
  if (!shouldCache) {
185
245
  try {
186
- return await source.getGrants({user});
246
+ const grants = await source.getGrants({user});
247
+ recordDenyPosture(user.id, source, grants);
248
+ return {failed: false, grants};
187
249
  } catch (error) {
188
250
  logger.warn("Permission source refresh failed during uncached resolution", {
189
251
  error: error instanceof Error ? error.message : String(error),
190
252
  policy: source.staleOnFailure ?? "deny",
191
253
  source: source.name,
192
254
  });
193
- return grantsAfterSourceFailure(source, cached, now);
255
+ return {failed: true, grants: grantsAfterSourceFailure(user, source, cached, now)};
194
256
  }
195
257
  }
196
258
 
@@ -202,20 +264,24 @@ export const createPermissionResolver = <S extends Statements>(args: {
202
264
  const cachedAfterTouch = userSources.get(source.name);
203
265
 
204
266
  if (cachedAfterTouch && now - cachedAfterTouch.fetchedAt < ttlMs) {
205
- return cachedAfterTouch.grants;
267
+ return {failed: false, grants: cachedAfterTouch.grants};
206
268
  }
207
269
 
208
270
  try {
209
271
  const grants = await source.getGrants({user});
210
272
  userSources.set(source.name, {fetchedAt: now, grants});
211
- return grants;
273
+ recordDenyPosture(user.id, source, grants);
274
+ return {failed: false, grants};
212
275
  } catch (error) {
213
276
  logger.warn("Permission source refresh failed", {
214
277
  error: error instanceof Error ? error.message : String(error),
215
278
  policy: source.staleOnFailure ?? "deny",
216
279
  source: source.name,
217
280
  });
218
- return grantsAfterSourceFailure(source, cachedAfterTouch, now);
281
+ return {
282
+ failed: true,
283
+ grants: grantsAfterSourceFailure(user, source, cachedAfterTouch, now),
284
+ };
219
285
  }
220
286
  };
221
287
 
@@ -235,9 +301,11 @@ export const createPermissionResolver = <S extends Statements>(args: {
235
301
  const roleNames = [...getUserRoles(user)];
236
302
  const permissionSets: PermissionSet[] = [];
237
303
  const sourceResults = new Map<string, PermissionSourceGrants | null>();
304
+ let anySourceFailed = false;
238
305
 
239
306
  for (const source of sources) {
240
- const grants = await fetchSourceGrants(user, source, shouldCache);
307
+ const {failed, grants} = await fetchSourceGrants(user, source, shouldCache);
308
+ anySourceFailed = anySourceFailed || failed;
241
309
  sourceResults.set(source.name, grants);
242
310
  if (!grants) {
243
311
  continue;
@@ -269,7 +337,8 @@ export const createPermissionResolver = <S extends Statements>(args: {
269
337
  }
270
338
  }
271
339
 
272
- if (shouldCache) {
340
+ // A set computed during a source outage is not cached, so recovery takes effect at once.
341
+ if (shouldCache && !anySourceFailed) {
273
342
  rememberPermissions(cacheKey, {
274
343
  expiresAt: DateTime.now().plus({milliseconds: cacheTtlMs}).toMillis(),
275
344
  permissions,