@glideidentity/glide-be-node-magical-auth 2.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.
@@ -123,6 +123,19 @@ type SessionStatus = (typeof SessionStatus)[keyof typeof SessionStatus];
123
123
  * SIM swap risk level.
124
124
  */
125
125
  type RiskLevel = 'RISK_LEVEL_HIGH' | 'RISK_LEVEL_MEDIUM' | 'RISK_LEVEL_LOW' | 'RISK_LEVEL_UNKNOWN';
126
+ /**
127
+ * Device biometric outcome, shared by the verify / get-phone responses and the
128
+ * verification record's `biometric_verification` claim. A value outside this
129
+ * set is kept as sent.
130
+ */
131
+ declare const BiometricVerification: {
132
+ readonly VERIFIED: "VERIFIED";
133
+ readonly FAILED: "FAILED";
134
+ readonly NOT_ENROLLED: "NOT_ENROLLED";
135
+ readonly UNSUPPORTED: "UNSUPPORTED";
136
+ readonly NOT_REQUESTED: "NOT_REQUESTED";
137
+ };
138
+ type BiometricVerification = (typeof BiometricVerification)[keyof typeof BiometricVerification] | (string & {});
126
139
  /**
127
140
  * SIM swap check failure reason.
128
141
  */
@@ -156,6 +169,8 @@ interface ClientInfo {
156
169
  user_agent: string;
157
170
  /** Platform identifier from the end-user's browser (e.g., navigator.platform) */
158
171
  platform?: string;
172
+ /** Privacy mode from the end-user's browser (`private`, `standard`, or `unknown`) */
173
+ privacy_mode?: 'private' | 'standard' | 'unknown';
159
174
  }
160
175
  /**
161
176
  * User consent data for authentication.
@@ -195,6 +210,10 @@ interface SimSwapInfo {
195
210
  carrier_name?: string;
196
211
  /** When the SIM swap check was performed (RFC3339) */
197
212
  checked_at?: string;
213
+ /** Whether a swap occurred within the query window. Omitted when unknown. */
214
+ swapped?: boolean;
215
+ /** Query window in hours used for the swap check. */
216
+ max_age_hours?: number;
198
217
  /** Reason for check failure (only present when checked=false) */
199
218
  reason?: SimSwapFailureReason;
200
219
  }
@@ -226,6 +245,10 @@ interface DeviceSwapInfo {
226
245
  carrier_name?: string;
227
246
  /** When the device swap check was performed (RFC3339) */
228
247
  checked_at?: string;
248
+ /** Whether a swap occurred within the query window. Omitted when unknown. */
249
+ swapped?: boolean;
250
+ /** Query window in hours used for the swap check. */
251
+ max_age_hours?: number;
229
252
  }
230
253
  /**
231
254
  * Parsed components of an E.164 phone number.
@@ -268,6 +291,51 @@ type Theme = string;
268
291
  * Only applies to Link authentication strategy; ignored for TS43/Desktop.
269
292
  */
270
293
  type LinkType = 'app_clip' | 'app_link' | 'headless' | 'web_link';
