@terreno/api 57.18.0 → 57.20.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 (169) hide show
  1. package/CHANGELOG.md +2071 -2
  2. package/dist/accountSecurity/accessActions.d.ts +38 -0
  3. package/dist/accountSecurity/accessActions.js +157 -0
  4. package/dist/accountSecurity/accountSecurityApp.d.ts +219 -0
  5. package/dist/accountSecurity/accountSecurityApp.js +438 -0
  6. package/dist/accountSecurity/accountSecurityService.d.ts +200 -0
  7. package/dist/accountSecurity/accountSecurityService.js +481 -0
  8. package/dist/accountSecurity/credentialActions.d.ts +16 -0
  9. package/dist/accountSecurity/credentialActions.js +189 -0
  10. package/dist/accountSecurity/membershipActions.d.ts +15 -0
  11. package/dist/accountSecurity/membershipActions.js +81 -0
  12. package/dist/accountSecurity/orgSecurityRoutes.d.ts +50 -0
  13. package/dist/accountSecurity/orgSecurityRoutes.js +149 -0
  14. package/dist/accountSecurity/securityEventHooks.d.ts +44 -0
  15. package/dist/accountSecurity/securityEventHooks.js +223 -0
  16. package/dist/accountSecurity/securityEvents.d.ts +162 -0
  17. package/dist/accountSecurity/securityEvents.js +114 -0
  18. package/dist/accountSecurity/securityNotifications.d.ts +125 -0
  19. package/dist/accountSecurity/securityNotifications.js +333 -0
  20. package/dist/api.js +38 -6
  21. package/dist/audit/auditEventModel.d.ts +5 -3
  22. package/dist/audit/auditEventModel.js +8 -6
  23. package/dist/audit/processQueue.js +4 -2
  24. package/dist/audit/record.d.ts +2 -2
  25. package/dist/audit/record.js +3 -0
  26. package/dist/authRecovery.js +29 -1
  27. package/dist/betterAuth.d.ts +179 -10
  28. package/dist/betterAuthApp.d.ts +15 -0
  29. package/dist/betterAuthApp.js +23 -0
  30. package/dist/betterAuthChallengeHeaders.d.ts +37 -0
  31. package/dist/betterAuthChallengeHeaders.js +180 -0
  32. package/dist/betterAuthFeatures.d.ts +54 -0
  33. package/dist/betterAuthFeatures.js +239 -0
  34. package/dist/betterAuthMethods.d.ts +73 -0
  35. package/dist/betterAuthMethods.js +55 -0
  36. package/dist/betterAuthOAuthHandoff.d.ts +10 -2
  37. package/dist/betterAuthOAuthHandoff.js +222 -24
  38. package/dist/betterAuthSetPassword.d.ts +33 -0
  39. package/dist/betterAuthSetPassword.js +166 -0
  40. package/dist/betterAuthSetup.d.ts +57 -8
  41. package/dist/betterAuthSetup.js +327 -36
  42. package/dist/consentApp.d.ts +9 -4
  43. package/dist/consentApp.js +344 -28
  44. package/dist/consentStatus.d.ts +60 -0
  45. package/dist/consentStatus.js +111 -0
  46. package/dist/errors.d.ts +6 -0
  47. package/dist/errors.js +41 -2
  48. package/dist/expressServer.js +3 -2
  49. package/dist/index.d.ts +14 -2
  50. package/dist/index.js +23 -3
  51. package/dist/mcp/oauth.js +151 -11
  52. package/dist/mcp/oauthMetadata.d.ts +2 -1
  53. package/dist/mcp/oauthMetadata.js +7 -4
  54. package/dist/models/consentResponse.js +51 -0
  55. package/dist/models/mcpOAuthClient.js +78 -2
  56. package/dist/models/mcpOAuthToken.js +28 -4
  57. package/dist/orgs/membershipGuards.d.ts +7 -0
  58. package/dist/orgs/membershipGuards.js +32 -0
  59. package/dist/orgs/orgsApp.d.ts +19 -1
  60. package/dist/orgs/orgsApp.js +55 -24
  61. package/dist/rateLimit/policies.js +8 -0
  62. package/dist/rbac/access.js +2 -1
  63. package/dist/rbac/resolve.d.ts +9 -1
  64. package/dist/rbac/resolve.js +21 -16
  65. package/dist/rbac/roleManager.d.ts +6 -0
  66. package/dist/rbac/roleManager.js +8 -7
  67. package/dist/rbac/roleModel.d.ts +1 -0
  68. package/dist/rbac/roleModel.js +45 -3
  69. package/dist/rbac/statements.d.ts +2 -2
  70. package/dist/rbac/statements.js +10 -1
  71. package/dist/rbac/types.d.ts +6 -0
  72. package/dist/rbac/userWriteGuards.js +2 -1
  73. package/dist/schemaMetadata.js +8 -1
  74. package/dist/seedRunner.js +7 -2
  75. package/dist/terrenoApp.d.ts +4 -0
  76. package/dist/terrenoApp.js +15 -0
  77. package/dist/tests/models.d.ts +5 -0
  78. package/dist/tests/models.js +8 -0
  79. package/dist/types/consentResponse.d.ts +8 -0
  80. package/dist/types/mcpOAuth.d.ts +35 -2
  81. package/package.json +6 -3
  82. package/src/__snapshots__/openApi.test.ts.snap +288 -0
  83. package/src/__snapshots__/openApiBuilder.test.ts.snap +96 -0
  84. package/src/accountSecurity/accessActions.test.ts +723 -0
  85. package/src/accountSecurity/accessActions.ts +173 -0
  86. package/src/accountSecurity/accountSecurity.test.ts +947 -0
  87. package/src/accountSecurity/accountSecurityApp.ts +720 -0
  88. package/src/accountSecurity/accountSecurityService.ts +826 -0
  89. package/src/accountSecurity/credentialActions.test.ts +867 -0
  90. package/src/accountSecurity/credentialActions.ts +260 -0
  91. package/src/accountSecurity/membershipActions.ts +89 -0
  92. package/src/accountSecurity/orgSecurityRoutes.test.ts +841 -0
  93. package/src/accountSecurity/orgSecurityRoutes.ts +232 -0
  94. package/src/accountSecurity/securityEventHooks.ts +294 -0
  95. package/src/accountSecurity/securityEvents.ts +165 -0
  96. package/src/accountSecurity/securityNotifications.test.ts +1323 -0
  97. package/src/accountSecurity/securityNotifications.ts +516 -0
  98. package/src/api.arrayOperations.test.ts +71 -0
  99. package/src/api.ts +38 -7
  100. package/src/audit/auditEventModel.ts +10 -7
  101. package/src/audit/processQueue.ts +4 -2
  102. package/src/audit/record.test.ts +15 -0
  103. package/src/audit/record.ts +10 -2
  104. package/src/authRecovery.test.ts +23 -0
  105. package/src/authRecovery.ts +34 -1
  106. package/src/authRecoveryBetterAuth.test.ts +169 -0
  107. package/src/betterAuth.ts +194 -8
  108. package/src/betterAuthApp.ts +32 -0
  109. package/src/betterAuthChallengeHeaders.test.ts +476 -0
  110. package/src/betterAuthChallengeHeaders.ts +227 -0
  111. package/src/betterAuthFeatures.test.ts +489 -0
  112. package/src/betterAuthFeatures.ts +283 -0
  113. package/src/betterAuthLinking.test.ts +844 -0
  114. package/src/betterAuthMethods.test.ts +138 -0
  115. package/src/betterAuthMethods.ts +98 -0
  116. package/src/betterAuthOAuthHandoff.test.ts +482 -69
  117. package/src/betterAuthOAuthHandoff.ts +293 -33
  118. package/src/betterAuthOAuthProxy.test.ts +421 -0
  119. package/src/betterAuthPasswordReset.test.ts +190 -0
  120. package/src/betterAuthSetPassword.test.ts +378 -0
  121. package/src/betterAuthSetPassword.ts +213 -0
  122. package/src/betterAuthSetup.test.ts +39 -7
  123. package/src/betterAuthSetup.ts +457 -38
  124. package/src/consentApp.test.ts +869 -2
  125. package/src/consentApp.ts +438 -36
  126. package/src/consentStatus.test.ts +226 -0
  127. package/src/consentStatus.ts +171 -0
  128. package/src/errors.test.ts +81 -0
  129. package/src/errors.ts +50 -1
  130. package/src/expressServer.test.ts +29 -0
  131. package/src/expressServer.ts +3 -2
  132. package/src/index.ts +30 -0
  133. package/src/mcp/oauth.test.ts +463 -2
  134. package/src/mcp/oauth.ts +184 -13
  135. package/src/mcp/oauthMetadata.ts +5 -2
  136. package/src/models/consentResponse.ts +53 -0
  137. package/src/models/mcpOAuthClient.ts +100 -3
  138. package/src/models/mcpOAuthToken.ts +30 -5
  139. package/src/orgs/membershipGuards.ts +39 -0
  140. package/src/orgs/orgRbac.test.ts +1 -1
  141. package/src/orgs/orgsApp.test.ts +101 -2
  142. package/src/orgs/orgsApp.ts +69 -28
  143. package/src/rateLimit/policies.test.ts +53 -0
  144. package/src/rateLimit/policies.ts +8 -0
  145. package/src/rbac/access.ts +4 -1
  146. package/src/rbac/resolve.test.ts +65 -0
  147. package/src/rbac/resolve.ts +37 -17
  148. package/src/rbac/roleManager.test.ts +64 -0
  149. package/src/rbac/roleManager.ts +15 -6
  150. package/src/rbac/roleModel.test.ts +174 -1
  151. package/src/rbac/roleModel.ts +66 -3
  152. package/src/rbac/routes.test.ts +58 -0
  153. package/src/rbac/statements.test.ts +4 -1
  154. package/src/rbac/statements.ts +11 -1
  155. package/src/rbac/types.ts +6 -1
  156. package/src/rbac/userWriteGuards.test.ts +48 -0
  157. package/src/rbac/userWriteGuards.ts +5 -2
  158. package/src/schemaMetadata.test.ts +39 -0
  159. package/src/schemaMetadata.ts +11 -1
  160. package/src/seedRunner.test.ts +56 -0
  161. package/src/seedRunner.ts +7 -2
  162. package/src/terrenoApp.ts +20 -0
  163. package/src/tests/accountSecurityTestApp.ts +290 -0
  164. package/src/tests/betterAuthStubs.ts +188 -0
  165. package/src/tests/mockOidcProvider.ts +105 -0
  166. package/src/tests/models.ts +13 -0
  167. package/src/tests/softwareAuthenticator.ts +183 -0
  168. package/src/types/consentResponse.ts +8 -0
  169. package/src/types/mcpOAuth.ts +39 -3
