@teamhanko/hanko-frontend-sdk 3.0.0 → 3.2.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.
@@ -1,13 +1,45 @@
1
1
  import { ContinueWithLoginIdentifierInputs, EmailCreateInputs, EmailDeleteInputs, EmailSetPrimaryInputs, EmailVerifyInputs, ExchangeTokenInputs, PasskeyCredentialDeleteInputs, PasskeyCredentialRenameInputs, PasswordRecoveryInputs, PasswordInputs, PatchMetadataInputs, RegisterClientCapabilitiesInputs, RegisterLoginIdentifierInputs, RegisterPasswordInputs, ThirdpartyOauthInputs, UsernameSetInputs, VerifyPasscodeInputs, WebauthnVerifyAssertionResponseInputs, WebauthnVerifyAttestationResponseInputs, SessionDeleteInputs, OTPCodeInputs, SecurityKeyDeleteInputs, RememberMeInputs, DisconnectThirdpartyInputs } from "./input";
2
+ /**
3
+ * Represents a single action that can be run from a {@link State}. `action` and `href` identify
4
+ * the action for the backend, `inputs` describes the input fields the action accepts (see
5
+ * {@link State#actions} for how these map to a concrete state), and `description` is a
6
+ * human-readable summary of what running the action does.
7
+ * @template TInputs - The shape of the inputs this action accepts, or `null` if it accepts none.
8
+ * @interface
9
+ * @category SDK
10
+ * @subcategory Flow Actions
11
+ * @property {string} action - The unique name of the action within the current flow.
12
+ * @property {string} href - The URL the action is submitted to when run.
13
+ * @property {TInputs} inputs - The input fields accepted by the action.
14
+ * @property {string} description - A human-readable description of the action.
15
+ */
2
16
  export interface Action<TInputs> {
3
17
  action: string;
4
18
  href: string;
5
19
  inputs: TInputs;
6
20
  description: string;
7
21
  }
22
+ /**
23
+ * Actions available in the `preflight` state, run once at the start of a flow to register client capabilities.
24
+ * @interface
25
+ * @category SDK
26
+ * @subcategory Flow Actions
27
+ * @property {Action<RegisterClientCapabilitiesInputs>} register_client_capabilities - Reports client capabilities (e.g. WebAuthn support) to the backend.
28
+ */
8
29
  export interface PreflightActions {
9
30
  readonly register_client_capabilities: Action<RegisterClientCapabilitiesInputs>;
10
31
  }