294
+ /**
295
+ * Server-observed network origin of a prepare request.
296
+ *
297
+ * The `ip` MUST be derived by your backend from the connection it actually sees
298
+ * (e.g. the left-most untrusted hop of a trusted `X-Forwarded-For` chain) —
299
+ * never from a value the end-user's client supplies in the request body or a
300
+ * header it controls. The aggregator trusts this value as-is and uses it only to
301
+ * compute the same-network {@link NetworkCheck}.
302
+ */
303
+ interface NetworkOrigin {
304
+ /**
305
+ * Server-observed IP address (IPv4 or IPv6) of the requesting device.
306
+ * @example "73.92.140.10"
307
+ */
308
+ ip?: string;
309
+ }
310
+ /**
311
+ * Egress-closeness comparison between the desktop (parent) and companion (child)
312
+ * server-observed IPs. Returned on the companion/child prepare response and on
313
+ * the parent's verify-phone-number and get-phone-number, only when the desktop
314
+ * prepare stamped a network origin (`options.network_origin`). On `match:
315
+ * 'unknown'` the comparison could not be made and `family` / `prefix_bits` are
316
+ * absent.
317
+ *
318
+ * This is a SIGNAL for how close the two devices' public egress IPs are as seen
319
+ * by the server — NOT proof of the same physical LAN (an identical egress IP can
320
+ * front an entire NAT/CGNAT or a whole city) — and must never be used as a hard
321
+ * gate. Branch on `match`; the caller owns any threshold on `prefix_bits`.
322
+ */
323
+ interface NetworkCheck {
324
+ /** Branch on this. On 'unknown', family and prefix_bits are absent. */
325
+ match: 'same_ip' | 'same_subnet' | 'different' | 'unknown' | (string & {});
326
+ /** IP family the comparison was performed in: 'ipv4' or 'ipv6'. */
327
+ family?: 'ipv4' | 'ipv6';
328
+ /**
329
+ * Number of matching leading bits between the two egress IPs (0..32 for ipv4,
330
+ * 0..128 for ipv6). Higher = closer egress; the maximum (32 / 128) means an
331
+ * identical egress IP.
332
+ */
333
+ prefix_bits?: number;
334
+ /** Desktop's server-observed egress IP */
335
+ desktop_ip?: string;
336
+ /** Companion's server-observed egress IP */
337
+ companion_ip?: string;
338
+ }
271
339
  /**
272
340
  * Advanced options for prepare requests.
273
341
  */
@@ -289,6 +357,43 @@ interface PrepareOptions {
289
357
  * Only applies to Link authentication strategy; ignored for TS43/Desktop.
290
358
  */
291
359
  link_type?: LinkType;
360
+ /** SIM swap query window in hours (1–2400). */
361
+ sim_swap_max_age_hours?: number;
362
+ /**
363
+ * On Desktop (QR), set on the parent prepare; the phone inherits it.
364
+ * The outcome comes back as `biometric_verification` on verify / get-phone.
365
+ */
366
+ biometric?: boolean;
367
+ /**
368
+ * Server-observed network origin of the requesting device. Stamp this on BOTH
369
+ * prepares to enable the same-network check (`network_check`): on the
370
+ * desktop/parent prepare it is persisted on the session, and on the
371
+ * companion/child prepare (carrying `parent_session_id`) it is compared against
372
+ * the parent's stored IP. Derive the IP server-side — never trust a
373
+ * client-supplied value.
374
+ */
375
+ network_origin?: NetworkOrigin;
376
+ /**
377
+ * Opaque JSON passed through to the branded mobile companion app and
378
+ * rendered there. Stored server-side on the parent session; echoed on the
379
+ * child (QR) prepare response. Object only, <=16KB. Reserved `flow` key
380
+ * (`signin` | `phone_change`) selects the screen.
381
+ */
382
+ mobile_companion_passthrough?: Record<string, unknown>;
383
+ /**
384
+ * Where to send the browser once authentication completes. Selects one of the
385
+ * `completion_redirect_urls` registered on your application; matching is exact
386
+ * per RFC 6749 §3.1.2 and an unregistered value is rejected.
387
+ *
388
+ * Stamp this server-side from your own deployment's configured origin — never
389
+ * from the request `Host` header or any other client-controllable input. If
390
+ * your application registers more than one completion URL, always send it:
391
+ * when omitted the aggregator falls back to the first registered URL, so the
392
+ * browser can land on another deployment's completion page.
393
+ *
394
+ * @example "https://checkout.use1.staging.glideid.app/glide-complete"
395
+ */
396
+ completion_redirect_url?: string;
292
397
  }
293
398
  /**
294
399
  * Request body for prepare authentication.
@@ -319,6 +424,10 @@ interface PrepareRequest {
319
424
  * Must contain the end-user's browser user agent from your frontend.
320
425
  */
321
426
  client_info: ClientInfo;
427
+ /** Optional authentication strategy override. */
428
+ authentication_strategy?: Exclude<AuthenticationStrategy, ''>;
429
+ /** Optional session timeout in seconds (60-900). */
430
+ session_timeout?: number;
322
431
  /**
323
432
  * SHA256 hash of fe_code for device binding (link protocol).
324
433
  * Set automatically by the SDK — callers should not set this directly.
@@ -364,6 +473,38 @@ interface PrepareResponse {
364
473
  data: StrategyData;
365
474
  /** Visual verification challenge (for desktop strategy) */
