@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.
- package/LICENSE +190 -23
- package/README.md +167 -1
- package/dist/index.cjs +716 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +168 -7
- package/dist/index.d.ts +168 -7
- package/dist/index.js +708 -11
- package/dist/index.js.map +1 -1
- package/dist/{types-DgXuYYzq.d.cts → types-BPuPzIcL.d.cts} +456 -178
- package/dist/{types-DgXuYYzq.d.ts → types-BPuPzIcL.d.ts} +456 -178
- package/dist/types.cjs.map +1 -1
- package/dist/types.d.cts +1 -1
- package/dist/types.d.ts +1 -1
- package/package.json +4 -2
|
@@ -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
|
|
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
|
-
|
|
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 };
|