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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.
@@ -373,6 +478,33 @@ interface PrepareResponse {
373
478
  * session_timeout when provided, otherwise the server-configured default.
374
479
  */
375
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;
376
508
  }
377
509
 
378
510
  /**
@@ -484,182 +616,6 @@ interface DesktopStrategyData {
484
616
  */
485
617
  type StrategyData = TS43StrategyData | LinkStrategyData | DesktopStrategyData;
486
618
 
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.
506
- */
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;
600
- }
601
-
602
- /**
603
- * Configuration for {@link createLogger}.
604
- */
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;
618
- }
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
- /**
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`.
660
- */
661
- declare function sanitize(data: unknown): unknown;
662
-
663
619
  /**
664
620
  * Error codes returned by the Magical Auth API.
665
621
  * Use `ErrorCode.SESSION_NOT_FOUND`, `ErrorCode.VALIDATION_ERROR`, etc. instead of raw strings.
@@ -672,6 +628,8 @@ declare const ErrorCode: {
672
628
  readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
673
629
  readonly INVALID_VERIFICATION: "INVALID_VERIFICATION";
674
630
  readonly CARRIER_NOT_ELIGIBLE: "CARRIER_NOT_ELIGIBLE";
631
+ readonly CARRIER_REJECTED: "CARRIER_REJECTED";
632
+ readonly CARRIER_APP_UNAVAILABLE: "CARRIER_APP_UNAVAILABLE";
675
633
  readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
676
634
  readonly PHONE_NUMBER_MISMATCH: "PHONE_NUMBER_MISMATCH";
677
635
  readonly INVALID_CREDENTIAL_FORMAT: "INVALID_CREDENTIAL_FORMAT";
@@ -696,6 +654,7 @@ interface ErrorResponse {
696
654
  message: string;
697
655
  status?: number;
698
656
  request_id?: string;
657
+ session_key?: string;
699
658
  timestamp?: string;
700
659
  trace_id?: string;
701
660
  span_id?: string;
@@ -718,9 +677,17 @@ declare class MagicalAuthError extends Error {
718
677
  */
719
678
  readonly status: number;
720
679
  /**
721
- * 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.
722
682
  */
723
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;
724
691
  /**
725
692
  * Additional error details.
726
693
  */
@@ -777,6 +744,25 @@ declare class SessionNotFoundError extends MagicalAuthError {
777
744
  declare class CarrierNotEligibleError extends MagicalAuthError {
778
745
  constructor(message?: string, requestId?: string);
779
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
+ }
780
766
  /**
781
767
  * Platform not supported for authentication.
782
768
  */
@@ -862,6 +848,7 @@ declare class DesktopWaitError extends MagicalAuthError {
862
848
  session_status: string;
863
849
  retry: boolean;
864
850
  session_expires_in_seconds: number;
851
+ request_id?: string;
865
852
  };
866
853
  constructor(waitResponse: {
867
854
  status: 'waiting';
@@ -870,8 +857,36 @@ declare class DesktopWaitError extends MagicalAuthError {
870
857
  session_status: string;
871
858
  retry: boolean;
872
859
  session_expires_in_seconds: number;
860
+ request_id?: string;
873
861
  });
874
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
+ }
875
890
  /**
876
891
  * Creates the appropriate error class instance from an API error response.
877
892
  * @param response - The error response from the API
@@ -880,4 +895,267 @@ declare class DesktopWaitError extends MagicalAuthError {
880
895
  */
881
896
  declare function createErrorFromResponse(response: ErrorResponse, headers?: Headers): MagicalAuthError;
882
897
 
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 };
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 };