@terreno/syncdb 58.0.6 → 58.1.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 (50) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/dist/auth/TerrenoOAuthConsentScreen.d.ts +65 -0
  3. package/dist/auth/TerrenoOAuthConsentScreen.d.ts.map +1 -0
  4. package/dist/auth/TerrenoOAuthConsentScreen.js +119 -0
  5. package/dist/auth/TerrenoOAuthConsentScreen.js.map +1 -0
  6. package/dist/auth/auth.d.ts +2 -0
  7. package/dist/auth/auth.d.ts.map +1 -1
  8. package/dist/auth/auth.js +2 -0
  9. package/dist/auth/auth.js.map +1 -1
  10. package/dist/auth/useLoginController.d.ts +23 -1
  11. package/dist/auth/useLoginController.d.ts.map +1 -1
  12. package/dist/auth/useLoginController.js +14 -4
  13. package/dist/auth/useLoginController.js.map +1 -1
  14. package/dist/auth/useMcpOAuthConsent.d.ts +65 -0
  15. package/dist/auth/useMcpOAuthConsent.d.ts.map +1 -0
  16. package/dist/auth/useMcpOAuthConsent.js +133 -0
  17. package/dist/auth/useMcpOAuthConsent.js.map +1 -0
  18. package/dist/codegen/discoverOperations.test.d.ts +2 -0
  19. package/dist/codegen/discoverOperations.test.d.ts.map +1 -0
  20. package/dist/codegen/discoverOperations.test.js +66 -0
  21. package/dist/codegen/discoverOperations.test.js.map +1 -0
  22. package/dist/devMcpRegistry.d.ts.map +1 -1
  23. package/dist/devMcpRegistry.isolated.js +6 -0
  24. package/dist/devMcpRegistry.isolated.js.map +1 -1
  25. package/dist/devMcpRegistry.js +3 -1
  26. package/dist/devMcpRegistry.js.map +1 -1
  27. package/dist/isolated/TerrenoLoginScreen.isolated.js +59 -0
  28. package/dist/isolated/TerrenoLoginScreen.isolated.js.map +1 -1
  29. package/dist/isolated/TerrenoOAuthConsentScreen.isolated.d.ts +2 -0
  30. package/dist/isolated/TerrenoOAuthConsentScreen.isolated.d.ts.map +1 -0
  31. package/dist/isolated/TerrenoOAuthConsentScreen.isolated.js +532 -0
  32. package/dist/isolated/TerrenoOAuthConsentScreen.isolated.js.map +1 -0
  33. package/dist/isolated/useLoginController.isolated.js +94 -0
  34. package/dist/isolated/useLoginController.isolated.js.map +1 -1
  35. package/dist/isolated/useMcpOAuthConsent.isolated.d.ts +2 -0
  36. package/dist/isolated/useMcpOAuthConsent.isolated.d.ts.map +1 -0
  37. package/dist/isolated/useMcpOAuthConsent.isolated.js +273 -0
  38. package/dist/isolated/useMcpOAuthConsent.isolated.js.map +1 -0
  39. package/package.json +4 -4
  40. package/src/auth/TerrenoOAuthConsentScreen.tsx +365 -0
  41. package/src/auth/auth.ts +2 -0
  42. package/src/auth/useLoginController.ts +47 -3
  43. package/src/auth/useMcpOAuthConsent.ts +242 -0
  44. package/src/codegen/discoverOperations.test.ts +69 -0
  45. package/src/devMcpRegistry.isolated.ts +6 -0
  46. package/src/devMcpRegistry.ts +3 -1
  47. package/src/isolated/TerrenoLoginScreen.isolated.tsx +93 -0
  48. package/src/isolated/TerrenoOAuthConsentScreen.isolated.tsx +637 -0
  49. package/src/isolated/useLoginController.isolated.ts +109 -0
  50. package/src/isolated/useMcpOAuthConsent.isolated.ts +330 -0