32
+ /**
33
+ * Actions available in the `login_init` state, the entry point of a login flow.
34
+ * @interface
35
+ * @category SDK
36
+ * @subcategory Flow Actions
37
+ * @property {Action<ContinueWithLoginIdentifierInputs>} [continue_with_login_identifier] - Submits an identifier (e.g. email or username) to continue the login.
38
+ * @property {Action<null>} [webauthn_generate_request_options] - Requests WebAuthn assertion options to attempt a passkey login.
39
+ * @property {Action<WebauthnVerifyAssertionResponseInputs>} [webauthn_verify_assertion_response] - Submits the WebAuthn assertion response for verification.
40
+ * @property {Action<ThirdpartyOauthInputs>} [thirdparty_oauth] - Starts a third-party OAuth login.
41
+ * @property {Action<RememberMeInputs>} [remember_me] - Sets whether the device should be remembered for future logins.
42
+ */
11
43
  export interface LoginInitActions {
12
44
  readonly continue_with_login_identifier?: Action<ContinueWithLoginIdentifierInputs>;
13
45
  readonly webauthn_generate_request_options?: Action<null>;
@@ -15,6 +47,35 @@ export interface LoginInitActions {
15
47
  readonly thirdparty_oauth?: Action<ThirdpartyOauthInputs>;
16
48
  readonly remember_me?: Action<RememberMeInputs>;
17
49
  }
50
+ /**
51
+ * Actions available in the `profile_init` state, the user's account/profile management screen.
52
+ * @interface
53
+ * @category SDK
54
+ * @subcategory Flow Actions
55
+ * @property {Action<null>} [account_delete] - Deletes the current user's account.
56
+ * @property {Action<null>} [continue_to_otp_secret_creation] - Continues to setting up an authenticator app (TOTP) for MFA.
57
+ * @property {Action<EmailCreateInputs>} [email_create] - Adds a new email address to the account.
58
+ * @property {Action<EmailDeleteInputs>} [email_delete] - Removes an email address from the account.
59
+ * @property {Action<EmailVerifyInputs>} [email_verify] - Requests verification of an unverified email address.
60
+ * @property {Action<EmailSetPrimaryInputs>} [email_set_primary] - Sets an email address as the primary one.
61
+ * @property {Action<null>} [otp_secret_delete] - Removes the configured authenticator app (TOTP) secret.
62
+ * @property {Action<PasswordInputs>} [password_create] - Sets a password for the account.
63
+ * @property {Action<PasswordInputs>} [password_update] - Updates the account's existing password.
64
+ * @property {Action<null>} [password_delete] - Removes the account's password.
65
+ * @property {Action<PatchMetadataInputs>} patch_metadata - Updates the user's public/unsafe metadata.
66
+ * @property {Action<null>} [security_key_create] - Starts registering a new hardware security key.
67
+ * @property {Action<SecurityKeyDeleteInputs>} [security_key_delete] - Removes a registered security key.
68
+ * @property {Action<UsernameSetInputs>} [username_create] - Sets a username for the account.
69
+ * @property {Action<null>} [username_delete] - Removes the account's username.
70
+ * @property {Action<UsernameSetInputs>} [username_update] - Updates the account's existing username.
71
+ * @property {Action<null>} [webauthn_credential_create] - Starts registering a new passkey.
72
+ * @property {Action<PasskeyCredentialRenameInputs>} [webauthn_credential_rename] - Renames a registered passkey.
73
+ * @property {Action<PasskeyCredentialDeleteInputs>} [webauthn_credential_delete] - Removes a registered passkey.
74
+ * @property {Action<WebauthnVerifyAttestationResponseInputs>} [webauthn_verify_attestation_response] - Submits the WebAuthn attestation response to complete a passkey/security key registration.
75
+ * @property {Action<SessionDeleteInputs>} [session_delete] - Revokes one of the user's active sessions.
76
+ * @property {Action<ThirdpartyOauthInputs>} [connect_thirdparty_oauth_provider] - Links a third-party OAuth provider to the account.
77
+ * @property {Action<DisconnectThirdpartyInputs>} [disconnect_thirdparty_oauth_provider] - Unlinks a third-party OAuth provider from the account.
78
+ */
18
79
  export interface ProfileInitActions {
19
80
  readonly account_delete?: Action<null>;
20
81
  readonly continue_to_otp_secret_creation?: Action<null>;
@@ -40,90 +101,255 @@ export interface ProfileInitActions {
40
101
  readonly connect_thirdparty_oauth_provider?: Action<ThirdpartyOauthInputs>;
41
102
  readonly disconnect_thirdparty_oauth_provider?: Action<DisconnectThirdpartyInputs>;
42
103
  }
104
+ /**
105
+ * Actions available in the `login_method_chooser` state, letting the user pick a login method.
106
+ * @interface
107
+ * @category SDK
108
+ * @subcategory Flow Actions
109
+ * @property {Action<null>} [continue_to_password_login] - Switches to password-based login.
110
+ * @property {Action<null>} [continue_to_passcode_confirmation] - Switches to passcode (one-time code) based login.
111
+ * @property {Action<null>} [webauthn_generate_request_options] - Requests WebAuthn assertion options to attempt a passkey login.
112
+ * @property {Action<null>} back - Returns to the previous state.
113
+ */
43
114
  export interface LoginMethodChooserActions {
44
115
  readonly continue_to_password_login?: Action<null>;
45
116
  readonly continue_to_passcode_confirmation?: Action<null>;
46
117
  readonly webauthn_generate_request_options?: Action<null>;
47
118
  readonly back: Action<null>;
48
119
  }
120
+ /**
121
+ * Actions available in the `login_otp` state, where the user submits a one-time passcode.
122
+ * @interface
123
+ * @category SDK
124
+ * @subcategory Flow Actions
125
+ * @property {Action<OTPCodeInputs>} otp_code_validate - Submits the entered one-time code for validation.
126
+ * @property {Action<null>} [continue_to_login_security_key] - Switches to security-key based login.
127
+ */
49
128
  export interface LoginOTPActions {
50
129
  readonly otp_code_validate: Action<OTPCodeInputs>;
51
130
  readonly continue_to_login_security_key?: Action<null>;
52
131
  }
132
+ /**
133
+ * Actions available in the `login_password` state.
134
+ * @interface
135
+ * @category SDK
136
+ * @subcategory Flow Actions
137
+ * @property {Action<PasswordInputs>} password_login - Submits the entered password for login.
138
+ * @property {Action<null>} [continue_to_passcode_confirmation_recovery] - Starts password recovery via a passcode.
139
+ * @property {Action<null>} continue_to_login_method_chooser - Returns to the login method chooser.
140
+ * @property {Action<null>} back - Returns to the previous state.
141
+ */
53
142
  export interface LoginPasswordActions {
54
143
  readonly password_login: Action<PasswordInputs>;
55
144
  readonly continue_to_passcode_confirmation_recovery?: Action<null>;
56
145
  readonly continue_to_login_method_chooser: Action<null>;
57
146
  readonly back: Action<null>;
58
147
  }
148
+ /**
149
+ * Actions available in the `login_password_recovery` state.
150
+ * @interface
151
+ * @category SDK
152
+ * @subcategory Flow Actions
153
+ * @property {Action<PasswordRecoveryInputs>} password_recovery - Submits a new password to complete password recovery.
154
+ */
59
155
  export interface LoginPasswordRecoveryActions {
60
156
  readonly password_recovery: Action<PasswordRecoveryInputs>;
61
157
  }
158
+ /**
159
+ * Actions available in the `login_passkey` state, while a passkey login ceremony is in progress.
160
+ * @interface
161
+ * @category SDK
162
+ * @subcategory Flow Actions
163
+ * @property {Action<WebauthnVerifyAssertionResponseInputs>} webauthn_verify_assertion_response - Submits the WebAuthn assertion response for verification.
164
+ * @property {Action<null>} back - Returns to the previous state.
165
+ */
62
166
  export interface LoginPasskeyActions {
63
167
  readonly webauthn_verify_assertion_response: Action<WebauthnVerifyAssertionResponseInputs>;
64
168
  readonly back: Action<null>;
65
169
  }
170
+ /**
171
+ * Actions available in the `login_security_key` state, while a security-key login ceremony is in progress.
172
+ * @interface
173
+ * @category SDK
174
+ * @subcategory Flow Actions
175
+ * @property {Action<null>} webauthn_generate_request_options - Requests WebAuthn assertion options for the security key.
176
+ * @property {Action<null>} [continue_to_login_otp] - Switches to one-time-passcode based login.
177
+ */
66
178
  export interface LoginSecurityKeyActions {
67
179
  readonly webauthn_generate_request_options: Action<null>;
68
180
  readonly continue_to_login_otp?: Action<null>;
69
181
  }
182
+ /**
183
+ * Actions available in the `mfa_method_chooser` state, letting the user pick a second factor method.
184
+ * @interface
185
+ * @category SDK
186
+ * @subcategory Flow Actions
187
+ * @property {Action<null>} [continue_to_otp_secret_creation] - Switches to authenticator app (TOTP) setup.
188
+ * @property {Action<null>} [continue_to_security_key_creation] - Switches to security key setup.
189
+ * @property {Action<null>} [skip] - Skips second factor setup, if optional.
190
+ * @property {Action<null>} [back] - Returns to the previous state.
191
+ */
70
192
  export interface MFAMethodChooserActions {
71
193
  readonly continue_to_otp_secret_creation?: Action<null>;
72
194
  readonly continue_to_security_key_creation?: Action<null>;
73
195
  readonly skip?: Action<null>;
74
196
  readonly back?: Action<null>;
75
197
  }
198
+ /**
199
+ * Actions available in the `mfa_otp_secret_creation` state, while setting up an authenticator app (TOTP).
200
+ * @interface
201
+ * @category SDK
202
+ * @subcategory Flow Actions
203
+ * @property {Action<OTPCodeInputs>} otp_code_verify - Submits a code generated from the authenticator app to confirm setup.
204
+ * @property {Action<null>} back - Returns to the previous state.
205
+ */
76
206
  export interface MFAAOTPSecretCreationActions {
77
207
  readonly otp_code_verify: Action<OTPCodeInputs>;
78
208
  readonly back: Action<null>;
79
209
  }
210
+ /**
211
+ * Actions available in the `mfa_security_key_creation` state, while registering a security key as a second factor.
212
+ * @interface
213
+ * @category SDK
214
+ * @subcategory Flow Actions
215
+ * @property {Action<null>} webauthn_generate_creation_options - Requests WebAuthn attestation (registration) options for the security key.
216
+ * @property {Action<null>} back - Returns to the previous state.
217
+ */
80
218
  export interface MFASecurityKeyCreationActions {
81
219
  readonly webauthn_generate_creation_options: Action<null>;
82
220
  readonly back: Action<null>;
83
221
  }
222
+ /**
223
+ * Actions available in the `onboarding_create_passkey` state, while registering a passkey during onboarding.
224
+ * @interface
225
+ * @category SDK
226
+ * @subcategory Flow Actions
227
+ * @property {Action<null>} webauthn_generate_creation_options - Requests WebAuthn attestation (registration) options for the passkey.
228
+ * @property {Action<null>} [skip] - Skips passkey creation, if optional.
229
+ * @property {Action<null>} [back] - Returns to the previous state.
230
+ */
84
231
  export interface OnboardingCreatePasskeyActions {
85
232
  readonly webauthn_generate_creation_options: Action<null>;
86
233
  readonly skip?: Action<null>;
87
234
  readonly back?: Action<null>;
88
235
  }
236
+ /**
237
+ * Actions available in the `onboarding_verify_passkey_attestation` / `webauthn_credential_verification` states,
238
+ * while a passkey or security key attestation response is being submitted.
239
+ * @interface
240
+ * @category SDK
241
+ * @subcategory Flow Actions
242
+ * @property {Action<WebauthnVerifyAttestationResponseInputs>} webauthn_verify_attestation_response - Submits the WebAuthn attestation response for verification.
243
+ * @property {Action<null>} back - Returns to the previous state.
244
+ */
89
245
  export interface OnboardingVerifyPasskeyAttestationActions {
90
246
  readonly webauthn_verify_attestation_response: Action<WebauthnVerifyAttestationResponseInputs>;
91
247
  readonly back: Action<null>;
92
248
  }
249
+ /**
250
+ * Actions available in the `registration_init` state, the entry point of a registration flow.
251
+ * @interface
252
+ * @category SDK
253
+ * @subcategory Flow Actions
254
+ * @property {Action<RegisterLoginIdentifierInputs>} register_login_identifier - Submits an identifier (e.g. email or username) to start registration.
255
+ * @property {Action<ThirdpartyOauthInputs>} [thirdparty_oauth] - Starts registration via a third-party OAuth provider.
256
+ * @property {Action<RememberMeInputs>} [remember_me] - Sets whether the device should be remembered for future logins.
257
+ */
93
258
  export interface RegistrationInitActions {
94
259
  readonly register_login_identifier: Action<RegisterLoginIdentifierInputs>;
95
260
  readonly thirdparty_oauth?: Action<ThirdpartyOauthInputs>;
96
261
  readonly remember_me?: Action<RememberMeInputs>;
97
262
  }
263
+ /**
264
+ * Actions available in the `password_creation` state, while setting a password during registration.
265
+ * @interface
266
+ * @category SDK
267
+ * @subcategory Flow Actions
268
+ * @property {Action<RegisterPasswordInputs>} register_password - Submits the chosen password.
269
+ * @property {Action<null>} [back] - Returns to the previous state.
270
+ * @property {Action<null>} [skip] - Skips setting a password, if optional.
271
+ */
98
272
  export interface PasswordCreationActions {
99
273
  readonly register_password: Action<RegisterPasswordInputs>;
100
274
  readonly back?: Action<null>;
101
275
  readonly skip?: Action<null>;
102
276
  }
277
+ /**
278
+ * Actions available in the `passcode_confirmation` state, while confirming a one-time passcode sent to the user.
279
+ * @interface
280
+ * @category SDK
281
+ * @subcategory Flow Actions
282
+ * @property {Action<VerifyPasscodeInputs>} verify_passcode - Submits the entered passcode for verification.
283
+ * @property {Action<null>} resend_passcode - Requests the passcode to be sent again.
284
+ * @property {Action<null>} back - Returns to the previous state.
285
+ */
103
286
  export interface PasscodeConfirmationActions {
104
287
  readonly verify_passcode: Action<VerifyPasscodeInputs>;
105
288
  readonly resend_passcode: Action<null>;
106
289
  readonly back: Action<null>;
107
290
  }
291
+ /**
292
+ * Actions available in the `onboarding_email` state, while setting an email address during onboarding.
293
+ * @interface
294
+ * @category SDK
295
+ * @subcategory Flow Actions
296
+ * @property {Action<EmailCreateInputs>} email_address_set - Submits the chosen email address.
297
+ * @property {Action<null>} skip - Skips setting an email address, if optional.
298
+ */
108
299
  export interface OnboardingEmailActions {
109
300
  readonly email_address_set: Action<EmailCreateInputs>;
110
301
  readonly skip: Action<null>;
111
302
  }
303
+ /**
304
+ * Actions available in the `onboarding_username` state, while setting a username during onboarding.
305
+ * @interface
306
+ * @category SDK
307
+ * @subcategory Flow Actions
308
+ * @property {Action<UsernameSetInputs>} username_create - Submits the chosen username.
309
+ * @property {Action<null>} skip - Skips setting a username, if optional.
310
+ */
112
311
  export interface OnboardingUsernameActions {
113
312
  readonly username_create: Action<UsernameSetInputs>;
114
313
  readonly skip: Action<null>;
115
314
  }
315
+ /**
316
+ * Actions available in the `credential_onboarding_chooser` state, letting the user pick how to onboard a credential.
317
+ * @interface
318
+ * @category SDK
319
+ * @subcategory Flow Actions
320
+ * @property {Action<null>} continue_to_passkey_registration - Switches to passkey registration.
321
+ * @property {Action<null>} continue_to_password_registration - Switches to password registration.
322
+ * @property {Action<null>} skip - Skips credential onboarding, if optional.
323
+ * @property {Action<null>} back - Returns to the previous state.
324
+ */
116
325
  export interface CredentialOnboardingChooserActions {
117
326
  readonly continue_to_passkey_registration: Action<null>;
118
327
  readonly continue_to_password_registration: Action<null>;
119
328
  readonly skip: Action<null>;
120
329
  readonly back: Action<null>;
121
330
  }
331
+ /**
332
+ * Actions available in the `device_trust` state, letting the user decide whether to trust the current device.
333
+ * @interface
334
+ * @category SDK
335
+ * @subcategory Flow Actions
336
+ * @property {Action<null>} trust_device - Marks the current device as trusted.
337
+ * @property {Action<null>} skip - Declines to trust the current device.
338
+ * @property {Action<null>} [back] - Returns to the previous state.
339
+ */
122
340
  export interface DeviceTrustActions {
123
341
  readonly trust_device: Action<null>;
124
342
  readonly skip: Action<null>;
125
343
  readonly back?: Action<null>;
126
344
  }
345
+ /**
346
+ * Actions available in the `thirdparty` state, while a third-party OAuth flow is being completed.
347
+ * @interface
348
+ * @category SDK
349
+ * @subcategory Flow Actions
350
+ * @property {Action<ExchangeTokenInputs>} exchange_token - Exchanges the third-party provider's callback token for a session.
351
+ * @property {Action<null>} [back] - Returns to the previous state.
352
+ */
127
353
  export interface ThirdPartyActions {
128
354
  readonly exchange_token: Action<ExchangeTokenInputs>;
129
355
  readonly back?: Action<null>;
@@ -2,18 +2,68 @@ import { StateName, Actions, Payloads } from "./state";
2
2
  import { FlowError } from "./flowError";
3
3
  import { State } from "../State";
4
4
  type PickStates<TState extends StateName> = TState;
5
+ /**
6
+ * The name of a top-level flow exposed by the flow API. Each flow is a self-contained state
7
+ * machine (e.g. logging in, registering, or managing a profile).
8
+ * @category SDK
9
+ * @subcategory Flow Types
10
+ */
5
11
  export type FlowName = "login" | "registration" | "profile" | "token_exchange";
12
+ /**
13
+ * A {@link State} narrowed to any one of the possible {@link StateName}s a flow can be in.
14
+ * @category SDK
15
+ * @subcategory Flow Types
16
+ */
6
17
  export type AnyState = {
7
18
  [TState in StateName]: State<TState>;
8
19
  }[StateName];
20
+ /**
21
+ * A handler that automatically runs a follow-up action for a given state, without requiring
22
+ * explicit user interaction. See {@link State#autoStep}.
23
+ * @template TState - The state name the handler applies to.
24
+ * @category SDK
25
+ * @subcategory Flow Types
26
+ */
9
27
  export type AutoStep<TState extends StateName> = (state: State<TState>) => Promise<AnyState>;
28
+ /**
29
+ * Maps each state that supports an automatic step (see {@link AutoStep}) to its handler.
30
+ * @category SDK
31
+ * @subcategory Flow Types
32
+ */
10
33
  export type AutoSteps = {
11
34
  [TState in PickStates<"preflight" | "login_passkey" | "onboarding_verify_passkey_attestation" | "webauthn_credential_verification" | "thirdparty" | "success" | "account_deleted">]: AutoStep<TState>;
12
35
  };
36
+ /**
37
+ * A handler that activates WebAuthn passkey autofill (conditional mediation) for a given state.
38
+ * See {@link State#passkeyAutofillActivation}.
39
+ * @template TState - The state name the handler applies to.
40
+ * @category SDK
41
+ * @subcategory Flow Types
42
+ */
13
43
  export type PasskeyAutofillActivationHandler<TState extends StateName> = (state: State<TState>) => Promise<void>;
44
+ /**
45
+ * Maps each state that supports passkey autofill activation (see {@link PasskeyAutofillActivationHandler})
46
+ * to its handler.
47
+ * @category SDK
48
+ * @subcategory Flow Types
49
+ */
14
50
  export type PasskeyAutofillActivationHandlers = {
15
51
  [TState in PickStates<"login_init">]: PasskeyAutofillActivationHandler<TState>;
16
52
  };
53
+ /**
54
+ * The raw response returned by the flow API backend for a given state, before it is wrapped in a
55
+ * {@link State} instance.
56
+ * @template TState - The specific state name type.
57
+ * @interface
58
+ * @category SDK
59
+ * @subcategory Flow Types
60
+ * @property {TState} name - The name of the state.
61
+ * @property {number} status - The HTTP status code of the response.
62
+ * @property {*} [payload] - The state's payload data, if any (see {@link Payloads}).
63
+ * @property {*} [actions] - The actions available from this state (see {@link Actions}).
64
+ * @property {string} csrf_token - The CSRF token to include when running an action from this state.
65
+ * @property {FlowError} [error] - A general error for this state, if the previous action failed.
66
+ */
17
67
  export interface FlowResponse<TState extends StateName> {
18
68
  name: TState;
19
69
  status: number;
@@ -1,3 +1,13 @@
1
+ /**
2
+ * An error returned by the flow API, either at the top level of a {@link State} (a general failure)
3
+ * or attached to an individual {@link Input} (a validation error for that specific field).
4
+ * @interface
5
+ * @category SDK
6
+ * @subcategory Flow Errors
7
+ * @property {string} code - A machine-readable error code.
8
+ * @property {string} message - A human-readable error message.
9
+ * @property {string} [cause] - Additional detail about what caused the error, if available.
10
+ */
1
11
  export interface FlowError {
2
12
  code: string;
3
13
  message: string;