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