@@ -0,0 +1,365 @@
1
+ /**
2
+ * A drop-in MCP OAuth consent route: `TerrenoLoginScreen` inline while signed out, then the
3
+ * consent card for the pending authorization request, driven by `useMcpOAuthConsent`.
4
+ */
5
+ import {Box, Button, Card, CheckBox, Heading, Spinner, Text} from "@terreno/ui";
6
+ import {type FC, type ReactNode, useCallback} from "react";
7
+ import {Pressable} from "react-native";
8
+
9
+ import {IsWeb} from "./platform";
10
+ import {useSession} from "./SessionProvider";
11
+ import {TerrenoLoginScreen, type TerrenoLoginScreenProps} from "./TerrenoLoginScreen";
12
+ import {
13
+ type McpOAuthConsentErrorKind,
14
+ type McpOAuthConsentGrant,
15
+ useMcpOAuthConsent,
16
+ } from "./useMcpOAuthConsent";
17
+
18
+ /** Title and message the consent screen shows for each error kind. */
19
+ export const MCP_OAUTH_CONSENT_ERROR_COPY: Readonly<
20
+ Record<McpOAuthConsentErrorKind, {title: string; message: string}>
21
+ > = {
22
+ decided: {
23
+ message:
24
+ "This request was already approved or denied. Start the connection again from your app.",
25
+ title: "Request already decided",
26
+ },
27
+ expired: {
28
+ message: "Authorization requests expire after a few minutes. Start the connection again.",
29
+ title: "Request expired",
30
+ },
31
+ missingRequest: {
32
+ message: "This link has no authorization request. Start the connection again from your app.",
33
+ title: "Missing authorization request",
34
+ },
35
+ notFound: {
36
+ message: "This authorization request does not exist. Check the link or start again.",
37
+ title: "Request not found",
38
+ },
39
+ signedOut: {
40
+ message: "Your session ended, or this browser cannot decide this request. Sign in again.",
41
+ title: "Sign in required",
42
+ },
43
+ unknown: {
44
+ message: "Something went wrong loading or deciding this request. Try again.",
45
+ title: "Could not complete the request",
46
+ },
47
+ };
48
+
49
+ const UNNAMED_CLIENT = "An unnamed MCP client";
50
+
51
+ /** Label and description that replace the server's copy for one grant scope. */
52
+ export interface McpOAuthConsentGrantLabel {
53
+ label: string;
54
+ description?: string;
55
+ }
56
+
57
+ export interface TerrenoOAuthConsentScreenProps {
58
+ /**
59
+ * The pending authorization request id. Defaults to the `request` query parameter of the
60
+ * current web URL.
61
+ */
62
+ requestId?: string;
63
+ /**
64
+ * Everything `TerrenoLoginScreen` needs while signed out (`client`, `rememberedAccounts`,
65
+ * `methods`, `title`, `logo`, `providerLabels`, ...). The screen supplies `onSignedIn`, which
66
+ * refreshes the session so the consent card renders in place. `callbackURL` defaults to the
67
+ * current web URL, so social sign-in returns here with `?request=` intact.
68
+ */
69
+ loginProps: Omit<TerrenoLoginScreenProps, "onSignedIn">;
70
+ /** Heading above the consent card. */
71
+ title?: string;
72
+ /** Logo shown above the consent card. */
73
+ logo?: ReactNode;
74
+ /** Overrides the server's label and description per grant scope. */
75
+ grantLabels?: Record<string, McpOAuthConsentGrantLabel>;
76
+ /**
77
+ * Follows the URL the server returns after approve or deny. Defaults to
78
+ * `window.location.assign` on web and `Linking.openURL` on native.
79
+ */
80
+ onRedirect?: (url: string) => void;
81
+ /**
82
+ * Prefix for every test id: `-screen`, `-client-name`, `-grant-${scope}`, `-approve-button`,
83
+ * `-deny-button`, `-error`, `-signed-in-as`.
84
+ * @default "oauth-consent"
85
+ */
86
+ testID?: string;
87
+ }
88
+
89
+ const readWebRequestId = (): string | undefined => {
90
+ if (!IsWeb || typeof window === "undefined") {
91
+ return undefined;
92
+ }
93
+ const search = window.location?.search ?? "";
94
+ return new URLSearchParams(search).get("request") ?? undefined;
95
+ };
96
+
97
+ const readWebHref = (): string | undefined => {
98
+ if (!IsWeb || typeof window === "undefined") {
99
+ return undefined;
100
+ }
101
+ return window.location?.href;
102
+ };
103
+
104
+ const ConsentFrame: FC<{children: ReactNode; testID: string}> = ({children, testID}) => (
105
+ <Box
106
+ alignItems="center"
107
+ color="base"
108
+ flex="grow"
109
+ justifyContent="center"
110
+ padding={6}
111
+ testID={`${testID}-screen`}
112
+ >
113
+ <Box gap={5} maxWidth={480} width="100%">
114
+ {children}
115
+ </Box>
116
+ </Box>
117
+ );
118
+
119
+ interface GrantRowProps {
120
+ grant: McpOAuthConsentGrant;
121
+ override?: McpOAuthConsentGrantLabel;
122
+ isSelected: boolean;
123
+ isDisabled: boolean;
124
+ onToggle: (scope: string) => void;
125
+ testID: string;
126
+ }
127
+
128
+ const GrantRow: FC<GrantRowProps> = ({
129
+ grant,
130
+ override,
131
+ isSelected,
132
+ isDisabled,
133
+ onToggle,
134
+ testID,
135
+ }) => {
136
+ const label = override?.label ?? grant.label;
137
+ const description = override ? override.description : (grant.description ?? undefined);
138
+
139
+ const handleClick = useCallback((): void => {
140
+ if (isDisabled) {
141
+ return;
142
+ }
143
+ onToggle(grant.scope);
144
+ }, [grant.scope, isDisabled, onToggle]);
145
+
146
+ // A react-native Pressable, not a clickable Box: Box renames its pressable to `${testID}-clickable`,
147
+ // and the checkbox element itself must carry the documented `${testID}-grant-${scope}` id.
148
+ return (
149
+ <Pressable
150
+ accessibilityHint={isSelected ? "Removes this access" : "Grants this access"}
151
+ accessibilityLabel={label}
152
+ accessibilityRole="checkbox"
153
+ accessibilityState={{checked: isSelected, disabled: isDisabled}}
154
+ aria-checked={isSelected}
155
+ disabled={isDisabled}
156
+ onPress={handleClick}
157
+ testID={`${testID}-grant-${grant.scope}`}
158
+ >
159
+ <Box alignItems="start" direction="row" gap={3}>
160
+ <CheckBox selected={isSelected} />
161
+ <Box flex="shrink" gap={1}>
162
+ <Text bold>{label}</Text>
163
+ {description ? <Text color="secondaryDark">{description}</Text> : null}
164
+ </Box>
165
+ </Box>
166
+ </Pressable>
167
+ );
168
+ };
169
+
170
+ interface ConsentCardProps {
171
+ requestId: string | undefined;
172
+ title?: string;
173
+ logo?: ReactNode;
174
+ grantLabels?: Record<string, McpOAuthConsentGrantLabel>;
175
+ onRedirect?: (url: string) => void;
176
+ email: string | undefined;
177
+ testID: string;
178
+ }
179
+
180
+ const ConsentCard: FC<ConsentCardProps> = ({
181
+ requestId,
182
+ title,
183
+ logo,
184
+ grantLabels,
185
+ onRedirect,
186
+ email,
187
+ testID,
188
+ }) => {
189
+ const consent = useMcpOAuthConsent({onRedirect, requestId});
190
+ const {approve, deny, request, selectedScopes, state, toggleScope} = consent;
191
+
192
+ const handleApprove = useCallback(async (): Promise<void> => {
193
+ await approve();
194
+ }, [approve]);
195
+
196
+ const handleDeny = useCallback(async (): Promise<void> => {
197
+ await deny();
198
+ }, [deny]);
199
+
200
+ if (state === "error") {
201
+ const copy = MCP_OAUTH_CONSENT_ERROR_COPY[consent.errorKind ?? "unknown"];
202
+ return (
203
+ <ConsentFrame testID={testID}>
204
+ {logo}
205
+ <Box gap={3} testID={`${testID}-error`}>
206
+ <Heading size="lg">{copy.title}</Heading>
207
+ <Text color="secondaryDark">{copy.message}</Text>
208
+ </Box>
209
+ </ConsentFrame>
210
+ );
211
+ }
212
+
213
+ if (!request) {
214
+ return (
215
+ <ConsentFrame testID={testID}>
216
+ <Box alignItems="center" padding={6} testID={`${testID}-loading`}>
217
+ <Spinner />
218
+ </Box>
219
+ </ConsentFrame>
220
+ );
221
+ }
222
+
223
+ const isSubmitting = state === "submitting";
224
+
225
+ return (
226
+ <ConsentFrame testID={testID}>
227
+ {logo}
228
+ {title ? <Heading size="md">{title}</Heading> : null}
229
+ <Box gap={2}>
230
+ <Heading size="lg" testID={`${testID}-client-name`}>
231
+ {request.clientName ?? UNNAMED_CLIENT}
232
+ </Heading>
233
+ <Text color="secondaryDark">wants to access your account through MCP.</Text>
234
+ </Box>
235
+
236
+ <Card padding={4}>
237
+ <Box gap={2} testID={`${testID}-redirect-warning`}>
238
+ <Text>Only approve if you started this from</Text>
239
+ <Text bold size="lg" testID={`${testID}-redirect-host`}>
240
+ {request.redirectHost}
241
+ </Text>
242
+ <Text color="secondaryDark">
243
+ Approving sends an authorization code there. If you did not just connect an app on that
244
+ site, deny this request.
245
+ </Text>
246
+ </Box>
247
+ </Card>
248
+
249
+ <Box gap={3} testID={`${testID}-grants`}>
250
+ <Text bold>Requested access</Text>
251
+ {request.grants.length > 0 ? (
252
+ request.grants.map((grant) => (
253
+ <GrantRow
254
+ grant={grant}
255
+ isDisabled={isSubmitting}
256
+ isSelected={selectedScopes.includes(grant.scope)}
257
+ key={grant.scope}
258
+ onToggle={toggleScope}
259
+ override={grantLabels?.[grant.scope]}
260
+ testID={testID}
261
+ />
262
+ ))
263
+ ) : (
264
+ <Text color="secondaryDark">The server's default MCP access</Text>
265
+ )}
266
+ </Box>
267
+
268
+ {/* Text links an email into nested spans that inherit its testID, so the id sits on a Box. */}
269
+ <Box testID={`${testID}-signed-in-as`}>
270
+ <Text color="secondaryDark">Signed in as {email ?? "your account"}</Text>
271
+ </Box>
272
+
273
+ <Box direction="row" gap={3}>
274
+ <Box flex="grow">
275
+ <Button
276
+ disabled={isSubmitting}
277
+ fullWidth
278
+ onClick={handleDeny}
279
+ testID={`${testID}-deny-button`}
280
+ text="Deny"
281
+ variant="secondary"
282
+ />
283
+ </Box>
284
+ <Box flex="grow">
285
+ <Button
286
+ disabled={isSubmitting || selectedScopes.length === 0}
287
+ fullWidth
288
+ loading={isSubmitting}
289
+ onClick={handleApprove}
290
+ testID={`${testID}-approve-button`}
291
+ text="Approve"
292
+ variant="primary"
293
+ />
294
+ </Box>
295
+ </Box>
296
+ </ConsentFrame>
297
+ );
298
+ };
299
+
300
+ /**
301
+ * One screen for the whole MCP OAuth consent route. Signed out, it shows `TerrenoLoginScreen`
302
+ * with `loginProps`; signing in refreshes the session and the consent card replaces it without
303
+ * navigation. Signed in, it shows the client, the redirect host, a checkbox per requested grant
304
+ * (all checked; the user may narrow them), the signed-in email, and Approve and Deny. Must render
305
+ * inside `SessionProvider` and an `ApiClientProvider` whose client sends the user's credentials.
306
+ *
307
+ * @example
308
+ * ```tsx
309
+ * <TerrenoOAuthConsentScreen
310
+ * loginProps={{
311
+ * client: authClient,
312
+ * methods: {providers: ["google"]},
313
+ * rememberedAccounts,
314
+ * title: "Sign in to connect",
315
+ * }}
316
+ * />
317
+ * ```
318
+ */
319
+ export const TerrenoOAuthConsentScreen: FC<TerrenoOAuthConsentScreenProps> = ({
320
+ requestId,
321
+ loginProps,
322
+ title,
323
+ logo,
324
+ grantLabels,
325
+ onRedirect,
326
+ testID = "oauth-consent",
327
+ }) => {
328
+ const {isLoading, refresh, user, userId} = useSession();
329
+
330
+ const handleSignedIn = useCallback(async (): Promise<void> => {
331
+ await refresh();
332
+ }, [refresh]);
333
+
334
+ if (isLoading) {
335
+ return (
336
+ <ConsentFrame testID={testID}>
337
+ <Box alignItems="center" padding={6} testID={`${testID}-loading`}>
338
+ <Spinner />
339
+ </Box>
340
+ </ConsentFrame>
341
+ );
342
+ }
343
+
344
+ if (!userId) {
345
+ return (
346
+ <TerrenoLoginScreen
347
+ {...loginProps}
348
+ callbackURL={loginProps.callbackURL ?? readWebHref()}
349
+ onSignedIn={handleSignedIn}
350
+ />
351
+ );
352
+ }
353
+
354
+ return (
355
+ <ConsentCard
356
+ email={user?.email ?? undefined}
357
+ grantLabels={grantLabels}
358
+ logo={logo}
359
+ onRedirect={onRedirect}
360
+ requestId={requestId ?? readWebRequestId()}
361
+ testID={testID}
362
+ title={title}
363
+ />
364
+ );
365
+ };
package/src/auth/auth.ts CHANGED
@@ -95,6 +95,7 @@ export {
95
95
  } from "./session";
