@terreno/api 57.16.1 → 57.17.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
package/src/betterAuth.ts CHANGED
@@ -5,6 +5,22 @@
5
5
  * JWT/Passport authentication system.
6
6
  */
7
7
 
8
+ import type {BetterAuthOptions, BetterAuthPlugin} from "better-auth";
9
+
10
+ /**
11
+ * Makes nested option objects optional too, so `options` can set one nested field (such as
12
+ * `emailAndPassword.requireEmailVerification`) without restating the fields Terreno sets.
13
+ * Functions, arrays, and strings are kept as they are.
14
+ */
15
+ export type BetterAuthOptionsOverride<T = Omit<BetterAuthOptions, "basePath" | "plugins">> =
16
+ T extends (...args: never[]) => unknown
17
+ ? T
18
+ : T extends readonly unknown[] | string
19
+ ? T
20
+ : T extends object
21
+ ? {[K in keyof T]?: BetterAuthOptionsOverride<T[K]>}
22
+ : T;
23
+
8
24
  /**
9
25
  * OAuth provider configuration for Better Auth.
10
26
  */
@@ -71,7 +87,13 @@ export interface BetterAuthConfig {
71
87
  publicAppUrl?: string;
72
88
 
73
89
  /** Deliver auth mail. Typically `getCommsService().sendMail`. */
74
- sendMail?: (message: {html?: string; subject: string; text: string; to: string}) => Promise<void>;
90
+ sendMail?: (message: {
91
+ html?: string;
92
+ sensitive?: boolean;
93
+ subject: string;
94
+ text: string;
95
+ to: string;
96
+ }) => Promise<void>;
75
97
 
76
98
  /**
77
99
  * Render reset/verify mail. Pass `@terreno/comms` `renderAuthMail` so JWT and
@@ -97,6 +119,87 @@ export interface BetterAuthConfig {
97
119
  * `NODE_ENV=production`).
98
120
  */
99
121
  disableRateLimit?: boolean;
122
+
123
+ /**
124
+ * Any other Better Auth option, deep-merged over the options Terreno builds from this
125
+ * config (for example `emailAndPassword.requireEmailVerification`,
126
+ * `emailAndPassword.password.{hash, verify}`, or `databaseHooks`). Arrays replace Terreno's
127
+ * rather than merging by index. An explicit value wins (an `undefined` value is ignored),
128
+ * including over Terreno's security defaults: the `database` adapter, `emailAndPassword.revokeSessionsOnPasswordReset`, and
129
+ * `session.cookieCache`. Set the base path with `basePath` and plugins with `plugins`.
130
+ */
131
+ options?: BetterAuthOptionsOverride;
132
+
133
+ /**
134
+ * Better Auth plugins, appended after Terreno's `bearer()` plugin. Their endpoints mount
135
+ * under `basePath`. They are not added to the `auth.api` type.
136
+ */
137
+ plugins?: BetterAuthPlugin[];
138
+
139
+ /**
140
+ * Hands a one-time token to web apps that sign in with a social or generic OAuth provider
141
+ * from another site, so they can use the bearer scheme without cookies. Unset by default.
142
+ *
143
+ * Start the sign-in with a top-level navigation to
144
+ * `GET {basePath}/oauth-handoff/start?provider=<id>&callbackURL=<url>` (optional
145
+ * `errorCallbackURL`), not with `POST /sign-in/social` from fetch. The start endpoint sets the
146
+ * OAuth state cookie first-party on the API's origin and redirects to the provider, so the
147
+ * cookie comes back on the callback even when the browser blocks third-party cookies. It works
148
+ * for social and generic OAuth providers. It answers 400, with no redirect, unless
149
+ * `callbackURL` (and `errorCallbackURL`, when given) is an absolute URL on one of `webOrigins`
150
+ * that `trustedOrigins` also allows, and unless the request is a page navigation. The URL's
151
+ * query is kept as it is. When the provider is unknown or cannot start, it redirects to
152
+ * `errorCallbackURL` (or `callbackURL`) with `error=provider_not_found` or
153
+ * `error=sign_in_failed`. It does not take `scopes`, `loginHint`, `requestSignUp`, or
154
+ * `newUserCallbackURL`, so a provider with `disableImplicitSignUp` cannot sign up new users
155
+ * through it. Better Auth's limiter allows three starts per ten seconds per IP.
156
+ *
157
+ * When set, Terreno adds Better Auth's `oneTimeToken` plugin (three-minute, single-use tokens,
158
+ * stored hashed, which clients cannot mint) and an after-hook on `/callback/:id`. When that
159
+ * callback creates a session and redirects to a listed path on one of `webOrigins`, the
160
+ * redirect `Location` gets `ott=<token>` in its URL fragment. The web app exchanges it once
161
+ * with `POST {basePath}/one-time-token/verify`, which answers with the session and the
162
+ * `set-auth-token` header.
163
+ *
164
+ * No other redirect gets a token: paths outside `callbackPaths`, app schemes (`exp://`,
165
+ * `terreno://`), relative paths, the API's own origin, and origins that only `trustedOrigins`
166
+ * allows (including wildcard patterns) are left as they are. The start endpoint refuses a
167
+ * `callbackURL` outside `callbackPaths` too; `errorCallbackURL` may be any path on a web
168
+ * origin, since an error redirect never carries a token. Each web origin must also be in
169
+ * `trustedOrigins`, or both the start endpoint and `POST /sign-in/social` refuse it as a
170
+ * `callbackURL`.
171
+ *
172
+ * The handoff is for bearer clients only. A handed-off callback redirect carries no session
173
+ * cookie for the API's origin, and verify drops every Set-Cookie it would send (the session
174
+ * cookies and any a plugin adds there), so a cookie-mode app gets no session from it.
175
+ */
176
+ oauthHandoff?: BetterAuthOAuthHandoffConfig;
177
+ }
178
+
179
+ /**
180
+ * Where the OAuth one-time-token handoff may send a token.
181
+ */
182
+ export interface BetterAuthOAuthHandoffConfig {
183
+ /**
184
+ * Exact `http:` or `https:` origins of the web apps, such as `"https://app.example.com"`.
185
+ * Scheme, host and port must match the redirect exactly. Patterns, paths, and other schemes
186
+ * are rejected when Better Auth is created, and so is an empty list.
187
+ */
188
+ webOrigins: string[];
189
+
190
+ /**
191
+ * Exact paths on those origins that may receive the token, such as `"/auth/return"`.
192
+ * Defaults to `["/"]`. The redirect must already be written the way the URL parser prints
193
+ * it (lower-case host, no default port, credentials, backslashes, or dot segments), and its
194
+ * path must equal one of these exactly (case, trailing slashes and encoded characters all
195
+ * count). Its query is free, so `?handoff=<nonce>` still works. Each entry must start with one `/` and be in normal form:
196
+ * no `.` or `..` segments, encoded slashes or backslashes, spaces, query, or fragment.
197
+ *
198
+ * Keep the list to the page that reads the token. That page must strip the fragment before
199
+ * anything else runs and must never redirect, on the server or in the browser, because a
200
+ * browser carries the fragment through a redirect that has none of its own.
201
+ */
202
+ callbackPaths?: string[];
100
203
  }
101
204
 
102
205
  /**