@@ -0,0 +1,173 @@
1
+ /**
2
+ * Access recovery actions: sign a user out everywhere, mail a password reset, disable or enable
3
+ * the account, and issue a set-password link to a legacy user who has no way to sign in.
4
+ *
5
+ * Revoking deletes the user's Better Auth sessions. Bearer clients (native apps, bearer-mode web,
6
+ * sockets) present the session token itself, so they fail on their next request. Cookie clients
7
+ * can keep working for up to Better Auth's 5-minute session cookie cache (Q7).
8
+ */
9
+
10
+ import {ConflictError, APIError as TerrenoAPIError} from "../errors";
11
+ import type {SecurityActionResult, SecurityRouteAction} from "./accountSecurityApp";
12
+ import type {SignInLinkRefusal} from "./accountSecurityService";
13
+
14
+ /**
15
+ * The RBAC statement `issue-sign-in-link` needs on top of `user:manageSecurity` (D11). Only
16
+ * `superadmin` holds it by default (through `*`); without RBAC the actor needs `admin: true`.
17
+ */
18
+ export const ISSUE_SIGN_IN_LINK_PERMISSION = {user: ["issueSignInLink"]} as const;
19
+
20
+ const NOT_LINKED_TITLE = "User has no Better Auth account";
21
+
22
+ const RESET_NOT_CONFIGURED_TITLE = "Password reset email is not configured";
23
+
24
+ const SIGN_IN_LINK_NOT_CONFIGURED_TITLE = "Sign-in links are not configured";
25
+
26
+ const SIGN_IN_LINK_REFUSALS: Record<
27
+ Exclude<SignInLinkRefusal, "not-configured">,
28
+ {detail: string; title: string}
29
+ > = {
30
+ "email-taken": {
31
+ detail: "Another Better Auth user already uses this email",
32
+ title: "Email already belongs to another sign-in account",
33
+ },
34
+ "has-password": {
35
+ detail: "The user can sign in with their existing password, which links their account",
36
+ title: "User already has a password",
37
+ },
38
+ linked: {
39
+ detail:
40
+ "Use send-password-reset for a user who already has a Better Auth account they have used",
41
+ title: "User already has a Better Auth account",
42
+ },
43
+ "no-email": {
44
+ detail: "Add an email to the user before issuing a sign-in link",
45
+ title: "User has no email",
46
+ },
47
+ };
48
+
49
+ /** `POST /:userId/security/revoke-sessions`: sign the user out on every device. */
50
+ export const revokeSessionsAction: SecurityRouteAction = {
51
+ id: "revoke-sessions",
52
+ isApplicable: ({state}) => state.sessions.active > 0,
53
+ isSupported: (features) => features.betterAuth,
54
+ method: "post",
55
+ path: "/revoke-sessions",
56
+ run: async ({service, target}): Promise<SecurityActionResult> => {
57
+ const {jwtRefreshRevoked, revokedCount} = await service.revokeSessions(target);
58
+ return {
59
+ audit: {jwtRefreshRevoked, revokedCount},
60
+ changed: revokedCount > 0 || jwtRefreshRevoked,
61
+ data: {jwtRefreshRevoked, revokedCount},
62
+ };
63
+ },
64
+ };
65
+
66
+ /**
67
+ * `POST /:userId/security/send-password-reset`: mail the user a Better Auth password-reset link.
68
+ * 501 without `sendMail` or `publicAppUrl`; 409 for a user with no Better Auth account.
69
+ */
70
+ export const sendPasswordResetAction: SecurityRouteAction = {
71
+ id: "send-password-reset",
72
+ isApplicable: ({state}) => state.betterAuthLinked,
73
+ isSupported: (features) => features.betterAuth,
74
+ method: "post",
75
+ path: "/send-password-reset",
76
+ run: async ({service, target}): Promise<SecurityActionResult> => {
77
+ const result = await service.sendPasswordReset(target);
78
+ if (result.sent) {
79
+ return {audit: {}, changed: true, data: {sent: true}};
80
+ }
81
+ if (result.reason === "not-configured") {
82
+ throw new TerrenoAPIError({
83
+ detail: "Configure sendMail and publicAppUrl in BetterAuthConfig",
84
+ status: 501,
85
+ title: RESET_NOT_CONFIGURED_TITLE,
86
+ });
87
+ }
88
+ throw new ConflictError({
89
+ detail: "Issue a sign-in link instead, which creates the Better Auth account",
90
+ title: NOT_LINKED_TITLE,
91
+ });
92
+ },
93
+ };
94
+
95
+ /**
96
+ * `POST /:userId/security/disable`: set `User.disabled` and revoke every session. A disabled
97
+ * user's remaining credentials are refused on REST (401) and on the socket handshake.
98
+ */
99
+ export const disableAccountAction: SecurityRouteAction = {
100
+ id: "disable",
101
+ isApplicable: ({state}) => !state.disabled,
102
+ isSupported: (features) => features.disableAccount,
103
+ method: "post",
104
+ path: "/disable",
105
+ // Under the org-admin prefix "disable" suspends the membership instead (Q8, T9).
106
+ platformOnly: true,
107
+ run: async ({service, target}): Promise<SecurityActionResult> => {
108
+ const {changed} = await service.setDisabled(target, true);
109
+ if (!changed) {
110
+ return {changed: false};
111
+ }
112
+ const {jwtRefreshRevoked, revokedCount} = await service.revokeSessions(target);
113
+ return {
114
+ audit: {jwtRefreshRevoked, revokedCount},
115
+ changed: true,
116
+ data: {jwtRefreshRevoked, revokedCount},
117
+ };
118
+ },
119
+ };
120
+
121
+ /** `POST /:userId/security/enable`: clear `User.disabled` so the user can sign in again. */
122
+ export const enableAccountAction: SecurityRouteAction = {
123
+ id: "enable",
124
+ isApplicable: ({state}) => state.disabled,
125
+ isSupported: (features) => features.disableAccount,
126
+ method: "post",
127
+ path: "/enable",
128
+ platformOnly: true,
129
+ run: async ({service, target}): Promise<SecurityActionResult> =>
130
+ service.setDisabled(target, false),
131
+ };
132
+
133
+ /**
134
+ * `POST /:userId/security/issue-sign-in-link` (platform only, `user:issueSignInLink`): for a
135
+ * legacy User with no Better Auth account and no password (a GitHub-JWT user), create the Better
136
+ * Auth user, link it, and return a single-use set-password link `{url, expiresAt}` for the
137
+ * administrator to hand over. The link is a password-reset token, so Better Auth's
138
+ * `/reset-password` consumes it once. A link that was never used can be issued again.
139
+ */
140
+ export const issueSignInLinkAction: SecurityRouteAction = {
141
+ id: "issue-sign-in-link",
142
+ isApplicable: ({state}) =>
143
+ !state.legacyPassword &&
144
+ (!state.betterAuthLinked ||
145
+ (!state.emailVerified &&
146
+ !state.password &&
147
+ state.providers.length === 0 &&
148
+ state.passkeys.count === 0)),
149
+ isSupported: (features) => features.betterAuth,
150
+ method: "post",
151
+ path: "/issue-sign-in-link",
152
+ platformOnly: true,
153
+ requiredPermission: ISSUE_SIGN_IN_LINK_PERMISSION,
154
+ run: async ({service, target}): Promise<SecurityActionResult> => {
155
+ const result = await service.issueSignInLink(target);
156
+ if (result.issued) {
157
+ // The URL carries the token, so it goes to the administrator and never into the audit log.
158
+ return {
159
+ audit: {betterAuthId: result.betterAuthId, expiresAt: result.expiresAt},
160
+ changed: true,
161
+ data: {expiresAt: result.expiresAt, url: result.url},
162
+ };
163
+ }
164
+ if (result.reason === "not-configured") {
165
+ throw new TerrenoAPIError({
166
+ detail: "Set publicAppUrl in BetterAuthConfig so the link opens the app's reset page",
167
+ status: 501,
168
+ title: SIGN_IN_LINK_NOT_CONFIGURED_TITLE,
169
+ });
170
+ }
171
+ throw new ConflictError(SIGN_IN_LINK_REFUSALS[result.reason]);
172
+ },
173
+ };