96
96
  export * from "./TerrenoAccountSecurityScreen";
97
97
  export * from "./TerrenoLoginScreen";
98
+ export * from "./TerrenoOAuthConsentScreen";
98
99
  export {
99
100
  AUTH_TOKEN_KEY,
100
101
  createJwtTokenStorage,
@@ -115,3 +116,4 @@ export * from "./useAccountSecurity";
115
116
  export * from "./useAuthMethods";
116
117
  export {type UseJwtAuthResult, useJwtAuth} from "./useJwtAuth";
117
118
  export * from "./useLoginController";
119
+ export * from "./useMcpOAuthConsent";
@@ -123,6 +123,23 @@ export interface LoginTwoFactorRequiredEvent {
123
123
  */
124
124
  export type LoginControllerClientInput = LoginControllerClient | BetterAuthClient;
125
125
 
126
+ /**
127
+ * Limits the sign-in methods the login screen shows to a subset of what the server offers. It
128
+ * never turns on a method the server has off: enable providers in server config (`googleOAuth`,
129
+ * `appleOAuth`, and so on), then pick which of them to show here.
130
+ */
131
+ export interface LoginMethodsFilter {
132
+ /**
133
+ * Provider ids to show, such as `["google"]`. The server's order is kept and ids the server
134
+ * does not offer are ignored. `[]` hides every social button; leave unset to show them all.
135
+ */
136
+ providers?: string[];
137
+ /** Pass `false` to hide the email and password form (and the forgot-password link). */
138
+ emailPassword?: boolean;
139
+ /** Pass `false` to hide the passkey button and passkey autofill. */
140
+ passkey?: boolean;
141
+ }
142
+
126
143
  export interface UseLoginControllerOptions {
127
144
  /** A client from `createBetterAuthClient`, ideally with the features the server enables. */
128
145
  client: LoginControllerClientInput;
@@ -184,6 +201,12 @@ export interface UseLoginControllerOptions {
184
201
  getBearerToken?: () => string | null;
185
202
  /** The email the form starts with. */
186
203
  initialEmail?: string;
204
+ /**
205
+ * Shows only a subset of the server's sign-in methods, for example on a consent route. Leave
206
+ * unset to show every method the server offers. Remembered-account cards for a hidden method
207
+ * do not sign in with it.
208
+ */
209
+ methods?: LoginMethodsFilter;
187
210
  }
188
211
 
189
212
  /**
@@ -398,9 +421,21 @@ export const useLoginController = ({
398
421
  webAuth,
399
422
  getBearerToken,
400
423
  initialEmail,
424
+ methods: methodsFilter,
401
425
  }: UseLoginControllerOptions): LoginController => {
402
426
  const client = clientInput as LoginControllerClient;
403
427
  const {methods} = useAuthMethods(client);
428
+ // Keyed on the filter's contents so an inline object does not rerun effects every render.
429
+ const allowedProvidersKey = methodsFilter?.providers
430
+ ? JSON.stringify(methodsFilter.providers)
431
+ : undefined;
432
+ const allowedProviders = useMemo(
433
+ (): string[] | undefined =>
434
+ allowedProvidersKey === undefined ? undefined : (JSON.parse(allowedProvidersKey) as string[]),
435
+ [allowedProvidersKey]
436
+ );
437
+ const isEmailPasswordAllowed = methodsFilter?.emailPassword !== false;
438
+ const isPasskeyAllowed = methodsFilter?.passkey !== false;
404
439
  const remembered = useRememberedAccounts(rememberedAccounts);
405
440
 
406
441
  const [step, setStep] = useState<LoginControllerStep>("checking");
@@ -708,7 +743,9 @@ export const useLoginController = ({
708
743
  // Starts again each time the screen returns to the login step. There is no abort on cleanup:
709
744
  // the ceremony's abort service lives in @simplewebauthn/browser, which rtk does not depend on;
710
745
  // the next ceremony replaces it, and a cancelled run never finishes a sign-in.
711
- const isPasskeyOn = Boolean(methods?.passkey && client.signIn.passkey && IsWeb);
746
+ const isPasskeyOn = Boolean(
747
+ isPasskeyAllowed && methods?.passkey && client.signIn.passkey && IsWeb
748
+ );
712
749
  useEffect(() => {
713
750
  if (step !== "login" || !isPasskeyOn || !passkeyAutofill) {
714
751
  return;
@@ -779,9 +816,16 @@ export const useLoginController = ({
779
816
  setStep("login");
780
817
  }, [initialEmail]);
781
818
 
782
- const offeredProviders = methods?.providers;
819
+ const serverProviders = methods?.providers;
820
+ const offeredProviders = useMemo(
821
+ (): string[] | undefined =>
822
+ allowedProviders
823
+ ? serverProviders?.filter((provider) => allowedProviders.includes(provider))
824
+ : serverProviders,
825
+ [allowedProviders, serverProviders]
826
+ );
783
827
  // True while the methods load, so the form does not flash away for servers that offer it.
784
- const isEmailPasswordEnabled = methods?.emailPassword !== false;
828
+ const isEmailPasswordEnabled = isEmailPasswordAllowed && methods?.emailPassword !== false;
785
829
  const nameMethod = useCallback(
786
830
  (method: string | undefined): string | undefined => {
787
831
  if (!method) {
@@ -0,0 +1,242 @@
1
+ /**
2
+ * Drives the MCP OAuth consent screen: loads a pending authorization request, tracks which of its
3
+ * grants the user keeps selected, and approves or denies it through the app's request client
4
+ * (`ApiClientProvider`). The server answers each decision with the URL that hands the result back
5
+ * to the MCP client, which `onRedirect` follows.
6
+ */
7
+ import {useCallback, useEffect, useRef, useState} from "react";
8
+ import {Linking} from "react-native";
9
+
10
+ import {isApiError} from "../api/apiError";
11
+ import {useApiClient} from "../react/apiHooks";
12
+ import {IsWeb} from "./platform";
13
+
14
+ /** Access level a grant gives. Write implies read. */
15
+ export type McpOAuthConsentGrantAccess = "read" | "write";
16
+
17
+ /** One grant the MCP client asked for, as the consent screen shows it. */
18
+ export interface McpOAuthConsentGrant {
19
+ /** OAuth scope value the grant stands for. */
20
+ scope: string;
21
+ /** Short name shown next to the grant's checkbox. */
22
+ label: string;
23
+ /** Longer explanation shown under the label, or `null` when the app gave none. */
24
+ description: string | null;
25
+ access: McpOAuthConsentGrantAccess;
26
+ }
27
+
28
+ /** A pending authorization request, as returned by `GET /oauth/authorize/:request`. */
29
+ export interface McpOAuthConsentRequest {
30
+ requestId: string;
31
+ clientId: string;
32
+ /** Name the client registered with, or `null` when it gave none. */
33
+ clientName: string | null;
34
+ /** Host the authorization code is sent to, so the user can tell where access goes. */
35
+ redirectHost: string;
36
+ redirectUri: string;
37
+ /** The requested scopes, in requested order. A scope without a configured grant has its own name as the label and `access: "write"`. */
38
+ grants: McpOAuthConsentGrant[];
39
+ /** The raw requested scope string, or `null` when the client asked for none. */
40
+ scope: string | null;
41
+ resource: string;
42
+ expiresAt: string;
43
+ }
44
+
45
+ /**
46
+ * Why consent cannot continue: no `request` in the URL (`missingRequest`), no such request
47
+ * (`notFound`, 404), already approved or denied (`decided`, 409), expired (`expired`, 400),
48
+ * not signed in (`signedOut`, 401), or anything else (`unknown`).
49
+ */
50
+ export type McpOAuthConsentErrorKind =
51
+ | "missingRequest"
52
+ | "notFound"
53
+ | "decided"
54
+ | "expired"
55
+ | "signedOut"
56
+ | "unknown";
57
+
58
+ export type McpOAuthConsentState = "loading" | "ready" | "submitting" | "error";
59
+
60
+ export interface UseMcpOAuthConsentOptions {
61
+ /** The `request` query parameter from the consent URL. */
62
+ requestId: string | undefined;
63
+ /**
64
+ * Follows the URL the server returns after approve or deny. Defaults to
65
+ * `window.location.assign` on web and `Linking.openURL` on native.
66
+ */
67
+ onRedirect?: (url: string) => void;
68
+ }
69
+
70
+ export interface UseMcpOAuthConsentResult {
71
+ state: McpOAuthConsentState;
72
+ /** The loaded request; present once `state` has been `ready`. */
73
+ request?: McpOAuthConsentRequest;
74
+ /** Scopes the user keeps selected, in grant order. Every grant starts selected. */
75
+ selectedScopes: string[];
76
+ /** Selects or clears one grant's scope. */
77
+ toggleScope: (scope: string) => void;
78
+ /** Approves the selected scopes and redirects. Does nothing when none is selected. */
79
+ approve: () => Promise<void>;
80
+ /** Denies the request and redirects. */
81
+ deny: () => Promise<void>;
82
+ /** Set when `state` is `error`. */
83
+ errorKind?: McpOAuthConsentErrorKind;
84
+ }
85
+
86
+ interface ConsentDecision {
87
+ redirectUrl: string;
88
+ }
89
+
90
+ interface ConsentSnapshot {
91
+ requestId: string | undefined;
92
+ state: McpOAuthConsentState;
93
+ request?: McpOAuthConsentRequest;
94
+ selectedScopes: string[];
95
+ errorKind?: McpOAuthConsentErrorKind;
96
+ }
97
+
98
+ const ERROR_KIND_BY_STATUS: Readonly<Record<number, McpOAuthConsentErrorKind>> = {
99
+ 400: "expired",
100
+ 401: "signedOut",
101
+ 404: "notFound",
102
+ 409: "decided",
103
+ };
104
+
105
+ const toErrorKind = (error: unknown): McpOAuthConsentErrorKind => {
106
+ if (!isApiError(error)) {
107
+ return "unknown";
108
+ }
109
+ return ERROR_KIND_BY_STATUS[error.status] ?? "unknown";
110
+ };
111
+
112
+ const defaultRedirect = (url: string): void => {
113
+ if (IsWeb) {
114
+ window.location.assign(url);
115
+ return;
116
+ }
117
+ Linking.openURL(url).catch((error: unknown) => {
118
+ console.warn("[useMcpOAuthConsent] Could not open the MCP OAuth redirect", error);
119
+ });
120
+ };
121
+
122
+ const requestPath = (requestId: string): string =>
123
+ `/oauth/authorize/${encodeURIComponent(requestId)}`;
124
+
125
+ const initialSnapshot = (requestId: string | undefined): ConsentSnapshot =>
126
+ requestId
127
+ ? {requestId, selectedScopes: [], state: "loading"}
128
+ : {errorKind: "missingRequest", requestId, selectedScopes: [], state: "error"};
129
+
130
+ /**
131
+ * Loads the MCP OAuth consent request `requestId` and approves or denies it. Must render inside an
132
+ * `ApiClientProvider` whose client sends the signed-in user's credentials.
133
+ */
134
+ export const useMcpOAuthConsent = ({
135
+ requestId,
136
+ onRedirect,
137
+ }: UseMcpOAuthConsentOptions): UseMcpOAuthConsentResult => {
138
+ const client = useApiClient();
139
+ const [snapshot, setSnapshot] = useState<ConsentSnapshot>(() => initialSnapshot(requestId));
140
+ // Guards against a second decision before the `submitting` render lands (double clicks).
141
+ const isDecidingRef = useRef(false);
142
+
143
+ // Reset when the consent URL names a different request, so stale grants never show.
144
+ const current = snapshot.requestId === requestId ? snapshot : initialSnapshot(requestId);
145
+ if (current !== snapshot) {
146
+ setSnapshot(current);
147
+ }
148
+
149
+ // Load the pending request whenever the consent URL names one.
150
+ useEffect(() => {
151
+ if (!requestId) {
152
+ return;
153
+ }
154
+ let isCancelled = false;
155
+ client.request<McpOAuthConsentRequest>({url: requestPath(requestId)}).then(
156
+ (request) => {
157
+ if (isCancelled) {
158
+ return;
159
+ }
160
+ setSnapshot({
161
+ request,
162
+ requestId,
163
+ selectedScopes: request.grants.map((grant) => grant.scope),
164
+ state: "ready",
165
+ });
166
+ },
167
+ (error: unknown) => {
168
+ if (isCancelled) {
169
+ return;
170
+ }
171
+ setSnapshot({errorKind: toErrorKind(error), requestId, selectedScopes: [], state: "error"});
172
+ }
173
+ );
174
+ return (): void => {
175
+ isCancelled = true;
176
+ };
177
+ }, [client, requestId]);
178
+
179
+ const toggleScope = useCallback((scope: string): void => {
180
+ setSnapshot((previous) => {
181
+ if (!previous.request) {
182
+ return previous;
183
+ }
184
+ const isSelected = previous.selectedScopes.includes(scope);
185
+ const selectedScopes = previous.request.grants
186
+ .map((grant) => grant.scope)
187
+ .filter((grantScope) =>
188
+ grantScope === scope ? !isSelected : previous.selectedScopes.includes(grantScope)
189
+ );
190
+ return {...previous, selectedScopes};
191
+ });
192
+ }, []);
193
+
194
+ const decide = useCallback(
195
+ async (decision: "approve" | "deny", body?: Record<string, unknown>): Promise<void> => {
196
+ if (!requestId || isDecidingRef.current) {
197
+ return;
198
+ }
199
+ isDecidingRef.current = true;
200
+ setSnapshot((previous) => ({...previous, state: "submitting"}));
201
+ let result: ConsentDecision;
202
+ try {
203
+ result = await client.request<ConsentDecision>({
204
+ body,
205
+ method: "POST",
206
+ url: `${requestPath(requestId)}/${decision}`,
207
+ });
208
+ } catch (error: unknown) {
209
+ isDecidingRef.current = false;
210
+ setSnapshot((previous) => ({...previous, errorKind: toErrorKind(error), state: "error"}));
211
+ return;
212
+ }
213
+ // Stay in `submitting` while the browser leaves, so the buttons cannot submit twice.
214
+ (onRedirect ?? defaultRedirect)(result.redirectUrl);
215
+ },
216
+ [client, onRedirect, requestId]
217
+ );
218
+
219
+ const approve = useCallback(async (): Promise<void> => {
220
+ if (current.state !== "ready" || current.selectedScopes.length === 0) {
221
+ return;
222
+ }
223
+ await decide("approve", {scope: current.selectedScopes.join(" ")});
224
+ }, [current.selectedScopes, current.state, decide]);
225
+
226
+ const deny = useCallback(async (): Promise<void> => {
227
+ if (current.state !== "ready") {
228
+ return;
229
+ }
230
+ await decide("deny");
231
+ }, [current.state, decide]);
232
+
233
+ return {
234
+ approve,
235
+ deny,
236
+ errorKind: current.errorKind,
237
+ request: current.request,
238
+ selectedScopes: current.selectedScopes,
239
+ state: current.state,
240
+ toggleScope,
241
+ };
242
+ };