366
475
  challenge?: Challenge;
476
+ /**
477
+ * The effective TTL applied to this session, in seconds. Equals the requested
478
+ * session_timeout when provided, otherwise the server-configured default.
479
+ */
480
+ session_expires_in_seconds?: number;
481
+ /**
482
+ * Egress-proximity comparison between the desktop (parent) and companion
483
+ * (child) devices. Present only on the companion/child prepare response (the
484
+ * request carrying `options.parent_session_id`), and only when the
485
+ * desktop/parent prepare opted in by stamping `options.network_origin` (the
486
+ * companion stamping its own `network_origin` enables the full comparison).
487
+ * Omitted for flows that do not opt in.
488
+ */
489
+ network_check?: NetworkCheck;
490
+ /**
491
+ * Echo of the opaque passthrough stored on the parent session, returned on
492
+ * the child (companion) prepare. Absent for non-companion flows.
493
+ */
494
+ mobile_companion_passthrough?: Record<string, unknown>;
495
+ /**
496
+ * Normalized carrier name for the resolved network. Present only for callers
497
+ * the gateway has explicitly enabled to receive carrier information (the same
498
+ * per-app gate as `/eligibility`); omitted otherwise to preserve the
499
+ * privacy-by-default contract.
500
+ */
501
+ carrier_name?: string;
502
+ /**
503
+ * The id of this request, the same value as the `X-Request-ID` response
504
+ * header. Quote it to Glide support. Absent from servers older than the
505
+ * release that added it. The session this creates is `session.session_key`.
506
+ */
507
+ request_id?: string;
367
508
  }
368
509
 
369
510
  /**
@@ -475,166 +616,6 @@ interface DesktopStrategyData {
475
616
  */
476
617
  type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData;
477
618
 
