@glideidentity/glide-be-node-magical-auth 3.2.0 → 3.2.1

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.
@@ -94,19 +94,23 @@ declare const UseCase: {
94
94
  type UseCase = (typeof UseCase)[keyof typeof UseCase];
95
95
  /**
96
96
  * Authentication strategy returned by prepare.
97
- * Use `AuthenticationStrategy.TS43`, `.LINK`, or `.DESKTOP` instead of raw strings.
97
+ * Use `AuthenticationStrategy.TS43`, `.LINK`, `.DESKTOP`, `.PASSKEY`, or `.CALL` instead of raw strings.
98
98
  */
99
99
  declare const AuthenticationStrategy: {
100
100
  readonly TS43: "ts43";
101
101
  readonly LINK: "link";
102
102
  readonly DESKTOP: "desktop";
103
+ readonly PASSKEY: "passkey";
104
+ readonly CALL: "call";
103
105
  readonly NONE: "";
104
106
  };
105
107
  type AuthenticationStrategy = (typeof AuthenticationStrategy)[keyof typeof AuthenticationStrategy];
106
108
  /**
107
109
  * Protocol type for authentication.
108
110
  */
109
- type ProtocolType = 'ts43' | 'link' | 'desktop';
111
+ type ProtocolType = 'ts43' | 'link' | 'desktop' | 'passkey' | 'call';
112
+ /** Session metadata key on companion sessions of a call verification. */
113
+ declare const SessionMetadataParentStrategy = "parent_strategy";
110
114
  /**
111
115
  * Session status for polling.
112
116
  * Use `SessionStatus.PENDING`, `.SCANNED`, etc. instead of raw strings.
@@ -320,6 +324,11 @@ interface NetworkOrigin {
320
324
  * front an entire NAT/CGNAT or a whole city) — and must never be used as a hard
321
325
  * gate. Branch on `match`; the caller owns any threshold on `prefix_bits`.
322
326
  */
327
+ /** Required with authentication_strategy `call`. */
328
+ interface CallOptions {
329
+ /** The number the caller dialled (E.164). Used only for the live-call check. */
330
+ called_number: string;
331
+ }
323
332
  interface NetworkCheck {
324
333
  /** Branch on this. On 'unknown', family and prefix_bits are absent. */
325
334
  match: 'same_ip' | 'same_subnet' | 'different' | 'unknown' | (string & {});
@@ -394,6 +403,31 @@ interface PrepareOptions {
394
403
  * @example "https://checkout.use1.staging.glideid.app/glide-complete"
395
404
  */
396
405
  completion_redirect_url?: string;
406
+ /** Requests a passkey challenge for `origin`; required with `step_up`. */
407
+ passkey?: PasskeyOption;
408
+ /** Binds the session to `action`; check the record with `verifyStepUp`. */
409
+ step_up?: StepUpOption;
410
+ /** Required with authentication_strategy `call`; refused with any other strategy. */
411
+ call?: CallOptions;
412
+ }
413
+ /** Enables the passkey factor on prepare. */
414
+ interface PasskeyOption {
415
+ enabled: boolean;
416
+ origin: string;
417
+ }
418
+ /** The action a step-up session approves. */
419
+ interface StepUpOption {
420
+ action: Record<string, string>;
421
+ }
422
+ /** A WebAuthn challenge: request options on a step-up prepare, creation options on a verify's `passkey_enrolment`. */
423
+ interface PasskeyChallenge {
424
+ challenge_key: string;
425
+ /** WebAuthn options JSON for the browser: get() request options, or create() creation options on an enrolment. */
426
+ public_key: Record<string, unknown>;
427
+ }
428
+ /** Hash of the action a step-up session is bound to. */
429
+ interface StepUpPrepared {
430
+ action_hash: string;
397
431
  }
398
432
  /**
399
433
  * Request body for prepare authentication.
@@ -450,8 +484,9 @@ interface PrepareRequest {
450
484
  interface PrepareResult extends PrepareResponse {
451
485
  /**
452
486
  * Frontend binding code for device-bound link protocol sessions.
453
- * Only present when `authentication_strategy === 'link'`.
454
- * The caller MUST set this as an HttpOnly cookie using `buildSetBindingCookieHeader()`.
487
+ * Present when the strategy or its fallback is 'link'. The caller MUST set it as an
488
+ * HttpOnly cookie for the link session (`fallback.session` when the fallback is link)
489
+ * using `buildSetBindingCookieHeader()`.
455
490
  */
456
491
  feCode?: string;
457
492
  }
@@ -469,6 +504,7 @@ interface PrepareResponse {
469
504
  * - 'ts43': TS43StrategyData - Contains protocol, data with dcql_query
470
505
  * - 'link': LinkStrategyData - Contains url, return_url, status_url, params
471
506
  * - 'desktop': DesktopStrategyData - Contains protocol, data with a single universal QR image and URL
507
+ * - 'call': CallStrategyData - Contains url and status_url
472
508
  */
473
509
  data: StrategyData;
474
510
  /** Visual verification challenge (for desktop strategy) */
@@ -499,12 +535,25 @@ interface PrepareResponse {
499
535
  * privacy-by-default contract.
500
536
  */
501
537
  carrier_name?: string;
538
+ /**
539
+ * TS43 from an Android client: `unavailable` on Android Chrome below 156,
540
+ * where biometric is never requested; verify returns `UNSUPPORTED` if biometric was requested at prepare.
541
+ */
542
+ biometric?: 'available' | 'unavailable';
502
543
  /**
503
544
  * The id of this request, the same value as the `X-Request-ID` response
504
545
  * header. Quote it to Glide support. Absent from servers older than the
505
546
  * release that added it. The session this creates is `session.session_key`.
506
547
  */
507
548
  request_id?: string;
549
+ /** Present on a step-up prepare; a passkey sign-in carries its options in `data.passkey`. */
550
+ passkey?: PasskeyChallenge;
551
+ /** Present on a step-up prepare. */
552
+ step_up?: StepUpPrepared;
553
+ /** On a `passkey` response, the carrier prepare to run when the user cancels the passkey. */
554
+ fallback?: PrepareResponse;
555
+ /** True when a carrier success on this session will return `passkey_enrolment`. */
556
+ passkey_enrolment?: boolean;
508
557
  }
509
558
 
510
559
  /**
@@ -610,11 +659,32 @@ interface DesktopStrategyData {
610
659
  /** QR code and session binding information */
611
660
  data: DesktopQRData;
612
661
  }
662
+ /**
663
+ * Passkey sign-in strategy data.
664
+ * Used when authentication_strategy is 'passkey'.
665
+ */
666
+ interface PasskeyStrategyData {
667
+ passkey: {
668
+ challenge_key: string;
669
+ /** PublicKeyCredentialRequestOptionsJSON for navigator.credentials.get. */
670
+ public_key: Record<string, unknown>;
671
+ };
672
+ }
673
+ /**
674
+ * Call strategy data.
675
+ * Used when authentication_strategy is 'call'.
676
+ */
677
+ interface CallStrategyData {
678
+ /** Companion URL the caller opens on the phone being verified. */
679
+ url: string;
680
+ /** Protected status endpoint for this session. */
681
+ status_url: string;
682
+ }
613
683
  /**
614
684
  * Union type for strategy-specific data.
615
685
  * The actual type depends on the authentication_strategy value.
616
686
  */
617
- type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData;
687
+ type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData | CallStrategyData | PasskeyStrategyData;
618
688
 
619
689
  /**
620
690
  * Error codes returned by the Magical Auth API.
@@ -630,6 +700,7 @@ declare const ErrorCode: {
630
700
  readonly CARRIER_NOT_ELIGIBLE: "CARRIER_NOT_ELIGIBLE";
631
701
  readonly CARRIER_REJECTED: "CARRIER_REJECTED";
632
702
  readonly CARRIER_APP_UNAVAILABLE: "CARRIER_APP_UNAVAILABLE";
703
+ readonly CARRIER_TEMPORARILY_UNAVAILABLE: "CARRIER_TEMPORARILY_UNAVAILABLE";
633
704
  readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
634
705
  readonly PHONE_NUMBER_MISMATCH: "PHONE_NUMBER_MISMATCH";
635
706
  readonly INVALID_CREDENTIAL_FORMAT: "INVALID_CREDENTIAL_FORMAT";
@@ -763,6 +834,13 @@ declare class CarrierRejectedError extends MagicalAuthError {
763
834
  declare class CarrierAppUnavailableError extends MagicalAuthError {
764
835
  constructor(message?: string, requestId?: string, details?: Record<string, unknown>);
765
836
  }
837
+ /**
838
+ * The carrier is temporarily unavailable. Retryable after `retryAfter` seconds.
839
+ */
840
+ declare class CarrierTemporarilyUnavailableError extends MagicalAuthError {
841
+ readonly retryAfter?: number;
842
+ constructor(message: string, retryAfter?: number, requestId?: string, details?: Record<string, unknown>);
843
+ }
766
844
  /**
767
845
  * Platform not supported for authentication.
768
846
  */
@@ -877,6 +955,7 @@ declare const VerificationRecordErrorCode: {
877
955
  readonly UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION";
878
956
  readonly REVOKED_KEY: "REVOKED_KEY";
879
957
  readonly RECORD_UNAVAILABLE: "RECORD_UNAVAILABLE";
958
+ readonly STEP_UP_REJECTED: "STEP_UP_REJECTED";
880
959
  };
881
960
  type VerificationRecordErrorCode = (typeof VerificationRecordErrorCode)[keyof typeof VerificationRecordErrorCode];
882
961
  /**
@@ -919,6 +998,55 @@ type PrepareMultipleResult = {
919
998
  error: MagicalAuthError;
920
999
  };
921
1000
 
1001
+ /** `call` session hand-off stage on the protected status endpoint. */
1002
+ type CallStage = 'prepared' | 'opened' | 'approving' | 'completed' | 'failed' | 'expired';
1003
+ /** Outcome of the T-Mobile live-call check on status and verify responses. */
1004
+ interface LiveCallInfo {
1005
+ /** False exactly when `status` is `unavailable`. */
1006
+ checked: boolean;
1007
+ status: 'active' | 'none' | 'unavailable';
1008
+ carrier_name?: string;
1009
+ checked_at?: string;
1010
+ reason?: 'carrier_not_supported' | 'timeout' | 'error' | 'disabled';
1011
+ }
1012
+ /**
1013
+ * Response from status polling endpoints.
1014
+ *
1015
+ * Note: This endpoint does NOT expose phone_number or verification results directly.
1016
+ * Sensitive data is only returned via the protected verify/get-phone-number endpoints
1017
+ * which require authentication.
1018
+ */
1019
+ interface StatusResponse {
1020
+ /** The session identifier (16-char hex) */
1021
+ session_key: string;
1022
+ /** Current status of the verification request */
1023
+ status: SessionStatus;
1024
+ /** Protocol used for authentication (optional) */
1025
+ protocol?: ProtocolType;
1026
+ /** Session creation timestamp (ISO 8601) */
1027
+ created_at: string;
1028
+ /** Last status update timestamp (ISO 8601) */
1029
+ last_updated: string;
1030
+ /** Device info (only present when status is "scanned" or later) */
1031
+ device_info?: DeviceInfo;
1032
+ /** Grace period expiry time (only present when status is "scanned") */
1033
+ grace_expires_at?: string;
1034
+ /** Timestamp when the QR code was scanned */
1035
+ scanned_at?: string;
1036
+ /** `call` sessions only: browser-observed hand-off stage. */
1037
+ stage?: CallStage;
1038
+ /** `call` sessions only: T-Mobile live-call check outcome once the check has run. */
1039
+ live_call?: LiveCallInfo;
1040
+ /** Additional metadata (e.g., error reason for failed status) */
1041
+ extra?: Record<string, unknown>;
1042
+ /**
1043
+ * The id of this request, the same value as the `X-Request-ID` response
1044
+ * header. Quote it to Glide support. Absent from servers older than the
1045
+ * release that added it.
1046
+ */
1047
+ request_id?: string;
1048
+ }
1049
+
922
1050
  /**
923
1051
  * Request body for verify phone number.
924
1052
  */
@@ -935,6 +1063,14 @@ interface VerifyPhoneNumberRequest {
935
1063
  * Only used for native link protocol sessions — web sessions use fe_code instead.
936
1064
  */
937
1065
  signature?: string;
1066
+ /** WebAuthn assertion JSON string from the browser; required on a step-up session. */
1067
+ passkey_assertion?: string;
1068
+ }
1069
+ /** Which step-up factors passed on verify. */
1070
+ interface StepUpResult {
1071
+ passkey: boolean;
1072
+ carrier: boolean;
1073
+ action_hash: string;
938
1074
  }
939
1075
  /**
940
1076
  * Response from verify phone number.
@@ -957,6 +1093,8 @@ interface VerifyPhoneNumberResponse {
957
1093
  sim_swap?: SimSwapInfo;
958
1094
  /** Device swap (IMEI change) check result (when supported by carrier) */
959
1095
  device_swap?: DeviceSwapInfo;
1096
+ /** T-Mobile live-call check outcome (`call` sessions). */
1097
+ live_call?: LiveCallInfo;
960
1098
  /** Same-network signal (Desktop QR, when the desktop prepare stamped network_origin) */
961
1099
  network_check?: NetworkCheck;
962
1100
  /** Parsed phone number components (optional, server-populated) */
@@ -980,6 +1118,15 @@ interface VerifyPhoneNumberResponse {
980
1118
  * release that added it.
981
1119
  */
982
1120
  request_id?: string;
1121
+ /** `'used'` on a step-up session. */
1122
+ passkey?: string;
1123
+ /** Present on a step-up session. */
1124
+ step_up?: StepUpResult;
1125
+ /**
1126
+ * WebAuthn creation options after a carrier verification on a prepare that asked
1127
+ * for passkeys; forward it to the browser to save a passkey.
1128
+ */
1129
+ passkey_enrolment?: PasskeyChallenge;
983
1130
  }
984
1131
 
985
1132
  /**
@@ -1032,40 +1179,6 @@ interface GetPhoneNumberResponse {
1032
1179
  request_id?: string;
1033
1180
  }
1034
1181
 
1035
- /**
1036
- * Response from status polling endpoints.
1037
- *
1038
- * Note: This endpoint does NOT expose phone_number or verification results directly.
1039
- * Sensitive data is only returned via the protected verify/get-phone-number endpoints
1040
- * which require authentication.
1041
- */
1042
- interface StatusResponse {
1043
- /** The session identifier (16-char hex) */
1044
- session_key: string;
1045
- /** Current status of the verification request */
1046
- status: SessionStatus;
1047
- /** Protocol used for authentication (optional) */
1048
- protocol?: ProtocolType;
1049
- /** Session creation timestamp (ISO 8601) */
1050
- created_at: string;
1051
- /** Last status update timestamp (ISO 8601) */
1052
- last_updated: string;
1053
- /** Device info (only present when status is "scanned" or later) */
1054
- device_info?: DeviceInfo;
1055
- /** Grace period expiry time (only present when status is "scanned") */
1056
- grace_expires_at?: string;
1057
- /** Timestamp when the QR code was scanned */
1058
- scanned_at?: string;
1059
- /** Additional metadata (e.g., error reason for failed status) */
1060
- extra?: Record<string, unknown>;
1061
- /**
1062
- * The id of this request, the same value as the `X-Request-ID` response
1063
- * header. Quote it to Glide support. Absent from servers older than the
1064
- * release that added it.
1065
- */
1066
- request_id?: string;
1067
- }
1068
-
1069
1182
  /**
1070
1183
  * Request body for report invocation.
1071
1184
  */
@@ -1158,4 +1271,4 @@ declare function createLogger(config?: LoggerConfig): Logger;
1158
1271
  */
1159
1272
  declare function sanitize(data: unknown): unknown;
1160
1273
 
1161
- export { type ResolvedConfig as $, AuthenticationStrategy as A, BadRequestError as B, CarrierAppUnavailableError as C, type DCQLCredential as D, ErrorCode as E, ForbiddenError as F, type GetPhoneNumberRequest as G, type HttpClient as H, InternalServerError as I, type NetworkOrigin as J, PREPARE_MULTIPLE_MAX as K, type LinkStrategyData as L, type MagicalAuthConfig as M, type NetworkCheck as N, type PhoneNumberDetails as O, type PLMN as P, PhoneNumberMismatchError as Q, type PrepareMultipleRequest as R, type PrepareMultipleResult as S, type PrepareOptions as T, type PrepareRequest as U, type PrepareResponse as V, type PrepareResult as W, type ProtocolType as X, RateLimitError as Y, type ReportInvocationRequest as Z, type ReportInvocationResponse as _, BiometricVerification as a, type RiskLevel as a0, ServiceUnavailableError as a1, type SessionInfo as a2, SessionNotEligibleError as a3, SessionNotFoundError as a4, SessionStatus as a5, type SimSwapFailureReason as a6, type SimSwapInfo as a7, type StatusResponse as a8, type StrategyData as a9, type TS43RequestData as aa, type TS43StrategyData as ab, type Theme as ac, UnauthorizedError as ad, UnsupportedPlatformError as ae, UseCase as af, ValidationError as ag, VerificationRecordError as ah, VerificationRecordErrorCode as ai, type VerifyPhoneNumberRequest as aj, type VerifyPhoneNumberResponse as ak, createErrorFromResponse as al, createLogger as am, defaultHttpClient as an, noopLogger as ao, resolveConfig as ap, sanitize as aq, BrowserMismatchError as b, CarrierNotEligibleError as c, CarrierRejectedError as d, type Challenge as e, type ClientInfo as f, type ConsentData as g, type DCQLCredentialMeta as h, type DCQLQuery as i, DEFAULT_BASE_URL as j, DEFAULT_TIMEOUT as k, type DesktopQRData as l, type DesktopStrategyData as m, DesktopWaitError as n, DeviceBindingError as o, type DeviceInfo as p, type DeviceSwapInfo as q, type ErrorResponse as r, type GetPhoneNumberResponse as s, type HttpRequestOptions as t, type HttpResponse as u, InvalidCredentialError as v, type Logger as w, type LoggerConfig as x, MagicalAuthError as y, MissingBindingCookieError as z };
1274
+ export { type PrepareOptions as $, AuthenticationStrategy as A, BadRequestError as B, type CallOptions as C, type DCQLCredential as D, ErrorCode as E, ForbiddenError as F, type GetPhoneNumberRequest as G, type HttpClient as H, InternalServerError as I, type LiveCallInfo as J, type Logger as K, type LinkStrategyData as L, type LoggerConfig as M, type MagicalAuthConfig as N, MagicalAuthError as O, MissingBindingCookieError as P, type NetworkCheck as Q, type NetworkOrigin as R, type PLMN as S, PREPARE_MULTIPLE_MAX as T, type PasskeyChallenge as U, type PasskeyOption as V, type PasskeyStrategyData as W, type PhoneNumberDetails as X, PhoneNumberMismatchError as Y, type PrepareMultipleRequest as Z, type PrepareMultipleResult as _, BiometricVerification as a, type PrepareRequest as a0, type PrepareResponse as a1, type PrepareResult as a2, type ProtocolType as a3, RateLimitError as a4, type ReportInvocationRequest as a5, type ReportInvocationResponse as a6, type ResolvedConfig as a7, type RiskLevel as a8, ServiceUnavailableError as a9, noopLogger as aA, resolveConfig as aB, sanitize as aC, type SessionInfo as aa, SessionMetadataParentStrategy as ab, SessionNotEligibleError as ac, SessionNotFoundError as ad, SessionStatus as ae, type SimSwapFailureReason as af, type SimSwapInfo as ag, type StatusResponse as ah, type StepUpOption as ai, type StepUpPrepared as aj, type StepUpResult as ak, type StrategyData as al, type TS43RequestData as am, type TS43StrategyData as an, type Theme as ao, UnauthorizedError as ap, UnsupportedPlatformError as aq, UseCase as ar, ValidationError as as, VerificationRecordError as at, VerificationRecordErrorCode as au, type VerifyPhoneNumberRequest as av, type VerifyPhoneNumberResponse as aw, createErrorFromResponse as ax, createLogger as ay, defaultHttpClient as az, BrowserMismatchError as b, type CallStage as c, type CallStrategyData as d, CarrierAppUnavailableError as e, CarrierNotEligibleError as f, CarrierRejectedError as g, CarrierTemporarilyUnavailableError as h, type Challenge as i, type ClientInfo as j, type ConsentData as k, type DCQLCredentialMeta as l, type DCQLQuery as m, DEFAULT_BASE_URL as n, DEFAULT_TIMEOUT as o, type DesktopQRData as p, type DesktopStrategyData as q, DesktopWaitError as r, DeviceBindingError as s, type DeviceInfo as t, type DeviceSwapInfo as u, type ErrorResponse as v, type GetPhoneNumberResponse as w, type HttpRequestOptions as x, type HttpResponse as y, InvalidCredentialError as z };
@@ -94,19 +94,23 @@ declare const UseCase: {
94
94
  type UseCase = (typeof UseCase)[keyof typeof UseCase];
95
95
  /**
96
96
  * Authentication strategy returned by prepare.
97
- * Use `AuthenticationStrategy.TS43`, `.LINK`, or `.DESKTOP` instead of raw strings.
97
+ * Use `AuthenticationStrategy.TS43`, `.LINK`, `.DESKTOP`, `.PASSKEY`, or `.CALL` instead of raw strings.
98
98
  */
99
99
  declare const AuthenticationStrategy: {
100
100
  readonly TS43: "ts43";
101
101
  readonly LINK: "link";
102
102
  readonly DESKTOP: "desktop";
103
+ readonly PASSKEY: "passkey";
104
+ readonly CALL: "call";
103
105
  readonly NONE: "";
104
106
  };
105
107
  type AuthenticationStrategy = (typeof AuthenticationStrategy)[keyof typeof AuthenticationStrategy];
106
108
  /**
107
109
  * Protocol type for authentication.
108
110
  */
109
- type ProtocolType = 'ts43' | 'link' | 'desktop';
111
+ type ProtocolType = 'ts43' | 'link' | 'desktop' | 'passkey' | 'call';
112
+ /** Session metadata key on companion sessions of a call verification. */
113
+ declare const SessionMetadataParentStrategy = "parent_strategy";
110
114
  /**
111
115
  * Session status for polling.
112
116
  * Use `SessionStatus.PENDING`, `.SCANNED`, etc. instead of raw strings.
@@ -320,6 +324,11 @@ interface NetworkOrigin {
320
324
  * front an entire NAT/CGNAT or a whole city) — and must never be used as a hard
321
325
  * gate. Branch on `match`; the caller owns any threshold on `prefix_bits`.
322
326
  */
327
+ /** Required with authentication_strategy `call`. */
328
+ interface CallOptions {
329
+ /** The number the caller dialled (E.164). Used only for the live-call check. */
330
+ called_number: string;
331
+ }
323
332
  interface NetworkCheck {
324
333
  /** Branch on this. On 'unknown', family and prefix_bits are absent. */
325
334
  match: 'same_ip' | 'same_subnet' | 'different' | 'unknown' | (string & {});
@@ -394,6 +403,31 @@ interface PrepareOptions {
394
403
  * @example "https://checkout.use1.staging.glideid.app/glide-complete"
395
404
  */
396
405
  completion_redirect_url?: string;
406
+ /** Requests a passkey challenge for `origin`; required with `step_up`. */
407
+ passkey?: PasskeyOption;
408
+ /** Binds the session to `action`; check the record with `verifyStepUp`. */
409
+ step_up?: StepUpOption;
410
+ /** Required with authentication_strategy `call`; refused with any other strategy. */
411
+ call?: CallOptions;
412
+ }
413
+ /** Enables the passkey factor on prepare. */
414
+ interface PasskeyOption {
415
+ enabled: boolean;
416
+ origin: string;
417
+ }
418
+ /** The action a step-up session approves. */
419
+ interface StepUpOption {
420
+ action: Record<string, string>;
421
+ }
422
+ /** A WebAuthn challenge: request options on a step-up prepare, creation options on a verify's `passkey_enrolment`. */
423
+ interface PasskeyChallenge {
424
+ challenge_key: string;
425
+ /** WebAuthn options JSON for the browser: get() request options, or create() creation options on an enrolment. */
426
+ public_key: Record<string, unknown>;
427
+ }
428
+ /** Hash of the action a step-up session is bound to. */
429
+ interface StepUpPrepared {
430
+ action_hash: string;
397
431
  }
398
432
  /**
399
433
  * Request body for prepare authentication.
@@ -450,8 +484,9 @@ interface PrepareRequest {
450
484
  interface PrepareResult extends PrepareResponse {
451
485
  /**
452
486
  * Frontend binding code for device-bound link protocol sessions.
453
- * Only present when `authentication_strategy === 'link'`.
454
- * The caller MUST set this as an HttpOnly cookie using `buildSetBindingCookieHeader()`.
487
+ * Present when the strategy or its fallback is 'link'. The caller MUST set it as an
488
+ * HttpOnly cookie for the link session (`fallback.session` when the fallback is link)
489
+ * using `buildSetBindingCookieHeader()`.
455
490
  */
456
491
  feCode?: string;
457
492
  }
@@ -469,6 +504,7 @@ interface PrepareResponse {
469
504
  * - 'ts43': TS43StrategyData - Contains protocol, data with dcql_query
470
505
  * - 'link': LinkStrategyData - Contains url, return_url, status_url, params
471
506
  * - 'desktop': DesktopStrategyData - Contains protocol, data with a single universal QR image and URL
507
+ * - 'call': CallStrategyData - Contains url and status_url
472
508
  */
473
509
  data: StrategyData;
474
510
  /** Visual verification challenge (for desktop strategy) */
@@ -499,12 +535,25 @@ interface PrepareResponse {
499
535
  * privacy-by-default contract.
500
536
  */
501
537
  carrier_name?: string;
538
+ /**
539
+ * TS43 from an Android client: `unavailable` on Android Chrome below 156,
540
+ * where biometric is never requested; verify returns `UNSUPPORTED` if biometric was requested at prepare.
541
+ */
542
+ biometric?: 'available' | 'unavailable';
502
543
  /**
503
544
  * The id of this request, the same value as the `X-Request-ID` response
504
545
  * header. Quote it to Glide support. Absent from servers older than the
505
546
  * release that added it. The session this creates is `session.session_key`.
506
547
  */
507
548
  request_id?: string;
549
+ /** Present on a step-up prepare; a passkey sign-in carries its options in `data.passkey`. */
550
+ passkey?: PasskeyChallenge;
551
+ /** Present on a step-up prepare. */
552
+ step_up?: StepUpPrepared;
553
+ /** On a `passkey` response, the carrier prepare to run when the user cancels the passkey. */
554
+ fallback?: PrepareResponse;
555
+ /** True when a carrier success on this session will return `passkey_enrolment`. */
556
+ passkey_enrolment?: boolean;
508
557
  }
509
558
 
510
559
  /**
@@ -610,11 +659,32 @@ interface DesktopStrategyData {
610
659
  /** QR code and session binding information */
611
660
  data: DesktopQRData;
612
661
  }
662
+ /**
663
+ * Passkey sign-in strategy data.
664
+ * Used when authentication_strategy is 'passkey'.
665
+ */
666
+ interface PasskeyStrategyData {
667
+ passkey: {
668
+ challenge_key: string;
669
+ /** PublicKeyCredentialRequestOptionsJSON for navigator.credentials.get. */
670
+ public_key: Record<string, unknown>;
671
+ };
672
+ }
673
+ /**
674
+ * Call strategy data.
675
+ * Used when authentication_strategy is 'call'.
676
+ */
677
+ interface CallStrategyData {
678
+ /** Companion URL the caller opens on the phone being verified. */
679
+ url: string;
680
+ /** Protected status endpoint for this session. */
681
+ status_url: string;
682
+ }
613
683
  /**
614
684
  * Union type for strategy-specific data.
615
685
  * The actual type depends on the authentication_strategy value.
616
686
  */
617
- type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData;
687
+ type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData | CallStrategyData | PasskeyStrategyData;
618
688
 
619
689
  /**
620
690
  * Error codes returned by the Magical Auth API.
@@ -630,6 +700,7 @@ declare const ErrorCode: {
630
700
  readonly CARRIER_NOT_ELIGIBLE: "CARRIER_NOT_ELIGIBLE";
631
701
  readonly CARRIER_REJECTED: "CARRIER_REJECTED";
632
702
  readonly CARRIER_APP_UNAVAILABLE: "CARRIER_APP_UNAVAILABLE";
703
+ readonly CARRIER_TEMPORARILY_UNAVAILABLE: "CARRIER_TEMPORARILY_UNAVAILABLE";
633
704
  readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
634
705
  readonly PHONE_NUMBER_MISMATCH: "PHONE_NUMBER_MISMATCH";
635
706
  readonly INVALID_CREDENTIAL_FORMAT: "INVALID_CREDENTIAL_FORMAT";
@@ -763,6 +834,13 @@ declare class CarrierRejectedError extends MagicalAuthError {
763
834
  declare class CarrierAppUnavailableError extends MagicalAuthError {
764
835
  constructor(message?: string, requestId?: string, details?: Record<string, unknown>);
765
836
  }
837
+ /**
838
+ * The carrier is temporarily unavailable. Retryable after `retryAfter` seconds.
839
+ */
840
+ declare class CarrierTemporarilyUnavailableError extends MagicalAuthError {
841
+ readonly retryAfter?: number;
842
+ constructor(message: string, retryAfter?: number, requestId?: string, details?: Record<string, unknown>);
843
+ }
766
844
  /**
767
845
  * Platform not supported for authentication.
768
846
  */
@@ -877,6 +955,7 @@ declare const VerificationRecordErrorCode: {
877
955
  readonly UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION";
878
956
  readonly REVOKED_KEY: "REVOKED_KEY";
879
957
  readonly RECORD_UNAVAILABLE: "RECORD_UNAVAILABLE";
958
+ readonly STEP_UP_REJECTED: "STEP_UP_REJECTED";
880
959
  };
881
960
  type VerificationRecordErrorCode = (typeof VerificationRecordErrorCode)[keyof typeof VerificationRecordErrorCode];
882
961
  /**
@@ -919,6 +998,55 @@ type PrepareMultipleResult = {
919
998
  error: MagicalAuthError;
920
999
  };
921
1000
 
1001
+ /** `call` session hand-off stage on the protected status endpoint. */
1002
+ type CallStage = 'prepared' | 'opened' | 'approving' | 'completed' | 'failed' | 'expired';
1003
+ /** Outcome of the T-Mobile live-call check on status and verify responses. */
1004
+ interface LiveCallInfo {
1005
+ /** False exactly when `status` is `unavailable`. */
1006
+ checked: boolean;
1007
+ status: 'active' | 'none' | 'unavailable';
1008
+ carrier_name?: string;
1009
+ checked_at?: string;
1010
+ reason?: 'carrier_not_supported' | 'timeout' | 'error' | 'disabled';
1011
+ }
1012
+ /**
1013
+ * Response from status polling endpoints.
1014
+ *
1015
+ * Note: This endpoint does NOT expose phone_number or verification results directly.
1016
+ * Sensitive data is only returned via the protected verify/get-phone-number endpoints
1017
+ * which require authentication.
1018
+ */
1019
+ interface StatusResponse {
1020
+ /** The session identifier (16-char hex) */
1021
+ session_key: string;
1022
+ /** Current status of the verification request */
1023
+ status: SessionStatus;
1024
+ /** Protocol used for authentication (optional) */
1025
+ protocol?: ProtocolType;
1026
+ /** Session creation timestamp (ISO 8601) */
1027
+ created_at: string;
1028
+ /** Last status update timestamp (ISO 8601) */
1029
+ last_updated: string;
1030
+ /** Device info (only present when status is "scanned" or later) */
1031
+ device_info?: DeviceInfo;
1032
+ /** Grace period expiry time (only present when status is "scanned") */
1033
+ grace_expires_at?: string;
1034
+ /** Timestamp when the QR code was scanned */
1035
+ scanned_at?: string;
1036
+ /** `call` sessions only: browser-observed hand-off stage. */
1037
+ stage?: CallStage;
1038
+ /** `call` sessions only: T-Mobile live-call check outcome once the check has run. */
1039
+ live_call?: LiveCallInfo;
1040
+ /** Additional metadata (e.g., error reason for failed status) */
1041
+ extra?: Record<string, unknown>;
1042
+ /**
1043
+ * The id of this request, the same value as the `X-Request-ID` response
1044
+ * header. Quote it to Glide support. Absent from servers older than the
1045
+ * release that added it.
1046
+ */
1047
+ request_id?: string;
1048
+ }
1049
+
922
1050
  /**
923
1051
  * Request body for verify phone number.
924
1052
  */
@@ -935,6 +1063,14 @@ interface VerifyPhoneNumberRequest {
935
1063
  * Only used for native link protocol sessions — web sessions use fe_code instead.
936
1064
  */
937
1065
  signature?: string;
1066
+ /** WebAuthn assertion JSON string from the browser; required on a step-up session. */
1067
+ passkey_assertion?: string;
1068
+ }
1069
+ /** Which step-up factors passed on verify. */
1070
+ interface StepUpResult {
1071
+ passkey: boolean;
1072
+ carrier: boolean;
1073
+ action_hash: string;
938
1074
  }
939
1075
  /**
940
1076
  * Response from verify phone number.
@@ -957,6 +1093,8 @@ interface VerifyPhoneNumberResponse {
957
1093
  sim_swap?: SimSwapInfo;
958
1094
  /** Device swap (IMEI change) check result (when supported by carrier) */
959
1095
  device_swap?: DeviceSwapInfo;
1096
+ /** T-Mobile live-call check outcome (`call` sessions). */
1097
+ live_call?: LiveCallInfo;
960
1098
  /** Same-network signal (Desktop QR, when the desktop prepare stamped network_origin) */
961
1099
  network_check?: NetworkCheck;
962
1100
  /** Parsed phone number components (optional, server-populated) */
@@ -980,6 +1118,15 @@ interface VerifyPhoneNumberResponse {
980
1118
  * release that added it.
981
1119
  */
982
1120
  request_id?: string;
1121
+ /** `'used'` on a step-up session. */
1122
+ passkey?: string;
1123
+ /** Present on a step-up session. */
1124
+ step_up?: StepUpResult;
1125
+ /**
1126
+ * WebAuthn creation options after a carrier verification on a prepare that asked
1127
+ * for passkeys; forward it to the browser to save a passkey.
1128
+ */
1129
+ passkey_enrolment?: PasskeyChallenge;
983
1130
  }
984
1131
 
985
1132
  /**
@@ -1032,40 +1179,6 @@ interface GetPhoneNumberResponse {
1032
1179
  request_id?: string;
1033
1180
  }
1034
1181
 
1035
- /**
1036
- * Response from status polling endpoints.
1037
- *
1038
- * Note: This endpoint does NOT expose phone_number or verification results directly.
1039
- * Sensitive data is only returned via the protected verify/get-phone-number endpoints
1040
- * which require authentication.
1041
- */
1042
- interface StatusResponse {
1043
- /** The session identifier (16-char hex) */
1044
- session_key: string;
1045
- /** Current status of the verification request */
1046
- status: SessionStatus;
1047
- /** Protocol used for authentication (optional) */
1048
- protocol?: ProtocolType;
1049
- /** Session creation timestamp (ISO 8601) */
1050
- created_at: string;
1051
- /** Last status update timestamp (ISO 8601) */
1052
- last_updated: string;
1053
- /** Device info (only present when status is "scanned" or later) */
1054
- device_info?: DeviceInfo;
1055
- /** Grace period expiry time (only present when status is "scanned") */
1056
- grace_expires_at?: string;
1057
- /** Timestamp when the QR code was scanned */
1058
- scanned_at?: string;
1059
- /** Additional metadata (e.g., error reason for failed status) */
1060
- extra?: Record<string, unknown>;
1061
- /**
1062
- * The id of this request, the same value as the `X-Request-ID` response
1063
- * header. Quote it to Glide support. Absent from servers older than the
1064
- * release that added it.
1065
- */
1066
- request_id?: string;
1067
- }
1068
-
1069
1182
  /**
1070
1183
  * Request body for report invocation.
1071
1184
  */
@@ -1158,4 +1271,4 @@ declare function createLogger(config?: LoggerConfig): Logger;
1158
1271
  */
1159
1272
  declare function sanitize(data: unknown): unknown;
1160
1273
 
1161
- export { type ResolvedConfig as $, AuthenticationStrategy as A, BadRequestError as B, CarrierAppUnavailableError as C, type DCQLCredential as D, ErrorCode as E, ForbiddenError as F, type GetPhoneNumberRequest as G, type HttpClient as H, InternalServerError as I, type NetworkOrigin as J, PREPARE_MULTIPLE_MAX as K, type LinkStrategyData as L, type MagicalAuthConfig as M, type NetworkCheck as N, type PhoneNumberDetails as O, type PLMN as P, PhoneNumberMismatchError as Q, type PrepareMultipleRequest as R, type PrepareMultipleResult as S, type PrepareOptions as T, type PrepareRequest as U, type PrepareResponse as V, type PrepareResult as W, type ProtocolType as X, RateLimitError as Y, type ReportInvocationRequest as Z, type ReportInvocationResponse as _, BiometricVerification as a, type RiskLevel as a0, ServiceUnavailableError as a1, type SessionInfo as a2, SessionNotEligibleError as a3, SessionNotFoundError as a4, SessionStatus as a5, type SimSwapFailureReason as a6, type SimSwapInfo as a7, type StatusResponse as a8, type StrategyData as a9, type TS43RequestData as aa, type TS43StrategyData as ab, type Theme as ac, UnauthorizedError as ad, UnsupportedPlatformError as ae, UseCase as af, ValidationError as ag, VerificationRecordError as ah, VerificationRecordErrorCode as ai, type VerifyPhoneNumberRequest as aj, type VerifyPhoneNumberResponse as ak, createErrorFromResponse as al, createLogger as am, defaultHttpClient as an, noopLogger as ao, resolveConfig as ap, sanitize as aq, BrowserMismatchError as b, CarrierNotEligibleError as c, CarrierRejectedError as d, type Challenge as e, type ClientInfo as f, type ConsentData as g, type DCQLCredentialMeta as h, type DCQLQuery as i, DEFAULT_BASE_URL as j, DEFAULT_TIMEOUT as k, type DesktopQRData as l, type DesktopStrategyData as m, DesktopWaitError as n, DeviceBindingError as o, type DeviceInfo as p, type DeviceSwapInfo as q, type ErrorResponse as r, type GetPhoneNumberResponse as s, type HttpRequestOptions as t, type HttpResponse as u, InvalidCredentialError as v, type Logger as w, type LoggerConfig as x, MagicalAuthError as y, MissingBindingCookieError as z };
1274
+ export { type PrepareOptions as $, AuthenticationStrategy as A, BadRequestError as B, type CallOptions as C, type DCQLCredential as D, ErrorCode as E, ForbiddenError as F, type GetPhoneNumberRequest as G, type HttpClient as H, InternalServerError as I, type LiveCallInfo as J, type Logger as K, type LinkStrategyData as L, type LoggerConfig as M, type MagicalAuthConfig as N, MagicalAuthError as O, MissingBindingCookieError as P, type NetworkCheck as Q, type NetworkOrigin as R, type PLMN as S, PREPARE_MULTIPLE_MAX as T, type PasskeyChallenge as U, type PasskeyOption as V, type PasskeyStrategyData as W, type PhoneNumberDetails as X, PhoneNumberMismatchError as Y, type PrepareMultipleRequest as Z, type PrepareMultipleResult as _, BiometricVerification as a, type PrepareRequest as a0, type PrepareResponse as a1, type PrepareResult as a2, type ProtocolType as a3, RateLimitError as a4, type ReportInvocationRequest as a5, type ReportInvocationResponse as a6, type ResolvedConfig as a7, type RiskLevel as a8, ServiceUnavailableError as a9, noopLogger as aA, resolveConfig as aB, sanitize as aC, type SessionInfo as aa, SessionMetadataParentStrategy as ab, SessionNotEligibleError as ac, SessionNotFoundError as ad, SessionStatus as ae, type SimSwapFailureReason as af, type SimSwapInfo as ag, type StatusResponse as ah, type StepUpOption as ai, type StepUpPrepared as aj, type StepUpResult as ak, type StrategyData as al, type TS43RequestData as am, type TS43StrategyData as an, type Theme as ao, UnauthorizedError as ap, UnsupportedPlatformError as aq, UseCase as ar, ValidationError as as, VerificationRecordError as at, VerificationRecordErrorCode as au, type VerifyPhoneNumberRequest as av, type VerifyPhoneNumberResponse as aw, createErrorFromResponse as ax, createLogger as ay, defaultHttpClient as az, BrowserMismatchError as b, type CallStage as c, type CallStrategyData as d, CarrierAppUnavailableError as e, CarrierNotEligibleError as f, CarrierRejectedError as g, CarrierTemporarilyUnavailableError as h, type Challenge as i, type ClientInfo as j, type ConsentData as k, type DCQLCredentialMeta as l, type DCQLQuery as m, DEFAULT_BASE_URL as n, DEFAULT_TIMEOUT as o, type DesktopQRData as p, type DesktopStrategyData as q, DesktopWaitError as r, DeviceBindingError as s, type DeviceInfo as t, type DeviceSwapInfo as u, type ErrorResponse as v, type GetPhoneNumberResponse as w, type HttpRequestOptions as x, type HttpResponse as y, InvalidCredentialError as z };
package/dist/types.d.cts CHANGED
@@ -1 +1 @@
1
- export { A as AuthenticationStrategy, a as BiometricVerification, e as Challenge, f as ClientInfo, g as ConsentData, p as DeviceInfo, E as ErrorCode, r as ErrorResponse, G as GetPhoneNumberRequest, s as GetPhoneNumberResponse, H as HttpClient, t as HttpRequestOptions, u as HttpResponse, w as Logger, x as LoggerConfig, M as MagicalAuthConfig, P as PLMN, R as PrepareMultipleRequest, S as PrepareMultipleResult, T as PrepareOptions, U as PrepareRequest, V as PrepareResponse, X as ProtocolType, Z as ReportInvocationRequest, _ as ReportInvocationResponse, $ as ResolvedConfig, a0 as RiskLevel, a2 as SessionInfo, a5 as SessionStatus, a6 as SimSwapFailureReason, a7 as SimSwapInfo, a8 as StatusResponse, ac as Theme, af as UseCase, aj as VerifyPhoneNumberRequest, ak as VerifyPhoneNumberResponse } from './types-BPuPzIcL.cjs';
1
+ export { A as AuthenticationStrategy, a as BiometricVerification, i as Challenge, j as ClientInfo, k as ConsentData, t as DeviceInfo, E as ErrorCode, v as ErrorResponse, G as GetPhoneNumberRequest, w as GetPhoneNumberResponse, H as HttpClient, x as HttpRequestOptions, y as HttpResponse, K as Logger, M as LoggerConfig, N as MagicalAuthConfig, S as PLMN, Z as PrepareMultipleRequest, _ as PrepareMultipleResult, $ as PrepareOptions, a0 as PrepareRequest, a1 as PrepareResponse, a3 as ProtocolType, a5 as ReportInvocationRequest, a6 as ReportInvocationResponse, a7 as ResolvedConfig, a8 as RiskLevel, aa as SessionInfo, ae as SessionStatus, af as SimSwapFailureReason, ag as SimSwapInfo, ah as StatusResponse, ao as Theme, ar as UseCase, av as VerifyPhoneNumberRequest, aw as VerifyPhoneNumberResponse } from './types-t9HAB-7Q.cjs';
package/dist/types.d.ts CHANGED
@@ -1 +1 @@
1
- export { A as AuthenticationStrategy, a as BiometricVerification, e as Challenge, f as ClientInfo, g as ConsentData, p as DeviceInfo, E as ErrorCode, r as ErrorResponse, G as GetPhoneNumberRequest, s as GetPhoneNumberResponse, H as HttpClient, t as HttpRequestOptions, u as HttpResponse, w as Logger, x as LoggerConfig, M as MagicalAuthConfig, P as PLMN, R as PrepareMultipleRequest, S as PrepareMultipleResult, T as PrepareOptions, U as PrepareRequest, V as PrepareResponse, X as ProtocolType, Z as ReportInvocationRequest, _ as ReportInvocationResponse, $ as ResolvedConfig, a0 as RiskLevel, a2 as SessionInfo, a5 as SessionStatus, a6 as SimSwapFailureReason, a7 as SimSwapInfo, a8 as StatusResponse, ac as Theme, af as UseCase, aj as VerifyPhoneNumberRequest, ak as VerifyPhoneNumberResponse } from './types-BPuPzIcL.js';
1
+ export { A as AuthenticationStrategy, a as BiometricVerification, i as Challenge, j as ClientInfo, k as ConsentData, t as DeviceInfo, E as ErrorCode, v as ErrorResponse, G as GetPhoneNumberRequest, w as GetPhoneNumberResponse, H as HttpClient, x as HttpRequestOptions, y as HttpResponse, K as Logger, M as LoggerConfig, N as MagicalAuthConfig, S as PLMN, Z as PrepareMultipleRequest, _ as PrepareMultipleResult, $ as PrepareOptions, a0 as PrepareRequest, a1 as PrepareResponse, a3 as ProtocolType, a5 as ReportInvocationRequest, a6 as ReportInvocationResponse, a7 as ResolvedConfig, a8 as RiskLevel, aa as SessionInfo, ae as SessionStatus, af as SimSwapFailureReason, ag as SimSwapInfo, ah as StatusResponse, ao as Theme, ar as UseCase, av as VerifyPhoneNumberRequest, aw as VerifyPhoneNumberResponse } from './types-t9HAB-7Q.js';