@glideidentity/glide-be-node-magical-auth 3.0.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.
@@ -123,6 +127,19 @@ type SessionStatus = (typeof SessionStatus)[keyof typeof SessionStatus];
123
127
  * SIM swap risk level.
124
128
  */
125
129
  type RiskLevel = 'RISK_LEVEL_HIGH' | 'RISK_LEVEL_MEDIUM' | 'RISK_LEVEL_LOW' | 'RISK_LEVEL_UNKNOWN';
130
+ /**
131
+ * Device biometric outcome, shared by the verify / get-phone responses and the
132
+ * verification record's `biometric_verification` claim. A value outside this
133
+ * set is kept as sent.
134
+ */
135
+ declare const BiometricVerification: {
136
+ readonly VERIFIED: "VERIFIED";
137
+ readonly FAILED: "FAILED";
138
+ readonly NOT_ENROLLED: "NOT_ENROLLED";
139
+ readonly UNSUPPORTED: "UNSUPPORTED";
140
+ readonly NOT_REQUESTED: "NOT_REQUESTED";
141
+ };
142
+ type BiometricVerification = (typeof BiometricVerification)[keyof typeof BiometricVerification] | (string & {});
126
143
  /**
127
144
  * SIM swap check failure reason.
128
145
  */
@@ -156,6 +173,8 @@ interface ClientInfo {
156
173
  user_agent: string;
157
174
  /** Platform identifier from the end-user's browser (e.g., navigator.platform) */
158
175
  platform?: string;
176
+ /** Privacy mode from the end-user's browser (`private`, `standard`, or `unknown`) */
177
+ privacy_mode?: 'private' | 'standard' | 'unknown';
159
178
  }
160
179
  /**
161
180
  * User consent data for authentication.
@@ -195,6 +214,10 @@ interface SimSwapInfo {
195
214
  carrier_name?: string;
196
215
  /** When the SIM swap check was performed (RFC3339) */
197
216
  checked_at?: string;
217
+ /** Whether a swap occurred within the query window. Omitted when unknown. */
218
+ swapped?: boolean;
219
+ /** Query window in hours used for the swap check. */
220
+ max_age_hours?: number;
198
221
  /** Reason for check failure (only present when checked=false) */
199
222
  reason?: SimSwapFailureReason;
200
223
  }
@@ -226,6 +249,10 @@ interface DeviceSwapInfo {
226
249
  carrier_name?: string;
227
250
  /** When the device swap check was performed (RFC3339) */
228
251
  checked_at?: string;
252
+ /** Whether a swap occurred within the query window. Omitted when unknown. */
253
+ swapped?: boolean;
254
+ /** Query window in hours used for the swap check. */
255
+ max_age_hours?: number;
229
256
  }
230
257
  /**
231
258
  * Parsed components of an E.164 phone number.
@@ -268,6 +295,56 @@ type Theme = string;
268
295
  * Only applies to Link authentication strategy; ignored for TS43/Desktop.
269
296
  */
270
297
  type LinkType = 'app_clip' | 'app_link' | 'headless' | 'web_link';
298
+ /**
299
+ * Server-observed network origin of a prepare request.
300
+ *
301
+ * The `ip` MUST be derived by your backend from the connection it actually sees
302
+ * (e.g. the left-most untrusted hop of a trusted `X-Forwarded-For` chain) —
303
+ * never from a value the end-user's client supplies in the request body or a
304
+ * header it controls. The aggregator trusts this value as-is and uses it only to
305
+ * compute the same-network {@link NetworkCheck}.
306
+ */
307
+ interface NetworkOrigin {
308
+ /**
309
+ * Server-observed IP address (IPv4 or IPv6) of the requesting device.
310
+ * @example "73.92.140.10"
311
+ */
312
+ ip?: string;
313
+ }
314
+ /**
315
+ * Egress-closeness comparison between the desktop (parent) and companion (child)
316
+ * server-observed IPs. Returned on the companion/child prepare response and on
317
+ * the parent's verify-phone-number and get-phone-number, only when the desktop
318
+ * prepare stamped a network origin (`options.network_origin`). On `match:
319
+ * 'unknown'` the comparison could not be made and `family` / `prefix_bits` are
320
+ * absent.
321
+ *
322
+ * This is a SIGNAL for how close the two devices' public egress IPs are as seen
323
+ * by the server — NOT proof of the same physical LAN (an identical egress IP can
324
+ * front an entire NAT/CGNAT or a whole city) — and must never be used as a hard
325
+ * gate. Branch on `match`; the caller owns any threshold on `prefix_bits`.
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
+ }
332
+ interface NetworkCheck {
333
+ /** Branch on this. On 'unknown', family and prefix_bits are absent. */
334
+ match: 'same_ip' | 'same_subnet' | 'different' | 'unknown' | (string & {});
335
+ /** IP family the comparison was performed in: 'ipv4' or 'ipv6'. */
336
+ family?: 'ipv4' | 'ipv6';
337
+ /**
338
+ * Number of matching leading bits between the two egress IPs (0..32 for ipv4,
339
+ * 0..128 for ipv6). Higher = closer egress; the maximum (32 / 128) means an
340
+ * identical egress IP.
341
+ */
342
+ prefix_bits?: number;
343
+ /** Desktop's server-observed egress IP */
344
+ desktop_ip?: string;
345
+ /** Companion's server-observed egress IP */
346
+ companion_ip?: string;
347
+ }
271
348
  /**
272
349
  * Advanced options for prepare requests.
273
350
  */