478
- /**
479
- * Request body for verify phone number.
480
- */
481
- interface VerifyPhoneNumberRequest {
482
- /** Session information from prepare response */
483
- session: SessionInfo;
484
- /** SD-JWT credential string from digital credential */
485
- credential: string;
486
- /** Device binding code for link protocol sessions (from _glide_bind cookie) */
487
- fe_code?: string;
488
- /**
489
- * Base64-encoded DER ECDSA signature for native device binding.
490
- * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
491
- * Only used for native link protocol sessions — web sessions use fe_code instead.
492
- */
493
- signature?: string;
494
- }
495
- /**
496
- * Response from verify phone number.
497
- */
498
- interface VerifyPhoneNumberResponse {
499
- /** The phone number that was verified (E.164 format) */
500
- phone_number: string;
501
- /** Whether the phone number matches the device */
502
- verified: boolean;
503
- /** Audience from TS43 response (when available) */
504
- aud?: string;
505
- /** SIM swap check result (when enabled) */
506
- sim_swap?: SimSwapInfo;
507
- /** Device swap (IMEI change) check result (when supported by carrier) */
508
- device_swap?: DeviceSwapInfo;
509
- /** Parsed phone number components (optional, server-populated) */
510
- phone_number_details?: PhoneNumberDetails;
511
- }
512
-
513
- /**
514
- * Request body for get phone number.
515
- */
516
- interface GetPhoneNumberRequest {
517
- /** Session information from prepare response */
518
- session: SessionInfo;
519
- /** SD-JWT credential string from digital credential */
520
- credential: string;
521
- /** Device binding code for link protocol sessions (from _glide_bind cookie) */
522
- fe_code?: string;
523
- /**
524
- * Base64-encoded DER ECDSA signature for native device binding.
525
- * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
526
- * Only used for native link protocol sessions — web sessions use fe_code instead.
527
- */
528
- signature?: string;
529
- }
530
- /**
531
- * Response from get phone number.
532
- */
533
- interface GetPhoneNumberResponse {
534
- /** The retrieved phone number (E.164 format) */
535
- phone_number: string;
536
- /** Audience from TS43 response (when available) */
537
- aud?: string;
538
- /** SIM swap check result (when enabled) */
539
- sim_swap?: SimSwapInfo;
540
- /** Device swap (IMEI change) check result (when supported by carrier) */
541
- device_swap?: DeviceSwapInfo;
542
- /** Parsed phone number components (optional, server-populated) */
543
- phone_number_details?: PhoneNumberDetails;
544
- }
545
-
546
- /**
547
- * Response from status polling endpoints.
548
- *
549
- * Note: This endpoint does NOT expose phone_number or verification results directly.
550
- * Sensitive data is only returned via the protected verify/get-phone-number endpoints
551
- * which require authentication.
552
- */
553
- interface StatusResponse {
554
- /** The session identifier (16-char hex) */
555
- session_key: string;
556
- /** Current status of the verification request */
557
- status: SessionStatus;
558
- /** Protocol used for authentication (optional) */
559
- protocol?: ProtocolType;
560
- /** Session creation timestamp (ISO 8601) */
561
- created_at: string;
562
- /** Last status update timestamp (ISO 8601) */
563
- last_updated: string;
564
- /** Device info (only present when status is "scanned" or later) */
565
- device_info?: DeviceInfo;
566
- /** Grace period expiry time (only present when status is "scanned") */
567
- grace_expires_at?: string;
568
- /** Timestamp when the QR code was scanned */
569
- scanned_at?: string;
570
- /** Additional metadata (e.g., error reason for failed status) */
571
- extra?: Record<string, unknown>;
572
- }
573
-
574
- /**
575
- * Request body for report invocation.
576
- */
577
- interface ReportInvocationRequest {
578
- /** The session identifier for the invocation */
579
- session_id: string;
580
- }
581
- /**
582
- * Response from report invocation.
583
- *
584
- * The backend returns `{ "success": true }` on 2xx. Invocation recording is
585
- * idempotent — reporting the same `session_id` twice also returns
586
- * `{ success: true }`.
587
- */
588
- interface ReportInvocationResponse {
589
- /** Whether the invocation was recorded successfully. */
590
- success: boolean;
591
- }
592
-
593
- /**
594
- * Configuration for {@link createLogger}.
595
- */
596
- interface LoggerConfig {
597
- /**
598
- * Enable logging. When `false` (default) the returned logger is silent at
599
- * every level. Set to `true` to route output through `console.*`. Partners
600
- * with their own structured logger (Pino, Winston, Bunyan, Datadog, etc.)
601
- * should pass it via `MagicalAuthConfig.logger` instead — this factory is
602
- * intended for local development and quick smoke tests.
603
- */
604
- debug?: boolean;
605
- /**
606
- * Prefix prepended to every log message. Default: `[GlideMagicalAuth]`.
607
- */
608
- prefix?: string;
609
- }
610
-
611
- /**
612
- * Creates a console logger with PII sanitization and a configurable prefix.
613
- *
614
- * Default-silent — call with no args (or `debug: false`) and every level is
615
- * a no-op. Set `debug: true` to opt into console output. Phone numbers,
616
- * JWTs, and explicit `session_key=…` values are auto-masked; object fields
617
- * named `phone_number`, `credential`, `token`, `password`, `secret`, or
618
- * `fe_code` are redacted to `[REDACTED]`.
619
- *
620
- * @example
621
- * ```typescript
622
- * import { MagicalAuthClient, createLogger } from '@glideidentity/glide-be-node-magical-auth';
623
- *
624
- * const client = new MagicalAuthClient({
625
- * clientId: process.env.GLIDE_CLIENT_ID!,
626
- * clientSecret: process.env.GLIDE_CLIENT_SECRET!,
627
- * logger: createLogger({ debug: true }),
628
- * });
629
- * ```
630
- */
631
- declare function createLogger(config?: LoggerConfig): Logger;
632
- /**
633
- * Recursively redacts PII from a log payload (string, array, or object).
634
- * Exported for partners who want the same redaction in their own logger.
635
- */
636
- declare function sanitize(data: unknown): unknown;
637
-
638
619
  /**
639
620
  * Error codes returned by the Magical Auth API.
640
621
  * Use `ErrorCode.SESSION_NOT_FOUND`, `ErrorCode.VALIDATION_ERROR`, etc. instead of raw strings.
@@ -647,6 +628,8 @@ declare const ErrorCode: {
647
628
  readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
648
629
  readonly INVALID_VERIFICATION: "INVALID_VERIFICATION";
649
630
  readonly CARRIER_NOT_ELIGIBLE: "CARRIER_NOT_ELIGIBLE";
631
+ readonly CARRIER_REJECTED: "CARRIER_REJECTED";
632
+ readonly CARRIER_APP_UNAVAILABLE: "CARRIER_APP_UNAVAILABLE";
650
633
  readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
651
634
  readonly PHONE_NUMBER_MISMATCH: "PHONE_NUMBER_MISMATCH";
652
635
  readonly INVALID_CREDENTIAL_FORMAT: "INVALID_CREDENTIAL_FORMAT";
@@ -671,6 +654,7 @@ interface ErrorResponse {
671
654
  message: string;
672
655
  status?: number;
673
656
  request_id?: string;
657
+ session_key?: string;
674
658
  timestamp?: string;
675
659
  trace_id?: string;
676
660
  span_id?: string;
@@ -693,9 +677,17 @@ declare class MagicalAuthError extends Error {
693
677
  */
