@terreno/api 57.19.2 → 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 +393 -0
  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,227 @@
1
+ /**
2
+ * Carries Better Auth's challenge cookies (the two-factor challenge, the trust-device token, and
3
+ * the passkey challenge) in a response and request header, so a bearer-mode web client
4
+ * (`credentials: "omit"`) on another site can finish two-factor and passkey sign-in without
5
+ * cookies.
6
+ *
7
+ * Better Auth keeps each of those values in a signed cookie. This plugin copies the signed
8
+ * values from Set-Cookie into `X-Terreno-Auth-Challenge` on the way out, and turns the header
9
+ * back into cookies on the way in. The values stay signed with the auth secret, so a client
10
+ * cannot forge or alter one: Better Auth's `getSignedCookie` rejects a bad signature exactly as
11
+ * it would for a cookie.
12
+ */
13
+
14
+ import type {BetterAuthPlugin} from "better-auth";
15
+ import {createAuthMiddleware} from "better-auth/api";
16
+ import {parseCookies, parseSetCookieHeader, setRequestCookie} from "better-auth/cookies";
17
+ import {DateTime} from "luxon";
18
+
19
+ /**
20
+ * The header that carries challenge cookies. A client opts in by sending it on a challenge
21
+ * request (`AUTH_CHALLENGE_EMPTY` when it holds none); only then does a response carry it.
22
+ */
23
+ export const AUTH_CHALLENGE_HEADER = "X-Terreno-Auth-Challenge";
24
+
25
+ /** The value a client sends when it holds no challenge cookies, to opt in to receiving them. */
26
+ export const AUTH_CHALLENGE_EMPTY = "-";
27
+
28
+ /** Better Auth paths, relative to its base path, whose requests accept the header. */
29
+ const AUTH_CHALLENGE_PATH_PREFIXES = ["/two-factor/", "/passkey/", "/sign-in/"] as const;
30
+
31
+ // Three signed cookies fit comfortably; anything longer is not ours and is ignored.
32
+ const MAX_HEADER_LENGTH = 4096;
33
+
34
+ const TWO_FACTOR_COOKIE = "two_factor";
35
+ const TRUST_DEVICE_COOKIE = "trust_device";
36
+ const DONT_REMEMBER_COOKIE = "dont_remember";
37
+ const DEFAULT_PASSKEY_COOKIE = "better-auth-passkey";
38
+
39
+ /** The parts of Better Auth's context this plugin reads, on both request and hook paths. */
40
+ interface ChallengeCookieContext {
41
+ createAuthCookie: (name: string) => {name: string};
42
+ getPlugin: (id: string) => unknown;
43
+ }
44
+
45
+ interface PasskeyPluginLike {
46
+ options?: {advanced?: {webAuthnChallengeCookie?: string}};
47
+ }
48
+
49
+ /** Real cookie names, with the prefix and `__Secure-` variant Better Auth gives them. */
50
+ interface ChallengeCookieNames {
51
+ /** "Don't remember me" from a `rememberMe: false` sign-in, read when the 2FA verify signs in. */
52
+ dontRemember: string;
53
+ passkey: string;
54
+ trustDevice: string;
55
+ twoFactor: string;
56
+ }
57
+
58
+ /**
59
+ * The challenge cookies the header may carry. Session cookies are never among them, so the header
60
+ * can never set a session.
61
+ */
62
+ const challengeCookieNames = (context: ChallengeCookieContext): ChallengeCookieNames => {
63
+ const passkey = context.getPlugin("passkey") as PasskeyPluginLike | null | undefined;
64
+ const passkeyCookie =
65
+ passkey?.options?.advanced?.webAuthnChallengeCookie ?? DEFAULT_PASSKEY_COOKIE;
66
+ return {
67
+ dontRemember: context.createAuthCookie(DONT_REMEMBER_COOKIE).name,
68
+ passkey: context.createAuthCookie(passkeyCookie).name,
69
+ trustDevice: context.createAuthCookie(TRUST_DEVICE_COOKIE).name,
70
+ twoFactor: context.createAuthCookie(TWO_FACTOR_COOKIE).name,
71
+ };
72
+ };
73
+
74
+ const isChallengePath = (url: string, baseURL: string): boolean => {
75
+ const basePath = new URL(baseURL).pathname.replace(/\/+$/, "");
76
+ const {pathname} = new URL(url);
77
+ if (!pathname.startsWith(`${basePath}/`)) {
78
+ return false;
79
+ }
80
+ const relative = pathname.slice(basePath.length);
81
+ return AUTH_CHALLENGE_PATH_PREFIXES.some((prefix) => relative.startsWith(prefix));
82
+ };
83
+
84
+ const readChallengeHeader = (headers: Headers | undefined): string | null => {
85
+ const value = headers?.get(AUTH_CHALLENGE_HEADER);
86
+ if (!value || value.length > MAX_HEADER_LENGTH) {
87
+ return null;
88
+ }
89
+ return value;
90
+ };
91
+
92
+ /**
93
+ * Adds the challenge cookies named in the header to the request's Cookie header. A cookie the
94
+ * request already carries wins, and names outside the challenge list are ignored. Returns null
95
+ * when nothing changes.
96
+ */
97
+ const mergeChallengeCookies = (
98
+ request: Request,
99
+ context: ChallengeCookieContext
100
+ ): Headers | null => {
101
+ const header = readChallengeHeader(request.headers);
102
+ if (!header) {
103
+ return null;
104
+ }
105
+ const carried = new URLSearchParams(header);
106
+ const existing = parseCookies(request.headers.get("cookie") ?? "");
107
+ const headers = new Headers(request.headers);
108
+ let isChanged = false;
109
+ for (const name of Object.values(challengeCookieNames(context))) {
110
+ const value = carried.get(name);
111
+ if (!value || existing.has(name)) {
112
+ continue;
113
+ }
114
+ setRequestCookie(headers, name, value);
115
+ isChanged = true;
116
+ }
117
+ return isChanged ? headers : null;
118
+ };
119
+
120
+ interface SetCookieAttributes {
121
+ expires?: Date;
122
+ "max-age"?: number;
123
+ value: string;
124
+ }
125
+
126
+ const isExpired = (cookie: SetCookieAttributes): boolean => {
127
+ if (!cookie.value || cookie["max-age"] === 0) {
128
+ return true;
129
+ }
130
+ return Boolean(cookie.expires && DateTime.fromJSDate(cookie.expires) <= DateTime.now());
131
+ };
132
+
133
+ /**
134
+ * The challenge cookies a response sets, as `name=value` pairs (URL search params). An expired
135
+ * cookie is sent with an empty value, which tells the client to forget it. `dont_remember` goes
136
+ * only with the two-factor challenge it belongs to, since every `rememberMe: false` sign-in
137
+ * sets it.
138
+ */
139
+ const collectChallengeCookies = (
140
+ setCookie: string,
141
+ names: ChallengeCookieNames
142
+ ): URLSearchParams => {
143
+ const parsed = parseSetCookieHeader(setCookie) as Map<string, SetCookieAttributes>;
144
+ const pairs = new URLSearchParams();
145
+ const carried = [names.twoFactor, names.trustDevice, names.passkey];
146
+ if (parsed.has(names.twoFactor)) {
147
+ carried.push(names.dontRemember);
148
+ }
149
+ for (const name of carried) {
150
+ const cookie = parsed.get(name);
151
+ if (!cookie) {
152
+ continue;
153
+ }
154
+ pairs.set(name, isExpired(cookie) ? "" : cookie.value);
155
+ }
156
+ return pairs;
157
+ };
158
+
159
+ /**
160
+ * The Better Auth plugin behind cookie-free challenges. `buildFeaturePlugins` adds it after the
161
+ * two-factor and passkey plugins whenever either is configured, so its after hook sees the
162
+ * cookies their hooks set.
163
+ *
164
+ * - Requests: on `{basePath}/two-factor/*`, `/passkey/*`, and `/sign-in/*` (where a trusted
165
+ * device is checked), the header's challenge cookies are merged into the Cookie header. This
166
+ * runs in `onRequest`, before endpoint hooks, so `bearer()` still adds the session cookie on
167
+ * top (a passkey registration needs both).
168
+ * - Responses: when the request sent the header, the challenge cookies the response sets are
169
+ * copied into it, and it is added to `Access-Control-Expose-Headers` the way `bearer()`
170
+ * exposes `set-auth-token`. A sign-in that answers with a two-factor challenge loses the
171
+ * `set-auth-token` of the session two-factor deleted. Only values the response sets are
172
+ * copied, and only for requests that send the header, so a cookie-mode page whose own code
173
+ * never sends it keeps its challenge cookies httpOnly.
174
+ */
175
+ export const createChallengeHeadersPlugin = (): BetterAuthPlugin => {
176
+ return {
177
+ hooks: {
178
+ after: [
179
+ {
180
+ handler: createAuthMiddleware(async (ctx): Promise<void> => {
181
+ const responseHeaders = ctx.context.responseHeaders;
182
+ const setCookie = responseHeaders?.get("set-cookie");
183
+ if (!responseHeaders || !setCookie) {
184
+ return;
185
+ }
186
+ const names = challengeCookieNames(ctx.context as unknown as ChallengeCookieContext);
187
+ const pairs = collectChallengeCookies(setCookie, names);
188
+ if (pairs.size === 0) {
189
+ return;
190
+ }
191
+ // A sign-in that needs a second factor kept no session: two-factor deleted the one
192
+ // bearer() had already turned into `set-auth-token`, so that token is dead.
193
+ if (pairs.get(names.twoFactor) && !ctx.context.newSession) {
194
+ responseHeaders.delete("set-auth-token");
195
+ }
196
+ const encoded = pairs.toString();
197
+ const exposed = new Set(
198
+ (responseHeaders.get("access-control-expose-headers") ?? "")
199
+ .split(",")
200
+ .map((header) => header.trim())
201
+ .filter(Boolean)
202
+ );
203
+ exposed.add(AUTH_CHALLENGE_HEADER);
204
+ ctx.setHeader(AUTH_CHALLENGE_HEADER, encoded);
205
+ ctx.setHeader("Access-Control-Expose-Headers", Array.from(exposed).join(", "));
206
+ }),
207
+ matcher: (context): boolean =>
208
+ Boolean(
209
+ readChallengeHeader(context.request?.headers) ?? readChallengeHeader(context.headers)
210
+ ),
211
+ },
212
+ ],
213
+ },
214
+ id: "terreno-challenge-headers",
215
+ onRequest: async (request, context): Promise<{request: Request} | undefined> => {
216
+ if (!isChallengePath(request.url, context.baseURL)) {
217
+ return undefined;
218
+ }
219
+ const headers = mergeChallengeCookies(request, context as unknown as ChallengeCookieContext);
220
+ if (!headers) {
221
+ return undefined;
222
+ }
223
+ // `duplex` lets a streamed body move to the new request on Node's fetch implementation.
224
+ return {request: new Request(request, {duplex: "half", headers} as RequestInit)};
225
+ },
226
+ } satisfies BetterAuthPlugin;
227
+ };