@@ -289,6 +366,68 @@ interface PrepareOptions {
289
366
  * Only applies to Link authentication strategy; ignored for TS43/Desktop.
290
367
  */
291
368
  link_type?: LinkType;
369
+ /** SIM swap query window in hours (1–2400). */
370
+ sim_swap_max_age_hours?: number;
371
+ /**
372
+ * On Desktop (QR), set on the parent prepare; the phone inherits it.
373
+ * The outcome comes back as `biometric_verification` on verify / get-phone.
374
+ */
375
+ biometric?: boolean;
376
+ /**
377
+ * Server-observed network origin of the requesting device. Stamp this on BOTH
378
+ * prepares to enable the same-network check (`network_check`): on the
379
+ * desktop/parent prepare it is persisted on the session, and on the
380
+ * companion/child prepare (carrying `parent_session_id`) it is compared against
381
+ * the parent's stored IP. Derive the IP server-side — never trust a
382
+ * client-supplied value.
383
+ */
384
+ network_origin?: NetworkOrigin;
385
+ /**
386
+ * Opaque JSON passed through to the branded mobile companion app and
387
+ * rendered there. Stored server-side on the parent session; echoed on the
388
+ * child (QR) prepare response. Object only, <=16KB. Reserved `flow` key
389
+ * (`signin` | `phone_change`) selects the screen.
390
+ */
391
+ mobile_companion_passthrough?: Record<string, unknown>;
392
+ /**
393
+ * Where to send the browser once authentication completes. Selects one of the
394
+ * `completion_redirect_urls` registered on your application; matching is exact
395
+ * per RFC 6749 §3.1.2 and an unregistered value is rejected.
396
+ *
397
+ * Stamp this server-side from your own deployment's configured origin — never
398
+ * from the request `Host` header or any other client-controllable input. If
399
+ * your application registers more than one completion URL, always send it:
400
+ * when omitted the aggregator falls back to the first registered URL, so the
401
+ * browser can land on another deployment's completion page.
402
+ *
403
+ * @example "https://checkout.use1.staging.glideid.app/glide-complete"
404
+ */
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;
292
431
  }
293
432
  /**
294
433
  * Request body for prepare authentication.
@@ -345,8 +484,9 @@ interface PrepareRequest {
345
484
  interface PrepareResult extends PrepareResponse {
346
485
  /**
347
486
  * Frontend binding code for device-bound link protocol sessions.
348
- * Only present when `authentication_strategy === 'link'`.
349
- * 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()`.
350
490
  */
351
491
  feCode?: string;
352
492
  }