694
678
  readonly status: number;
695
679
  /**
696
- * Request ID for debugging/support.
680
+ * The id of this request, the same value as the `X-Request-ID` response
681
+ * header. Quote it to Glide support.
697
682
  */
698
683
  readonly requestId?: string;
684
+ /**
685
+ * The session the failed request was about, once the server had read it from
686
+ * the request. Undefined when the request failed before naming a session, on
687
+ * operations that have none (eligibility, prepare), and from servers older
688
+ * than the release that added it.
689
+ */
690
+ readonly sessionKey?: string;
699
691
  /**
700
692
  * Additional error details.
701
693
  */
@@ -752,6 +744,25 @@ declare class SessionNotFoundError extends MagicalAuthError {
752
744
  declare class CarrierNotEligibleError extends MagicalAuthError {
753
745
  constructor(message?: string, requestId?: string);
754
746
  }
747
+ /**
748
+ * Carrier rejected a device-bound (link/desktop) authentication request.
749
+ *
750
+ * Surfaced at verify / get-phone-number when the carrier (or a pipeline stage)
751
+ * failed during an OAuth-callback-driven flow. The reason is carried in
752
+ * `details`: `carrier_error` (a code safe to expose), `carrier_error_description`
753
+ * (truncated to 200 chars), and optionally `stage` and `error_code` for
754
+ * non-`?error=` pipeline failures.
755
+ */
756
+ declare class CarrierRejectedError extends MagicalAuthError {
757
+ constructor(message?: string, requestId?: string, details?: Record<string, unknown>);
758
+ }
759
+ /**
760
+ * Desktop (QR): the phone that scanned the code has no working carrier app.
761
+ * Terminal for the session; start a new QR.
762
+ */
763
+ declare class CarrierAppUnavailableError extends MagicalAuthError {
764
+ constructor(message?: string, requestId?: string, details?: Record<string, unknown>);
765
+ }
755
766
  /**
756
767
  * Platform not supported for authentication.
757
768
  */
@@ -837,6 +848,7 @@ declare class DesktopWaitError extends MagicalAuthError {
837
848
  session_status: string;
838
849
  retry: boolean;
839
850
  session_expires_in_seconds: number;
851
+ request_id?: string;
840
852
  };
841
853
  constructor(waitResponse: {
842
854
  status: 'waiting';
@@ -845,8 +857,36 @@ declare class DesktopWaitError extends MagicalAuthError {
845
857
  session_status: string;
846
858
  retry: boolean;
847
859
  session_expires_in_seconds: number;
860
+ request_id?: string;
848
861
  });
849
862
  }
863
+ /**
864
+ * Codes of {@link VerificationRecordError} (identical strings in every Glide backend SDK).
865
+ */
866
+ declare const VerificationRecordErrorCode: {
867
+ readonly MALFORMED: "MALFORMED";
868
+ readonly DISALLOWED_HEADER: "DISALLOWED_HEADER";
869
+ readonly UNKNOWN_KEY: "UNKNOWN_KEY";
870
+ readonly BAD_SIGNATURE: "BAD_SIGNATURE";
871
+ readonly WRONG_ISSUER: "WRONG_ISSUER";
872
+ readonly WRONG_AUDIENCE: "WRONG_AUDIENCE";
873
+ readonly EXPIRED: "EXPIRED";
874
+ readonly NOT_YET_VALID: "NOT_YET_VALID";
875
+ readonly NONCE_MISMATCH: "NONCE_MISMATCH";
876
+ readonly ORIGIN_MISMATCH: "ORIGIN_MISMATCH";
877
+ readonly UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION";
878
+ readonly REVOKED_KEY: "REVOKED_KEY";
879
+ readonly RECORD_UNAVAILABLE: "RECORD_UNAVAILABLE";
880
+ };
881
+ type VerificationRecordErrorCode = (typeof VerificationRecordErrorCode)[keyof typeof VerificationRecordErrorCode];
882
+ /**
883
+ * Thrown by `verifyVerificationRecord` when a verification record fails any check.
884
+ * Raised locally, so `status` is 0.
885
+ */
886
+ declare class VerificationRecordError extends MagicalAuthError {
887
+ readonly code: VerificationRecordErrorCode;
888
+ constructor(code: VerificationRecordErrorCode, message: string);
889
+ }
850
890
  /**
851
891
  * Creates the appropriate error class instance from an API error response.
852
892
  * @param response - The error response from the API
@@ -855,4 +895,267 @@ declare class DesktopWaitError extends MagicalAuthError {
855
895
  */
856
896
  declare function createErrorFromResponse(response: ErrorResponse, headers?: Headers): MagicalAuthError;
857
897
 
858
- export { SessionStatus 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, PhoneNumberMismatchError as J, type PrepareOptions as K, type Logger as L, type MagicalAuthConfig as M, type PrepareResponse as N, type ProtocolType as O, type PrepareRequest as P, RateLimitError as Q, type ReportInvocationResponse as R, type StatusResponse as S, type ReportInvocationRequest as T, type ResolvedConfig as U, type VerifyPhoneNumberRequest as V, type RiskLevel as W, ServiceUnavailableError as X, type SessionInfo as Y, SessionNotEligibleError as Z, SessionNotFoundError as _, type PrepareResult as a, type SimSwapFailureReason as a0, type SimSwapInfo as a1, type StrategyData as a2, type TS43RequestData as a3, type TS43StrategyData as a4, type Theme as a5, UnauthorizedError as a6, UnsupportedPlatformError as a7, UseCase as a8, ValidationError as a9, createErrorFromResponse as aa, createLogger as ab, defaultHttpClient as ac, noopLogger as ad, resolveConfig as ae, sanitize as af, type VerifyPhoneNumberResponse as b, type GetPhoneNumberResponse as c, BrowserMismatchError 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 HttpRequestOptions as s, type HttpResponse as t, InvalidCredentialError as u, type LinkStrategyData as v, type LoggerConfig as w, MagicalAuthError as x, MissingBindingCookieError as y, type PLMN as z };
898
+ declare const PREPARE_MULTIPLE_MAX = 10;
899
+ /**
900
+ * `nonce` is excluded on purpose: there is no per-number slot for one, and a
901
+ * single shared nonce across sessions would defeat replay protection. Each
902
+ * inner prepare generates its own.
903
+ */
904
+ interface PrepareMultipleRequest extends Omit<PrepareRequest, 'phone_number' | 'nonce'> {
905
+ phone_numbers: string[];
906
+ }
907
+ /**
908
+ * `phone_number` is deliberately outside `result` so that forwarding `result`
909
+ * to a client carries no PII. Note that `result` still contains `feCode` on the
910
+ * link strategy, which must never reach browser JavaScript.
911
+ */
912
+ type PrepareMultipleResult = {
913
+ phone_number: string;
914
+ ok: true;
915
+ result: PrepareResult;
916
+ } | {
917
+ phone_number: string;
918
+ ok: false;
919
+ error: MagicalAuthError;
920
+ };
921
+
922
+ /**
923
+ * Request body for verify phone number.
924
+ */
925
+ interface VerifyPhoneNumberRequest {
926
+ /** Session information from prepare response */
927
+ session: SessionInfo;
928
+ /** SD-JWT credential string from digital credential */
929
+ credential: string;
930
+ /** Device binding code for link protocol sessions (from _glide_bind cookie) */
931
+ fe_code?: string;
932
+ /**
933
+ * Base64-encoded DER ECDSA signature for native device binding.
934
+ * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
935
+ * Only used for native link protocol sessions — web sessions use fe_code instead.
936
+ */
937
+ signature?: string;
938
+ }
939
+ /**
940
+ * Response from verify phone number.
941
+ */
942
+ interface VerifyPhoneNumberResponse {
943
+ /** The phone number that was verified (E.164 format) */
944
+ phone_number: string;
945
+ /** Whether the phone number matches the device */
946
+ verified: boolean;
947
+ /**
948
+ * The session's prepare nonce, equal to the record's `nonce` claim. Absent
949
+ * from servers older than the release that added it.
950
+ */
951
+ nonce?: string;
952
+ /** Audience from TS43 response (when available) */
953
+ aud?: string;
954
+ /** Equals the record's `biometric_verification` claim. */
955
+ biometric_verification: BiometricVerification;
956
+ /** SIM swap check result (when enabled) */
957
+ sim_swap?: SimSwapInfo;
958
+ /** Device swap (IMEI change) check result (when supported by carrier) */
959
+ device_swap?: DeviceSwapInfo;
960
+ /** Same-network signal (Desktop QR, when the desktop prepare stamped network_origin) */
961
+ network_check?: NetworkCheck;
962
+ /** Parsed phone number components (optional, server-populated) */
963
+ phone_number_details?: PhoneNumberDetails;
964
+ /**
965
+ * Glide-signed compact JWS of this result. Check it with
966
+ * `MagicalAuthClient.verifyVerificationRecord` before trusting it.
967
+ */
968
+ verification_record?: string;
969
+ /** Whether a record was issued; absent from servers without records. */
970
+ verification_record_status?: 'signed' | 'unavailable' | (string & {});
971
+ /**
972
+ * The session this response is about (the key prepare returned), so a result
973
+ * can be stored or logged without the request. Absent from servers older than
974
+ * the release that added it.
975
+ */
976
+ session_key?: string;
977
+ /**
978
+ * The id of this request, the same value as the `X-Request-ID` response
979
+ * header. Quote it to Glide support. Absent from servers older than the
980
+ * release that added it.
981
+ */
982
+ request_id?: string;
983
+ }
984
+
985
+ /**
986
+ * Request body for get phone number.
987
+ */
988
+ interface GetPhoneNumberRequest {
989
+ /** Session information from prepare response */
990
+ session: SessionInfo;
991
+ /** SD-JWT credential string from digital credential */
992
+ credential: string;
993
+ /** Device binding code for link protocol sessions (from _glide_bind cookie) */
994
+ fe_code?: string;
995
+ /**
996
+ * Base64-encoded DER ECDSA signature for native device binding.
997
+ * The native app signs "{session_key}:{credential}" with its SE/TEE private key.
998
+ * Only used for native link protocol sessions — web sessions use fe_code instead.
999
+ */
1000
+ signature?: string;
1001
+ }
1002
+ /**
1003
+ * Response from get phone number.
1004
+ */
1005
+ interface GetPhoneNumberResponse {
1006
+ /** The retrieved phone number (E.164 format) */
1007
+ phone_number: string;
1008
+ /** The session's prepare nonce. Absent from servers older than the release that added it. */
1009
+ nonce?: string;
1010
+ /** Audience from TS43 response (when available) */
1011
+ aud?: string;
1012
+ biometric_verification: BiometricVerification;
1013
+ /** SIM swap check result (when enabled) */
1014
+ sim_swap?: SimSwapInfo;
1015
+ /** Device swap (IMEI change) check result (when supported by carrier) */
1016
+ device_swap?: DeviceSwapInfo;
1017
+ /** Same-network signal (Desktop QR, when the desktop prepare stamped network_origin) */
1018
+ network_check?: NetworkCheck;
1019
+ /** Parsed phone number components (optional, server-populated) */
1020
+ phone_number_details?: PhoneNumberDetails;
1021
+ /**
1022
+ * The session this response is about (the key prepare returned), so a result
1023
+ * can be stored or logged without the request. Absent from servers older than
1024
+ * the release that added it.
1025
+ */
1026
+ session_key?: string;
1027
+ /**
1028
+ * The id of this request, the same value as the `X-Request-ID` response
1029
+ * header. Quote it to Glide support. Absent from servers older than the
1030
+ * release that added it.
1031
+ */
1032
+ request_id?: string;
1033
+ }
1034
+
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
+ /**
1070
+ * Request body for report invocation.
1071
+ */
1072
+ interface ReportInvocationRequest {
1073
+ /** The session identifier for the invocation */
1074
+ session_id: string;
1075
+ }
1076
+ /**
1077
+ * Response from report invocation.
1078
+ *
1079
+ * The backend returns `{ "success": true }` on 2xx. Invocation recording is
1080
+ * idempotent — reporting the same `session_id` twice also returns
1081
+ * `{ success: true }`.
1082
+ */
1083
+ interface ReportInvocationResponse {
1084
+ /** Whether the invocation was recorded successfully. */
1085
+ success: boolean;
1086
+ /**
1087
+ * The session this response is about (the key prepare returned), so a result
1088
+ * can be stored or logged without the request. Absent from servers older than
1089
+ * the release that added it.
1090
+ */
1091
+ session_key?: string;
1092
+ /**
1093
+ * The id of this request, the same value as the `X-Request-ID` response
1094
+ * header. Quote it to Glide support. Absent from servers older than the
1095
+ * release that added it.
1096
+ */
1097
+ request_id?: string;
1098
+ }
1099
+
1100
+ /**
1101
+ * Configuration for {@link createLogger}.
1102
+ */
1103
+ interface LoggerConfig {
1104
+ /**
1105
+ * Enable logging. When `false` (default) the returned logger is silent at
1106
+ * every level. Set to `true` to route output through `console.*`. Partners
1107
+ * with their own structured logger (Pino, Winston, Bunyan, Datadog, etc.)
1108
+ * should pass it via `MagicalAuthConfig.logger` instead — this factory is
1109
+ * intended for local development and quick smoke tests.
1110
+ */
1111
+ debug?: boolean;
1112
+ /**
1113
+ * Prefix prepended to every log message. Default: `[GlideMagicalAuth]`.
1114
+ */
1115
+ prefix?: string;
1116
+ }
1117
+
1118
+ /**
1119
+ * Creates a console logger with PII sanitization and a configurable prefix.
1120
+ *
1121
+ * Default-silent — call with no args (or `debug: false`) and every level is
1122
+ * a no-op. Set `debug: true` to opt into console output. Phone numbers,
1123
+ * JWTs, and explicit `session_key=…` values are auto-masked; object fields
1124
+ * named `phone_number`, `credential`, `token`, `password`, `secret`, or
1125
+ * `fe_code` are redacted to `[REDACTED]`.
1126
+ *
1127
+ * @example
1128
+ * ```typescript
1129
+ * import { MagicalAuthClient, createLogger } from '@glideidentity/glide-be-node-magical-auth';
1130
+ *
1131
+ * const client = new MagicalAuthClient({
1132
+ * clientId: process.env.GLIDE_CLIENT_ID!,
1133
+ * clientSecret: process.env.GLIDE_CLIENT_SECRET!,
1134
+ * logger: createLogger({ debug: true }),
1135
+ * });
1136
+ * ```
1137
+ */
1138
+ declare function createLogger(config?: LoggerConfig): Logger;
1139
+ /**
1140
+ * Recursively redacts PII from a log payload (string, array, or object).
1141
+ * Exported for partners who want the same redaction in their own logger.
1142
+ *
1143
+ * Regex ordering matters: JWT first (most specific — base64url segments
1144
+ * may contain digit runs that would otherwise be eaten by `PHONE_RE`),
1145
+ * then `session_key=…` assignment context, then the catchall phone
1146
+ * regex. Reordering this loses redaction guarantees for JWTs whose
1147
+ * payloads encode long all-numeric strings.
1148
+ *
1149
+ * Sensitive object fields (`SENSITIVE`) are replaced in full with
1150
+ * `[REDACTED]` regardless of value type — strings, objects, arrays, or
1151
+ * primitives. This prevents nested-secret leaks like
1152
+ * `{ secret: { value: '<real>' } }` slipping through because the inner
1153
+ * structure happens not to match any string regex.
1154
+ *
1155
+ * `sanitize()` is cycle-safe: a `WeakSet` of already-visited objects
1156
+ * short-circuits to `'[Circular]'` so a circular log payload (which
1157
+ * `console.log` itself handles gracefully) never throws `RangeError`.
1158
+ */
1159
+ declare function sanitize(data: unknown): unknown;
1160
+
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 };