@@ -364,6 +504,7 @@ interface PrepareResponse {
364
504
  * - 'ts43': TS43StrategyData - Contains protocol, data with dcql_query
365
505
  * - 'link': LinkStrategyData - Contains url, return_url, status_url, params
366
506
  * - 'desktop': DesktopStrategyData - Contains protocol, data with a single universal QR image and URL
507
+ * - 'call': CallStrategyData - Contains url and status_url
367
508
  */
368
509
  data: StrategyData;
369
510
  /** Visual verification challenge (for desktop strategy) */
@@ -373,6 +514,46 @@ interface PrepareResponse {
373
514
  * session_timeout when provided, otherwise the server-configured default.
374
515
  */
375
516
  session_expires_in_seconds?: number;
517
+ /**
518
+ * Egress-proximity comparison between the desktop (parent) and companion
519
+ * (child) devices. Present only on the companion/child prepare response (the
520
+ * request carrying `options.parent_session_id`), and only when the
521
+ * desktop/parent prepare opted in by stamping `options.network_origin` (the
522
+ * companion stamping its own `network_origin` enables the full comparison).
523
+ * Omitted for flows that do not opt in.
524
+ */
525
+ network_check?: NetworkCheck;
526
+ /**
527
+ * Echo of the opaque passthrough stored on the parent session, returned on
528
+ * the child (companion) prepare. Absent for non-companion flows.
529
+ */
530
+ mobile_companion_passthrough?: Record<string, unknown>;
531
+ /**
532
+ * Normalized carrier name for the resolved network. Present only for callers
533
+ * the gateway has explicitly enabled to receive carrier information (the same
534
+ * per-app gate as `/eligibility`); omitted otherwise to preserve the
535
+ * privacy-by-default contract.
536
+ */
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';
543
+ /**
544
+ * The id of this request, the same value as the `X-Request-ID` response
545
+ * header. Quote it to Glide support. Absent from servers older than the
546
+ * release that added it. The session this creates is `session.session_key`.
547
+ */
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;
376
557
  }
377
558
 
378
559
  /**
@@ -479,186 +660,31 @@ interface DesktopStrategyData {
479
660
  data: DesktopQRData;
480
661
  }
481
662
  /**
482
- * Union type for strategy-specific data.
483
- * The actual type depends on the authentication_strategy value.
484
- */
485
- type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData;
486
-
487
- /**
488
- * Request body for verify phone number.
489
- */
490
- interface VerifyPhoneNumberRequest {
491
- /** Session information from prepare response */
492
- session: SessionInfo;
493
- /** SD-JWT credential string from digital credential */
494
- credential: string;
495
- /** Device binding code for link protocol sessions (from _glide_bind cookie) */
496
- fe_code?: string;
497
- /**
498
- * Base64-encoded DER ECDSA signature for native device binding.
499
- * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
500
- * Only used for native link protocol sessions — web sessions use fe_code instead.
501
- */
502
- signature?: string;
503
- }
504
- /**
505
- * Response from verify phone number.
663
+ * Passkey sign-in strategy data.
664
+ * Used when authentication_strategy is 'passkey'.
506
665
  */
507
- interface VerifyPhoneNumberResponse {
508
- /** The phone number that was verified (E.164 format) */
509
- phone_number: string;
510
- /** Whether the phone number matches the device */
511
- verified: boolean;
512
- /** Audience from TS43 response (when available) */
513
- aud?: string;
514
- /** SIM swap check result (when enabled) */
515
- sim_swap?: SimSwapInfo;
516
- /** Device swap (IMEI change) check result (when supported by carrier) */
517
- device_swap?: DeviceSwapInfo;
518
- /** Parsed phone number components (optional, server-populated) */
519
- phone_number_details?: PhoneNumberDetails;
520
- }
521
-
522
- /**
523
- * Request body for get phone number.
524
- */
525
- interface GetPhoneNumberRequest {
526
- /** Session information from prepare response */
527
- session: SessionInfo;
528
- /** SD-JWT credential string from digital credential */
529
- credential: string;
530
- /** Device binding code for link protocol sessions (from _glide_bind cookie) */
531
- fe_code?: string;
532
- /**
533
- * Base64-encoded DER ECDSA signature for native device binding.
534
- * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
535
- * Only used for native link protocol sessions — web sessions use fe_code instead.
536
- */
537
- signature?: string;
538
- }
539
- /**
540
- * Response from get phone number.
541
- */
542
- interface GetPhoneNumberResponse {
543
- /** The retrieved phone number (E.164 format) */
544
- phone_number: string;
545
- /** Audience from TS43 response (when available) */
546
- aud?: string;
547
- /** SIM swap check result (when enabled) */
548
- sim_swap?: SimSwapInfo;
549
- /** Device swap (IMEI change) check result (when supported by carrier) */
550
- device_swap?: DeviceSwapInfo;
551
- /** Parsed phone number components (optional, server-populated) */
552
- phone_number_details?: PhoneNumberDetails;
553
- }
554
-
555
- /**
556
- * Response from status polling endpoints.
557
- *
558
- * Note: This endpoint does NOT expose phone_number or verification results directly.
559
- * Sensitive data is only returned via the protected verify/get-phone-number endpoints
560
- * which require authentication.
561
- */
562
- interface StatusResponse {
563
- /** The session identifier (16-char hex) */
564
- session_key: string;
565
- /** Current status of the verification request */
566
- status: SessionStatus;
567
- /** Protocol used for authentication (optional) */
568
- protocol?: ProtocolType;
569
- /** Session creation timestamp (ISO 8601) */
570
- created_at: string;
571
- /** Last status update timestamp (ISO 8601) */
572
- last_updated: string;
573
- /** Device info (only present when status is "scanned" or later) */
574
- device_info?: DeviceInfo;
575
- /** Grace period expiry time (only present when status is "scanned") */
576
- grace_expires_at?: string;
577
- /** Timestamp when the QR code was scanned */
578
- scanned_at?: string;
579
- /** Additional metadata (e.g., error reason for failed status) */
580
- extra?: Record<string, unknown>;
581
- }
582
-
583
- /**
584
- * Request body for report invocation.
585
- */
586
- interface ReportInvocationRequest {
587
- /** The session identifier for the invocation */
588
- session_id: string;
589
- }
590
- /**
591
- * Response from report invocation.
592
- *
593
- * The backend returns `{ "success": true }` on 2xx. Invocation recording is
594
- * idempotent — reporting the same `session_id` twice also returns
595
- * `{ success: true }`.
596
- */
597
- interface ReportInvocationResponse {
598
- /** Whether the invocation was recorded successfully. */
599
- success: boolean;
666
+ interface PasskeyStrategyData {
667
+ passkey: {
668
+ challenge_key: string;
669
+ /** PublicKeyCredentialRequestOptionsJSON for navigator.credentials.get. */
670
+ public_key: Record<string, unknown>;
671
+ };
600
672
  }
601
-
602
673
  /**
603
- * Configuration for {@link createLogger}.
674
+ * Call strategy data.
675
+ * Used when authentication_strategy is 'call'.
604
676
  */
605
- interface LoggerConfig {
606
- /**
607
- * Enable logging. When `false` (default) the returned logger is silent at
608
- * every level. Set to `true` to route output through `console.*`. Partners
609
- * with their own structured logger (Pino, Winston, Bunyan, Datadog, etc.)
610
- * should pass it via `MagicalAuthConfig.logger` instead — this factory is
611
- * intended for local development and quick smoke tests.
612
- */
613
- debug?: boolean;
614
- /**
615
- * Prefix prepended to every log message. Default: `[GlideMagicalAuth]`.
616
- */
617
- prefix?: string;
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;
618
682
  }
619
-
620
- /**
621
- * Creates a console logger with PII sanitization and a configurable prefix.
622
- *
623
- * Default-silent — call with no args (or `debug: false`) and every level is
624
- * a no-op. Set `debug: true` to opt into console output. Phone numbers,
625
- * JWTs, and explicit `session_key=…` values are auto-masked; object fields
626
- * named `phone_number`, `credential`, `token`, `password`, `secret`, or
627
- * `fe_code` are redacted to `[REDACTED]`.
628
- *
629
- * @example
630
- * ```typescript
631
- * import { MagicalAuthClient, createLogger } from '@glideidentity/glide-be-node-magical-auth';
632
- *
633
- * const client = new MagicalAuthClient({
634
- * clientId: process.env.GLIDE_CLIENT_ID!,
635
- * clientSecret: process.env.GLIDE_CLIENT_SECRET!,
636
- * logger: createLogger({ debug: true }),
637
- * });
638
- * ```
639
- */
640
- declare function createLogger(config?: LoggerConfig): Logger;
641
683
  /**
642
- * Recursively redacts PII from a log payload (string, array, or object).
643
- * Exported for partners who want the same redaction in their own logger.
644
- *
645
- * Regex ordering matters: JWT first (most specific — base64url segments
646
- * may contain digit runs that would otherwise be eaten by `PHONE_RE`),
647
- * then `session_key=…` assignment context, then the catchall phone
648
- * regex. Reordering this loses redaction guarantees for JWTs whose
649
- * payloads encode long all-numeric strings.
650
- *
651
- * Sensitive object fields (`SENSITIVE`) are replaced in full with
652
- * `[REDACTED]` regardless of value type — strings, objects, arrays, or
653
- * primitives. This prevents nested-secret leaks like
654
- * `{ secret: { value: '<real>' } }` slipping through because the inner
655
- * structure happens not to match any string regex.
656
- *
657
- * `sanitize()` is cycle-safe: a `WeakSet` of already-visited objects
658
- * short-circuits to `'[Circular]'` so a circular log payload (which
659
- * `console.log` itself handles gracefully) never throws `RangeError`.
684
+ * Union type for strategy-specific data.
685
+ * The actual type depends on the authentication_strategy value.
660
686
  */
661
- declare function sanitize(data: unknown): unknown;
687
+ type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData | CallStrategyData | PasskeyStrategyData;
662
688
 
663
689
  /**
664
690
  * Error codes returned by the Magical Auth API.
@@ -672,6 +698,9 @@ declare const ErrorCode: {
672
698
  readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
673
699
  readonly INVALID_VERIFICATION: "INVALID_VERIFICATION";
674
700
  readonly CARRIER_NOT_ELIGIBLE: "CARRIER_NOT_ELIGIBLE";
701
+ readonly CARRIER_REJECTED: "CARRIER_REJECTED";
702
+ readonly CARRIER_APP_UNAVAILABLE: "CARRIER_APP_UNAVAILABLE";
703
+ readonly CARRIER_TEMPORARILY_UNAVAILABLE: "CARRIER_TEMPORARILY_UNAVAILABLE";
675
704
  readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
676
705
  readonly PHONE_NUMBER_MISMATCH: "PHONE_NUMBER_MISMATCH";
677
706
  readonly INVALID_CREDENTIAL_FORMAT: "INVALID_CREDENTIAL_FORMAT";
@@ -696,6 +725,7 @@ interface ErrorResponse {
696
725
  message: string;
697
726
  status?: number;
698
727
  request_id?: string;
728
+ session_key?: string;
699
729
  timestamp?: string;
700
730
  trace_id?: string;
701
731
  span_id?: string;
@@ -718,9 +748,17 @@ declare class MagicalAuthError extends Error {
718
748
  */
719
749
  readonly status: number;
720
750
  /**
721
- * Request ID for debugging/support.
751
+ * The id of this request, the same value as the `X-Request-ID` response
752
+ * header. Quote it to Glide support.
722
753
  */
723
754
  readonly requestId?: string;
755
+ /**
756
+ * The session the failed request was about, once the server had read it from
757
+ * the request. Undefined when the request failed before naming a session, on
758
+ * operations that have none (eligibility, prepare), and from servers older
759
+ * than the release that added it.
760
+ */
761
+ readonly sessionKey?: string;
724
762
  /**
725
763
  * Additional error details.
726
764
  */
@@ -777,6 +815,32 @@ declare class SessionNotFoundError extends MagicalAuthError {
777
815
  declare class CarrierNotEligibleError extends MagicalAuthError {
778
816
  constructor(message?: string, requestId?: string);
779
817
  }
818
+ /**
819
+ * Carrier rejected a device-bound (link/desktop) authentication request.
820
+ *
821
+ * Surfaced at verify / get-phone-number when the carrier (or a pipeline stage)
822
+ * failed during an OAuth-callback-driven flow. The reason is carried in
823
+ * `details`: `carrier_error` (a code safe to expose), `carrier_error_description`
824
+ * (truncated to 200 chars), and optionally `stage` and `error_code` for
825
+ * non-`?error=` pipeline failures.
826
+ */
827
+ declare class CarrierRejectedError extends MagicalAuthError {
828
+ constructor(message?: string, requestId?: string, details?: Record<string, unknown>);
829
+ }
830
+ /**
831
+ * Desktop (QR): the phone that scanned the code has no working carrier app.
832
+ * Terminal for the session; start a new QR.
833
+ */
834
+ declare class CarrierAppUnavailableError extends MagicalAuthError {
835
+ constructor(message?: string, requestId?: string, details?: Record<string, unknown>);
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
+ }
780
844
  /**
781
845
  * Platform not supported for authentication.
782
846
  */
@@ -862,6 +926,7 @@ declare class DesktopWaitError extends MagicalAuthError {
862
926
  session_status: string;
863
927
  retry: boolean;
864
928
  session_expires_in_seconds: number;
929
+ request_id?: string;
865
930
  };
866
931
  constructor(waitResponse: {
867
932
  status: 'waiting';
@@ -870,8 +935,37 @@ declare class DesktopWaitError extends MagicalAuthError {
870
935
  session_status: string;
871
936
  retry: boolean;
872
937
  session_expires_in_seconds: number;
938
+ request_id?: string;
873
939
  });
874
940
  }
941
+ /**
942
+ * Codes of {@link VerificationRecordError} (identical strings in every Glide backend SDK).
943
+ */
944
+ declare const VerificationRecordErrorCode: {
945
+ readonly MALFORMED: "MALFORMED";
946
+ readonly DISALLOWED_HEADER: "DISALLOWED_HEADER";
947
+ readonly UNKNOWN_KEY: "UNKNOWN_KEY";
948
+ readonly BAD_SIGNATURE: "BAD_SIGNATURE";
949
+ readonly WRONG_ISSUER: "WRONG_ISSUER";
950
+ readonly WRONG_AUDIENCE: "WRONG_AUDIENCE";
951
+ readonly EXPIRED: "EXPIRED";
952
+ readonly NOT_YET_VALID: "NOT_YET_VALID";
953
+ readonly NONCE_MISMATCH: "NONCE_MISMATCH";
954
+ readonly ORIGIN_MISMATCH: "ORIGIN_MISMATCH";
955
+ readonly UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION";
956
+ readonly REVOKED_KEY: "REVOKED_KEY";
957
+ readonly RECORD_UNAVAILABLE: "RECORD_UNAVAILABLE";
958
+ readonly STEP_UP_REJECTED: "STEP_UP_REJECTED";
959
+ };
960
+ type VerificationRecordErrorCode = (typeof VerificationRecordErrorCode)[keyof typeof VerificationRecordErrorCode];
961
+ /**
962
+ * Thrown by `verifyVerificationRecord` when a verification record fails any check.
963
+ * Raised locally, so `status` is 0.
964
+ */
965
+ declare class VerificationRecordError extends MagicalAuthError {
966
+ readonly code: VerificationRecordErrorCode;
967
+ constructor(code: VerificationRecordErrorCode, message: string);
968
+ }
875
969
  /**
876
970
  * Creates the appropriate error class instance from an API error response.
877
971
  * @param response - The error response from the API
@@ -880,4 +974,301 @@ declare class DesktopWaitError extends MagicalAuthError {
880
974
  */
881
975
  declare function createErrorFromResponse(response: ErrorResponse, headers?: Headers): MagicalAuthError;
882
976
 
883
- export { type StatusResponse as $, AuthenticationStrategy as A, BadRequestError as B, CarrierNotEligibleError as C, type DCQLCredential as D, ErrorCode as E, ForbiddenError as F, type GetPhoneNumberRequest as G, type HttpClient as H, InternalServerError as I, type PrepareResponse as J, type PrepareResult as K, type LinkStrategyData as L, type MagicalAuthConfig as M, type ProtocolType as N, type ReportInvocationRequest as O, type PLMN as P, type ReportInvocationResponse as Q, RateLimitError as R, type ResolvedConfig as S, type RiskLevel as T, ServiceUnavailableError as U, type SessionInfo as V, SessionNotEligibleError as W, SessionNotFoundError as X, SessionStatus as Y, type SimSwapFailureReason as Z, type SimSwapInfo as _, BrowserMismatchError as a, type StrategyData as a0, type TS43RequestData as a1, type TS43StrategyData as a2, type Theme as a3, UnauthorizedError as a4, UnsupportedPlatformError as a5, UseCase as a6, ValidationError as a7, type VerifyPhoneNumberRequest as a8, type VerifyPhoneNumberResponse as a9, createErrorFromResponse as aa, createLogger as ab, defaultHttpClient as ac, noopLogger as ad, resolveConfig as ae, sanitize as af, type Challenge as b, type ClientInfo as c, type ConsentData as d, type DCQLCredentialMeta as e, type DCQLQuery as f, DEFAULT_BASE_URL as g, DEFAULT_TIMEOUT as h, type DesktopQRData as i, type DesktopStrategyData as j, DesktopWaitError as k, DeviceBindingError as l, type DeviceInfo as m, type DeviceSwapInfo as n, type ErrorResponse as o, type GetPhoneNumberResponse as p, type HttpRequestOptions as q, type HttpResponse as r, InvalidCredentialError as s, type Logger as t, type LoggerConfig as u, MagicalAuthError as v, MissingBindingCookieError as w, PhoneNumberMismatchError as x, type PrepareOptions as y, type PrepareRequest as z };
977
+ declare const PREPARE_MULTIPLE_MAX = 10;
978
+ /**
979
+ * `nonce` is excluded on purpose: there is no per-number slot for one, and a
980
+ * single shared nonce across sessions would defeat replay protection. Each
981
+ * inner prepare generates its own.
982
+ */
983
+ interface PrepareMultipleRequest extends Omit<PrepareRequest, 'phone_number' | 'nonce'> {
984
+ phone_numbers: string[];
985
+ }
986
+ /**
987
+ * `phone_number` is deliberately outside `result` so that forwarding `result`
988
+ * to a client carries no PII. Note that `result` still contains `feCode` on the
989
+ * link strategy, which must never reach browser JavaScript.
990
+ */
991
+ type PrepareMultipleResult = {
992
+ phone_number: string;
993
+ ok: true;
994
+ result: PrepareResult;
995
+ } | {
996
+ phone_number: string;
997
+ ok: false;
998
+ error: MagicalAuthError;
999
+ };
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
+
1050
+ /**
1051
+ * Request body for verify phone number.
1052
+ */
1053
+ interface VerifyPhoneNumberRequest {
1054
+ /** Session information from prepare response */
1055
+ session: SessionInfo;
1056
+ /** SD-JWT credential string from digital credential */
1057
+ credential: string;
1058
+ /** Device binding code for link protocol sessions (from _glide_bind cookie) */
1059
+ fe_code?: string;
1060
+ /**
1061
+ * Base64-encoded DER ECDSA signature for native device binding.
1062
+ * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
1063
+ * Only used for native link protocol sessions — web sessions use fe_code instead.
1064
+ */
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;
1074
+ }
1075
+ /**
1076
+ * Response from verify phone number.
1077
+ */
1078
+ interface VerifyPhoneNumberResponse {
1079
+ /** The phone number that was verified (E.164 format) */
1080
+ phone_number: string;
1081
+ /** Whether the phone number matches the device */
1082
+ verified: boolean;
1083
+ /**
1084
+ * The session's prepare nonce, equal to the record's `nonce` claim. Absent
1085
+ * from servers older than the release that added it.
1086
+ */
1087
+ nonce?: string;
1088
+ /** Audience from TS43 response (when available) */
1089
+ aud?: string;
1090
+ /** Equals the record's `biometric_verification` claim. */
1091
+ biometric_verification: BiometricVerification;
1092
+ /** SIM swap check result (when enabled) */
1093
+ sim_swap?: SimSwapInfo;
1094
+ /** Device swap (IMEI change) check result (when supported by carrier) */
1095
+ device_swap?: DeviceSwapInfo;
1096
+ /** T-Mobile live-call check outcome (`call` sessions). */
1097
+ live_call?: LiveCallInfo;
1098
+ /** Same-network signal (Desktop QR, when the desktop prepare stamped network_origin) */
1099
+ network_check?: NetworkCheck;
1100
+ /** Parsed phone number components (optional, server-populated) */
1101
+ phone_number_details?: PhoneNumberDetails;
1102
+ /**
1103
+ * Glide-signed compact JWS of this result. Check it with
1104
+ * `MagicalAuthClient.verifyVerificationRecord` before trusting it.
1105
+ */
1106
+ verification_record?: string;
1107
+ /** Whether a record was issued; absent from servers without records. */
1108
+ verification_record_status?: 'signed' | 'unavailable' | (string & {});
1109
+ /**
1110
+ * The session this response is about (the key prepare returned), so a result
1111
+ * can be stored or logged without the request. Absent from servers older than
1112
+ * the release that added it.
1113
+ */
1114
+ session_key?: string;
1115
+ /**
1116
+ * The id of this request, the same value as the `X-Request-ID` response
1117
+ * header. Quote it to Glide support. Absent from servers older than the
1118
+ * release that added it.
1119
+ */
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;
1130
+ }
1131
+
1132
+ /**
1133
+ * Request body for get phone number.
1134
+ */
1135
+ interface GetPhoneNumberRequest {
1136
+ /** Session information from prepare response */
1137
+ session: SessionInfo;
1138
+ /** SD-JWT credential string from digital credential */
1139
+ credential: string;
1140
+ /** Device binding code for link protocol sessions (from _glide_bind cookie) */
1141
+ fe_code?: string;
1142
+ /**
1143
+ * Base64-encoded DER ECDSA signature for native device binding.
1144
+ * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
1145
+ * Only used for native link protocol sessions — web sessions use fe_code instead.
1146
+ */
1147
+ signature?: string;
1148
+ }
1149
+ /**
1150
+ * Response from get phone number.
1151
+ */
1152
+ interface GetPhoneNumberResponse {
1153
+ /** The retrieved phone number (E.164 format) */
1154
+ phone_number: string;
1155
+ /** The session's prepare nonce. Absent from servers older than the release that added it. */
1156
+ nonce?: string;
1157
+ /** Audience from TS43 response (when available) */
1158
+ aud?: string;
1159
+ biometric_verification: BiometricVerification;
1160
+ /** SIM swap check result (when enabled) */
1161
+ sim_swap?: SimSwapInfo;
1162
+ /** Device swap (IMEI change) check result (when supported by carrier) */
1163
+ device_swap?: DeviceSwapInfo;
1164
+ /** Same-network signal (Desktop QR, when the desktop prepare stamped network_origin) */
1165
+ network_check?: NetworkCheck;
1166
+ /** Parsed phone number components (optional, server-populated) */
1167
+ phone_number_details?: PhoneNumberDetails;
1168
+ /**
1169
+ * The session this response is about (the key prepare returned), so a result
1170
+ * can be stored or logged without the request. Absent from servers older than
1171
+ * the release that added it.
1172
+ */
1173
+ session_key?: string;
1174
+ /**
1175
+ * The id of this request, the same value as the `X-Request-ID` response
1176
+ * header. Quote it to Glide support. Absent from servers older than the
1177
+ * release that added it.
1178
+ */
1179
+ request_id?: string;
1180
+ }
1181
+
1182
+ /**
1183
+ * Request body for report invocation.
1184
+ */
1185
+ interface ReportInvocationRequest {
1186
+ /** The session identifier for the invocation */
1187
+ session_id: string;
1188
+ }
1189
+ /**
1190
+ * Response from report invocation.
1191
+ *
1192
+ * The backend returns `{ "success": true }` on 2xx. Invocation recording is
1193
+ * idempotent — reporting the same `session_id` twice also returns
1194
+ * `{ success: true }`.
1195
+ */
1196
+ interface ReportInvocationResponse {
1197
+ /** Whether the invocation was recorded successfully. */
1198
+ success: boolean;
1199
+ /**
1200
+ * The session this response is about (the key prepare returned), so a result
1201
+ * can be stored or logged without the request. Absent from servers older than
1202
+ * the release that added it.
1203
+ */
1204
+ session_key?: string;
1205
+ /**
1206
+ * The id of this request, the same value as the `X-Request-ID` response
1207
+ * header. Quote it to Glide support. Absent from servers older than the
1208
+ * release that added it.
1209
+ */
1210
+ request_id?: string;
1211
+ }
1212
+
1213
+ /**
1214
+ * Configuration for {@link createLogger}.
1215
+ */
1216
+ interface LoggerConfig {
1217
+ /**
1218
+ * Enable logging. When `false` (default) the returned logger is silent at
1219
+ * every level. Set to `true` to route output through `console.*`. Partners
1220
+ * with their own structured logger (Pino, Winston, Bunyan, Datadog, etc.)
1221
+ * should pass it via `MagicalAuthConfig.logger` instead — this factory is
1222
+ * intended for local development and quick smoke tests.
1223
+ */
1224
+ debug?: boolean;
1225
+ /**
1226
+ * Prefix prepended to every log message. Default: `[GlideMagicalAuth]`.
1227
+ */
1228
+ prefix?: string;
1229
+ }
1230
+
1231
+ /**
1232
+ * Creates a console logger with PII sanitization and a configurable prefix.
1233
+ *
1234
+ * Default-silent — call with no args (or `debug: false`) and every level is
1235
+ * a no-op. Set `debug: true` to opt into console output. Phone numbers,
1236
+ * JWTs, and explicit `session_key=…` values are auto-masked; object fields
1237
+ * named `phone_number`, `credential`, `token`, `password`, `secret`, or
1238
+ * `fe_code` are redacted to `[REDACTED]`.
1239
+ *
1240
+ * @example
1241
+ * ```typescript
1242
+ * import { MagicalAuthClient, createLogger } from '@glideidentity/glide-be-node-magical-auth';
1243
+ *
1244
+ * const client = new MagicalAuthClient({
1245
+ * clientId: process.env.GLIDE_CLIENT_ID!,
1246
+ * clientSecret: process.env.GLIDE_CLIENT_SECRET!,
1247
+ * logger: createLogger({ debug: true }),
1248
+ * });
1249
+ * ```
1250
+ */
1251
+ declare function createLogger(config?: LoggerConfig): Logger;
1252
+ /**
1253
+ * Recursively redacts PII from a log payload (string, array, or object).
1254
+ * Exported for partners who want the same redaction in their own logger.
1255
+ *
1256
+ * Regex ordering matters: JWT first (most specific — base64url segments
1257
+ * may contain digit runs that would otherwise be eaten by `PHONE_RE`),
1258
+ * then `session_key=…` assignment context, then the catchall phone
1259
+ * regex. Reordering this loses redaction guarantees for JWTs whose
1260
+ * payloads encode long all-numeric strings.
1261
+ *
1262
+ * Sensitive object fields (`SENSITIVE`) are replaced in full with
1263
+ * `[REDACTED]` regardless of value type — strings, objects, arrays, or
1264
+ * primitives. This prevents nested-secret leaks like
1265
+ * `{ secret: { value: '<real>' } }` slipping through because the inner
1266
+ * structure happens not to match any string regex.
1267
+ *
1268
+ * `sanitize()` is cycle-safe: a `WeakSet` of already-visited objects
1269
+ * short-circuits to `'[Circular]'` so a circular log payload (which
1270
+ * `console.log` itself handles gracefully) never throws `RangeError`.
1271
+ */
1272
+ declare function sanitize(data: unknown): unknown;
1273
+
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 };