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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MagicalAuthConfig, P as PrepareRequest, a as PrepareResult, V as VerifyPhoneNumberRequest, b as VerifyPhoneNumberResponse, G as GetPhoneNumberRequest, c as GetPhoneNumberResponse, R as ReportInvocationResponse, S as StatusResponse, H as HttpClient, L as Logger } from './types-DKfytuP6.cjs';
2
- export { A as AuthenticationStrategy, B as BadRequestError, d as BrowserMismatchError, C as CarrierNotEligibleError, e as Challenge, f as ClientInfo, g as ConsentData, D as DCQLCredential, h as DCQLCredentialMeta, i as DCQLQuery, j as DEFAULT_BASE_URL, k as DEFAULT_TIMEOUT, l as DesktopQRData, m as DesktopStrategyData, n as DesktopWaitError, o as DeviceBindingError, p as DeviceInfo, q as DeviceSwapInfo, E as ErrorCode, r as ErrorResponse, F as ForbiddenError, s as HttpRequestOptions, t as HttpResponse, I as InternalServerError, u as InvalidCredentialError, v as LinkStrategyData, w as LoggerConfig, x as MagicalAuthError, y as MissingBindingCookieError, z as PLMN, J as PhoneNumberMismatchError, K as PrepareOptions, N as PrepareResponse, O as ProtocolType, Q as RateLimitError, T as ReportInvocationRequest, U as ResolvedConfig, W as RiskLevel, X as ServiceUnavailableError, Y as SessionInfo, Z as SessionNotEligibleError, _ as SessionNotFoundError, $ as SessionStatus, a0 as SimSwapFailureReason, a1 as SimSwapInfo, a2 as StrategyData, a3 as TS43RequestData, a4 as TS43StrategyData, a5 as Theme, a6 as UnauthorizedError, a7 as UnsupportedPlatformError, a8 as UseCase, a9 as ValidationError, aa as createErrorFromResponse, ab as createLogger, ac as defaultHttpClient, ad as noopLogger, ae as resolveConfig, af as sanitize } from './types-DKfytuP6.cjs';
1
+ import { A as AuthenticationStrategy, P as PLMN, f as ClientInfo, O as PhoneNumberDetails, a as BiometricVerification, M as MagicalAuthConfig, U as PrepareRequest, W as PrepareResult, R as PrepareMultipleRequest, S as PrepareMultipleResult, aj as VerifyPhoneNumberRequest, ak as VerifyPhoneNumberResponse, G as GetPhoneNumberRequest, s as GetPhoneNumberResponse, _ as ReportInvocationResponse, a8 as StatusResponse, H as HttpClient, w as Logger } from './types-BPuPzIcL.cjs';
2
+ export { B as BadRequestError, b as BrowserMismatchError, C as CarrierAppUnavailableError, c as CarrierNotEligibleError, d as CarrierRejectedError, e as Challenge, g as ConsentData, D as DCQLCredential, h as DCQLCredentialMeta, i as DCQLQuery, j as DEFAULT_BASE_URL, k as DEFAULT_TIMEOUT, l as DesktopQRData, m as DesktopStrategyData, n as DesktopWaitError, o as DeviceBindingError, p as DeviceInfo, q as DeviceSwapInfo, E as ErrorCode, r as ErrorResponse, F as ForbiddenError, t as HttpRequestOptions, u as HttpResponse, I as InternalServerError, v as InvalidCredentialError, L as LinkStrategyData, x as LoggerConfig, y as MagicalAuthError, z as MissingBindingCookieError, N as NetworkCheck, J as NetworkOrigin, K as PREPARE_MULTIPLE_MAX, Q as PhoneNumberMismatchError, T as PrepareOptions, V as PrepareResponse, X as ProtocolType, Y as RateLimitError, Z as ReportInvocationRequest, $ as ResolvedConfig, a0 as RiskLevel, a1 as ServiceUnavailableError, a2 as SessionInfo, a3 as SessionNotEligibleError, a4 as SessionNotFoundError, a5 as SessionStatus, a6 as SimSwapFailureReason, a7 as SimSwapInfo, a9 as StrategyData, aa as TS43RequestData, ab as TS43StrategyData, ac as Theme, ad as UnauthorizedError, ae as UnsupportedPlatformError, af as UseCase, ag as ValidationError, ah as VerificationRecordError, ai as VerificationRecordErrorCode, al as createErrorFromResponse, am as createLogger, an as defaultHttpClient, ao as noopLogger, ap as resolveConfig, aq as sanitize } from './types-BPuPzIcL.cjs';
3
3
 
4
4
  /**
5
5
  * Request body for device-bound session completion (link protocol only).
@@ -25,6 +25,18 @@ interface CompleteRequest {
25
25
  interface CompleteResponse {
26
26
  /** Session status after successful device binding validation (always "completed") */
27
27
  status: 'completed';
28
+ /**
29
+ * The session this response is about (the key prepare returned), so a result
30
+ * can be stored or logged without the request. Absent from servers older than
31
+ * the release that added it.
32
+ */
33
+ session_key?: string;
34
+ /**
35
+ * The id of this request, the same value as the `X-Request-ID` response
36
+ * header. Quote it to Glide support. Absent from servers older than the
37
+ * release that added it.
38
+ */
39
+ request_id?: string;
28
40
  }
29
41
  /**
30
42
  * Returned with HTTP 202 when a desktop (QR) session's wait timer expires
@@ -46,6 +58,164 @@ interface DesktopWaitResponse {
46
58
  retry: boolean;
47
59
  /** Approximate seconds until the session expires */
48
60
  session_expires_in_seconds: number;
61
+ /**
62
+ * The id of this request, the same value as the `X-Request-ID` response
63
+ * header. Quote it to Glide support. Absent from servers older than the
64
+ * release that added it.
65
+ */
66
+ request_id?: string;
67
+ }
68
+
69
+ /** Request to check authentication eligibility. */
70
+ interface EligibilityRequest {
71
+ /** Phone number in E.164 format. At least one of phone_number or plmn required. */
72
+ phone_number?: string;
73
+ /** PLMN (MCC+MNC). At least one of phone_number or plmn required. */
74
+ plmn?: PLMN;
75
+ /**
76
+ * Client info (with a non-blank `user_agent`). Required: eligibility filtering
77
+ * is device-aware and the server rejects a missing `client_info` or blank
78
+ * `user_agent` with 400 VALIDATION_ERROR.
79
+ */
80
+ client_info: ClientInfo;
81
+ }
82
+ /** Constraints for the device that completes an option (always the phone). */
83
+ interface Requirements {
84
+ /** "self" = requesting device; "companion" = a separate phone. */
85
+ target?: 'self' | 'companion';
86
+ /** Minimum Android OS version (user-facing messaging). */
87
+ android_min_version?: number;
88
+ /** Minimum Android SDK/API level (enforced in code). */
89
+ android_min_sdk?: number;
90
+ /** Minimum iOS version (App Clip floor for link). */
91
+ ios_min_version?: number;
92
+ /** Forward-compat: any future fields are preserved here. */
93
+ [key: string]: unknown;
94
+ }
95
+ /** An available authentication strategy option. */
96
+ interface AvailableOption {
97
+ /** The authentication strategy identifier. */
98
+ authentication_strategy: Exclude<AuthenticationStrategy, ''>;
99
+ /** Human-readable strategy name. */
100
+ name: string;
101
+ /** Description of the authentication flow. */
102
+ description: string;
103
+ /** Platforms this strategy is available on. */
104
+ available_platforms: string[];
105
+ /** Platform/version requirements for the completing device. */
106
+ requirements?: Requirements;
107
+ }
108
+ /** Response from the eligibility check. */
109
+ interface EligibilityResponse {
110
+ /** Whether authentication is available. */
111
+ eligible: boolean;
112
+ /** Available authentication strategy options. */
113
+ available_options: AvailableOption[];
114
+ /**
115
+ * Normalized carrier name for the resolved network. Present only for callers
116
+ * the gateway has explicitly enabled to receive carrier information (the same
117
+ * per-app gate as `/prepare`); omitted otherwise and whenever `eligible` is false.
118
+ */
119
+ carrier_name?: string;
120
+ /**
121
+ * The id of this request, the same value as the `X-Request-ID` response
122
+ * header. Quote it to Glide support. Absent from servers older than the
123
+ * release that added it.
124
+ */
125
+ request_id?: string;
126
+ }
127
+
128
+ /**
129
+ * Options for `MagicalAuthClient.verifyVerificationRecord`. All optional.
130
+ */
131
+ interface VerificationRecordOptions {
132
+ /** When set, must equal the record's nonce (the prepare nonce). */
133
+ expectedNonce?: string;
134
+ /**
135
+ * Accept a record past `exp`, for audit of stored records. The record's
136
+ * `iat` must still be within `maxAuditAgeSeconds`.
137
+ */
138
+ allowExpired?: boolean;
139
+ /** Bounds `iat` when `allowExpired` is set. Missing, zero or negative means 90 days. */
140
+ maxAuditAgeSeconds?: number;
141
+ /** Overrides the expected `iss`. Empty means the client base URL without trailing "/". */
142
+ issuer?: string;
143
+ /** Rejected in addition to the SDK's built-in revoked list. */
144
+ revokedKids?: string[];
145
+ /** The record `aud` to require. Missing or empty means this client's ID. */
146
+ expectedAudience?: string;
147
+ /** When non-empty, the record's `origin` must equal one entry exactly. */
148
+ expectedOrigin?: readonly string[];
149
+ /** Overrides the clock used for claim checks (not the key cache). */
150
+ now?: () => Date;
151
+ }
152
+ /** One entry of the record's `sign_offs` claim. */
153
+ interface VerificationRecordSignOff {
154
+ role: string;
155
+ signer: string;
156
+ status: 'unavailable' | 'present';
157
+ reason?: string;
158
+ format?: string;
159
+ token?: string;
160
+ }
161
+ /** Optional carrier claim on a verified record. */
162
+ interface VerificationRecordCarrier {
163
+ id: string;
164
+ name?: string;
165
+ mvno?: string;
166
+ }
167
+ /** Swap age band in whole hours; -1 means unknown. */
168
+ interface VerificationRecordAgeBand {
169
+ from: number;
170
+ to: number;
171
+ }
172
+ /** A record's `sim_swap` or `device_swap` claim. */
173
+ interface VerificationRecordSwap {
174
+ checked: boolean;
175
+ risk_level?: string;
176
+ age_band?: VerificationRecordAgeBand;
177
+ carrier_name?: string;
178
+ reason?: string;
179
+ swapped?: boolean;
180
+ max_age_hours?: number;
181
+ }
182
+ /** Claims of a verified record, under their wire (snake_case) names. */
183
+ interface VerificationRecordClaims {
184
+ ver: '1.0';
185
+ iss: string;
186
+ sub: string;
187
+ aud: string;
188
+ iat: number;
189
+ nbf: number;
190
+ exp: number;
191
+ jti: string;
192
+ nonce: string;
193
+ origin: string;
194
+ use_case: string;
195
+ verified: boolean;
196
+ strategy?: string;
197
+ phone_number_details?: PhoneNumberDetails;
198
+ carrier?: VerificationRecordCarrier;
199
+ biometric_verification: BiometricVerification;
200
+ sim_swap?: VerificationRecordSwap;
201
+ device_swap?: VerificationRecordSwap;
202
+ sign_offs: VerificationRecordSignOff[];
203
+ }
204
+ /**
205
+ * How the SDK treated one sign-off: `unavailable` (with the server's reason)
206
+ * or `unverified`. A present sign-off is never treated as carrier trust in
207
+ * this version.
208
+ */
209
+ interface SignOffResult {
210
+ role: string;
211
+ signer: string;
212
+ result: 'unavailable' | 'unverified';
213
+ reason?: string;
214
+ }
215
+ /** A record whose signature and claims passed every check. */
216
+ interface VerifiedVerificationRecord {
217
+ claims: VerificationRecordClaims;
218
+ signOffResults: SignOffResult[];
49
219
  }
50
220
 
51
221
  /**
@@ -82,6 +252,7 @@ interface RequestOptions {
82
252
  declare class MagicalAuthClient {
83
253
  private readonly config;
84
254
  private readonly tokenManager;
255
+ private readonly recordKeys;
85
256
  /**
86
257
  * Creates a new MagicalAuthClient instance.
87
258
  *
@@ -89,6 +260,17 @@ declare class MagicalAuthClient {
89
260
  * @throws {Error} If clientId or clientSecret is missing
90
261
  */
91
262
  constructor(config: MagicalAuthConfig);
263
+ /**
264
+ * Check authentication eligibility for a phone number or PLMN.
265
+ * Returns available authentication strategies with platform requirements.
266
+ *
267
+ * @param request - Eligibility request with phone_number or plmn. `client_info.user_agent` is required.
268
+ * @param options - Per-request options (e.g., correlationId)
269
+ * @returns Eligibility response with available options
270
+ * @throws {ValidationError} If request validation fails (incl. missing/blank `client_info.user_agent`)
271
+ * @throws {MagicalAuthError} For other API errors
272
+ */
273
+ checkEligibility(request: EligibilityRequest, options?: RequestOptions): Promise<EligibilityResponse>;
92
274
  /**
93
275
  * Prepares authentication by checking carrier eligibility and generating protocol-specific requests.
94
276
  *
@@ -104,6 +286,20 @@ declare class MagicalAuthClient {
104
286
  * @throws {MagicalAuthError} For other API errors
105
287
  */
106
288
  prepare(request: PrepareRequest, options?: RequestOptions): Promise<PrepareResult>;
289
+ /**
290
+ * Prepares authentication for several phone numbers at once.
291
+ *
292
+ * Fans out one ordinary {@link prepare} call per number, so each number gets
293
+ * its own carrier resolution, residency routing and session. Per-number
294
+ * failures are returned as items rather than thrown; this only throws
295
+ * {@link ValidationError}, and only before any request is issued.
296
+ *
297
+ * @param request - Shared prepare fields plus `phone_numbers` (1..10)
298
+ * @param options - Per-request options (e.g., correlationId)
299
+ * @returns One result per input number, in input order
300
+ * @throws {ValidationError} If the list is empty, over the cap, has blank entries, or a shared prepare field is invalid
301
+ */
302
+ prepareMultiple(request: PrepareMultipleRequest, options?: RequestOptions): Promise<PrepareMultipleResult[]>;
107
303
  /**
108
304
  * Validates device binding codes and completes a link protocol session.
109
305
  *
@@ -135,6 +331,20 @@ declare class MagicalAuthClient {
135
331
  * @throws {MagicalAuthError} For other API errors
136
332
  */
137
333
  verifyPhoneNumber(request: VerifyPhoneNumberRequest, options?: RequestOptions): Promise<VerifyPhoneNumberResponse>;
334
+ /**
335
+ * Verifies a verification record returned by {@link verifyPhoneNumber}: the
336
+ * ES256 signature against Glide's published record keys, then issuer,
337
+ * the expected audience (default this client's ID), validity window, shape, nonce and origin.
338
+ *
339
+ * A missing or empty record fails with `RECORD_UNAVAILABLE`, so a caller
340
+ * that requires records can pass `response.verification_record` straight in.
341
+ *
342
+ * @param record - Compact JWS from `VerifyPhoneNumberResponse.verification_record`
343
+ * @param options - Expected nonce, expected audience, expected origins, audit mode, issuer override, extra revoked kids, clock
344
+ * @returns The verified claims and how each sign-off was treated
345
+ * @throws {VerificationRecordError} On any failed check; `code` is a {@link VerificationRecordErrorCode}
346
+ */
347
+ verifyVerificationRecord(record: string | undefined, options?: VerificationRecordOptions): Promise<VerifiedVerificationRecord>;
138
348
  /**
139
349
  * Retrieves the phone number associated with the device using digital credentials.
140
350
  *
@@ -358,8 +568,13 @@ declare function clearStaleBindingCookies(cookieHeader: string | undefined, opti
358
568
  * `_glide_bind_{sessionKey}` HttpOnly cookie), and displays the result.
359
569
  *
360
570
  * On successful completion, a localStorage signal is written
361
- * (`glide_signal_{session_key}`) so the FE SDK in the original tab can
362
- * detect completion via `StorageEvent` without polling.
571
+ * (`glide_signal_{session_key}` = session_key) so the FE SDK in the original
572
+ * tab can detect completion via `StorageEvent` without polling, plus a
573
+ * sibling timestamp (`glide_sigmeta_{session_key}` = epoch ms) the FE SDK
574
+ * uses to sweep stale signals. Both keys stay for the session lifetime: the
575
+ * waiting tab may be suspended while the App Clip is in the foreground and
576
+ * must still find the signal when it resumes. The FE SDK removes them on
577
+ * consume; the page only erases them after 10 minutes as a fallback.
363
578
  *
364
579
  * @param completeEndpoint - Relative path to POST to (e.g., "/api/glide/complete")
365
580
  * @returns Complete HTML string ready to serve
@@ -416,4 +631,4 @@ declare function getCompletionPageHtml(completeEndpoint: string): string;
416
631
  */
417
632
  declare const VERSION: string;
418
633
 
419
- export { BINDING_COOKIE_MAX_AGE, BINDING_COOKIE_PREFIX, type BindingCookieOptions, type CompleteRequest, type CompleteResponse, type DesktopWaitResponse, GetPhoneNumberRequest, GetPhoneNumberResponse, HEX_64, HttpClient, Logger, MagicalAuthClient, MagicalAuthConfig, PrepareRequest, PrepareResult, ReportInvocationResponse, type RequestOptions, SENSITIVE_KEYS, StatusResponse, TokenManager, VERSION, VerifyPhoneNumberRequest, VerifyPhoneNumberResponse, assertValidFeCode, buildClearBindingCookieHeader, buildSetBindingCookieHeader, clearStaleBindingCookies, computeFeHash, generateFeCode, getBindingCookieName, getCompletionPageHtml, parseBindingCookie };
634
+ export { AuthenticationStrategy, type AvailableOption, BINDING_COOKIE_MAX_AGE, BINDING_COOKIE_PREFIX, type BindingCookieOptions, BiometricVerification, ClientInfo, type CompleteRequest, type CompleteResponse, type DesktopWaitResponse, type EligibilityRequest, type EligibilityResponse, GetPhoneNumberRequest, GetPhoneNumberResponse, HEX_64, HttpClient, Logger, MagicalAuthClient, MagicalAuthConfig, PLMN, PrepareMultipleRequest, PrepareMultipleResult, PrepareRequest, PrepareResult, ReportInvocationResponse, type RequestOptions, type Requirements, SENSITIVE_KEYS, type SignOffResult, StatusResponse, TokenManager, VERSION, type VerificationRecordAgeBand, type VerificationRecordCarrier, type VerificationRecordClaims, type VerificationRecordOptions, type VerificationRecordSignOff, type VerificationRecordSwap, type VerifiedVerificationRecord, VerifyPhoneNumberRequest, VerifyPhoneNumberResponse, assertValidFeCode, buildClearBindingCookieHeader, buildSetBindingCookieHeader, clearStaleBindingCookies, computeFeHash, generateFeCode, getBindingCookieName, getCompletionPageHtml, parseBindingCookie };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MagicalAuthConfig, P as PrepareRequest, a as PrepareResult, V as VerifyPhoneNumberRequest, b as VerifyPhoneNumberResponse, G as GetPhoneNumberRequest, c as GetPhoneNumberResponse, R as ReportInvocationResponse, S as StatusResponse, H as HttpClient, L as Logger } from './types-DKfytuP6.js';
2
- export { A as AuthenticationStrategy, B as BadRequestError, d as BrowserMismatchError, C as CarrierNotEligibleError, e as Challenge, f as ClientInfo, g as ConsentData, D as DCQLCredential, h as DCQLCredentialMeta, i as DCQLQuery, j as DEFAULT_BASE_URL, k as DEFAULT_TIMEOUT, l as DesktopQRData, m as DesktopStrategyData, n as DesktopWaitError, o as DeviceBindingError, p as DeviceInfo, q as DeviceSwapInfo, E as ErrorCode, r as ErrorResponse, F as ForbiddenError, s as HttpRequestOptions, t as HttpResponse, I as InternalServerError, u as InvalidCredentialError, v as LinkStrategyData, w as LoggerConfig, x as MagicalAuthError, y as MissingBindingCookieError, z as PLMN, J as PhoneNumberMismatchError, K as PrepareOptions, N as PrepareResponse, O as ProtocolType, Q as RateLimitError, T as ReportInvocationRequest, U as ResolvedConfig, W as RiskLevel, X as ServiceUnavailableError, Y as SessionInfo, Z as SessionNotEligibleError, _ as SessionNotFoundError, $ as SessionStatus, a0 as SimSwapFailureReason, a1 as SimSwapInfo, a2 as StrategyData, a3 as TS43RequestData, a4 as TS43StrategyData, a5 as Theme, a6 as UnauthorizedError, a7 as UnsupportedPlatformError, a8 as UseCase, a9 as ValidationError, aa as createErrorFromResponse, ab as createLogger, ac as defaultHttpClient, ad as noopLogger, ae as resolveConfig, af as sanitize } from './types-DKfytuP6.js';
1
+ import { A as AuthenticationStrategy, P as PLMN, f as ClientInfo, O as PhoneNumberDetails, a as BiometricVerification, M as MagicalAuthConfig, U as PrepareRequest, W as PrepareResult, R as PrepareMultipleRequest, S as PrepareMultipleResult, aj as VerifyPhoneNumberRequest, ak as VerifyPhoneNumberResponse, G as GetPhoneNumberRequest, s as GetPhoneNumberResponse, _ as ReportInvocationResponse, a8 as StatusResponse, H as HttpClient, w as Logger } from './types-BPuPzIcL.js';
2
+ export { B as BadRequestError, b as BrowserMismatchError, C as CarrierAppUnavailableError, c as CarrierNotEligibleError, d as CarrierRejectedError, e as Challenge, g as ConsentData, D as DCQLCredential, h as DCQLCredentialMeta, i as DCQLQuery, j as DEFAULT_BASE_URL, k as DEFAULT_TIMEOUT, l as DesktopQRData, m as DesktopStrategyData, n as DesktopWaitError, o as DeviceBindingError, p as DeviceInfo, q as DeviceSwapInfo, E as ErrorCode, r as ErrorResponse, F as ForbiddenError, t as HttpRequestOptions, u as HttpResponse, I as InternalServerError, v as InvalidCredentialError, L as LinkStrategyData, x as LoggerConfig, y as MagicalAuthError, z as MissingBindingCookieError, N as NetworkCheck, J as NetworkOrigin, K as PREPARE_MULTIPLE_MAX, Q as PhoneNumberMismatchError, T as PrepareOptions, V as PrepareResponse, X as ProtocolType, Y as RateLimitError, Z as ReportInvocationRequest, $ as ResolvedConfig, a0 as RiskLevel, a1 as ServiceUnavailableError, a2 as SessionInfo, a3 as SessionNotEligibleError, a4 as SessionNotFoundError, a5 as SessionStatus, a6 as SimSwapFailureReason, a7 as SimSwapInfo, a9 as StrategyData, aa as TS43RequestData, ab as TS43StrategyData, ac as Theme, ad as UnauthorizedError, ae as UnsupportedPlatformError, af as UseCase, ag as ValidationError, ah as VerificationRecordError, ai as VerificationRecordErrorCode, al as createErrorFromResponse, am as createLogger, an as defaultHttpClient, ao as noopLogger, ap as resolveConfig, aq as sanitize } from './types-BPuPzIcL.js';
3
3
 
4
4
  /**
5
5
  * Request body for device-bound session completion (link protocol only).
@@ -25,6 +25,18 @@ interface CompleteRequest {
25
25
  interface CompleteResponse {
26
26
  /** Session status after successful device binding validation (always "completed") */
27
27
  status: 'completed';
28
+ /**
29
+ * The session this response is about (the key prepare returned), so a result
30
+ * can be stored or logged without the request. Absent from servers older than
31
+ * the release that added it.
32
+ */
33
+ session_key?: string;
34
+ /**
35
+ * The id of this request, the same value as the `X-Request-ID` response
36
+ * header. Quote it to Glide support. Absent from servers older than the
37
+ * release that added it.
38
+ */
39
+ request_id?: string;
28
40
  }
29
41
  /**
30
42
  * Returned with HTTP 202 when a desktop (QR) session's wait timer expires
@@ -46,6 +58,164 @@ interface DesktopWaitResponse {
46
58
  retry: boolean;
47
59
  /** Approximate seconds until the session expires */
48
60
  session_expires_in_seconds: number;
61
+ /**
62
+ * The id of this request, the same value as the `X-Request-ID` response
63
+ * header. Quote it to Glide support. Absent from servers older than the
64
+ * release that added it.
65
+ */
66
+ request_id?: string;
67
+ }
68
+
69
+ /** Request to check authentication eligibility. */
70
+ interface EligibilityRequest {
71
+ /** Phone number in E.164 format. At least one of phone_number or plmn required. */
72
+ phone_number?: string;
73
+ /** PLMN (MCC+MNC). At least one of phone_number or plmn required. */
74
+ plmn?: PLMN;
75
+ /**
76
+ * Client info (with a non-blank `user_agent`). Required: eligibility filtering
77
+ * is device-aware and the server rejects a missing `client_info` or blank
78
+ * `user_agent` with 400 VALIDATION_ERROR.
79
+ */
80
+ client_info: ClientInfo;
81
+ }
82
+ /** Constraints for the device that completes an option (always the phone). */
83
+ interface Requirements {
84
+ /** "self" = requesting device; "companion" = a separate phone. */
85
+ target?: 'self' | 'companion';
86
+ /** Minimum Android OS version (user-facing messaging). */
87
+ android_min_version?: number;
88
+ /** Minimum Android SDK/API level (enforced in code). */
89
+ android_min_sdk?: number;
90
+ /** Minimum iOS version (App Clip floor for link). */
91
+ ios_min_version?: number;
92
+ /** Forward-compat: any future fields are preserved here. */
93
+ [key: string]: unknown;
94
+ }
95
+ /** An available authentication strategy option. */
96
+ interface AvailableOption {
97
+ /** The authentication strategy identifier. */
98
+ authentication_strategy: Exclude<AuthenticationStrategy, ''>;
99
+ /** Human-readable strategy name. */
100
+ name: string;
101
+ /** Description of the authentication flow. */
102
+ description: string;
103
+ /** Platforms this strategy is available on. */
104
+ available_platforms: string[];
105
+ /** Platform/version requirements for the completing device. */
106
+ requirements?: Requirements;
107
+ }
108
+ /** Response from the eligibility check. */
109
+ interface EligibilityResponse {
110
+ /** Whether authentication is available. */
111
+ eligible: boolean;
112
+ /** Available authentication strategy options. */
113
+ available_options: AvailableOption[];
114
+ /**
115
+ * Normalized carrier name for the resolved network. Present only for callers
116
+ * the gateway has explicitly enabled to receive carrier information (the same
117
+ * per-app gate as `/prepare`); omitted otherwise and whenever `eligible` is false.
118
+ */
119
+ carrier_name?: string;
120
+ /**
121
+ * The id of this request, the same value as the `X-Request-ID` response
122
+ * header. Quote it to Glide support. Absent from servers older than the
123
+ * release that added it.
124
+ */
125
+ request_id?: string;
126
+ }
127
+
128
+ /**
129
+ * Options for `MagicalAuthClient.verifyVerificationRecord`. All optional.
130
+ */
131
+ interface VerificationRecordOptions {
132
+ /** When set, must equal the record's nonce (the prepare nonce). */
133
+ expectedNonce?: string;
134
+ /**
135
+ * Accept a record past `exp`, for audit of stored records. The record's
136
+ * `iat` must still be within `maxAuditAgeSeconds`.
137
+ */
138
+ allowExpired?: boolean;
139
+ /** Bounds `iat` when `allowExpired` is set. Missing, zero or negative means 90 days. */
140
+ maxAuditAgeSeconds?: number;
141
+ /** Overrides the expected `iss`. Empty means the client base URL without trailing "/". */
142
+ issuer?: string;
143
+ /** Rejected in addition to the SDK's built-in revoked list. */
144
+ revokedKids?: string[];
145
+ /** The record `aud` to require. Missing or empty means this client's ID. */
146
+ expectedAudience?: string;
147
+ /** When non-empty, the record's `origin` must equal one entry exactly. */
148
+ expectedOrigin?: readonly string[];
149
+ /** Overrides the clock used for claim checks (not the key cache). */
150
+ now?: () => Date;
151
+ }
152
+ /** One entry of the record's `sign_offs` claim. */
153
+ interface VerificationRecordSignOff {
154
+ role: string;
155
+ signer: string;
156
+ status: 'unavailable' | 'present';
157
+ reason?: string;
158
+ format?: string;
159
+ token?: string;
160
+ }
161
+ /** Optional carrier claim on a verified record. */
162
+ interface VerificationRecordCarrier {
163
+ id: string;
164
+ name?: string;
165
+ mvno?: string;
166
+ }
167
+ /** Swap age band in whole hours; -1 means unknown. */
168
+ interface VerificationRecordAgeBand {
169
+ from: number;
170
+ to: number;
171
+ }
172
+ /** A record's `sim_swap` or `device_swap` claim. */
173
+ interface VerificationRecordSwap {
174
+ checked: boolean;
175
+ risk_level?: string;
176
+ age_band?: VerificationRecordAgeBand;
177
+ carrier_name?: string;
178
+ reason?: string;
179
+ swapped?: boolean;
180
+ max_age_hours?: number;
181
+ }
182
+ /** Claims of a verified record, under their wire (snake_case) names. */
183
+ interface VerificationRecordClaims {
184
+ ver: '1.0';
185
+ iss: string;
186
+ sub: string;
187
+ aud: string;
188
+ iat: number;
189
+ nbf: number;
190
+ exp: number;
191
+ jti: string;
192
+ nonce: string;
193
+ origin: string;
194
+ use_case: string;
195
+ verified: boolean;
196
+ strategy?: string;
197
+ phone_number_details?: PhoneNumberDetails;
198
+ carrier?: VerificationRecordCarrier;
199
+ biometric_verification: BiometricVerification;
200
+ sim_swap?: VerificationRecordSwap;
201
+ device_swap?: VerificationRecordSwap;
202
+ sign_offs: VerificationRecordSignOff[];
203
+ }
204
+ /**
205
+ * How the SDK treated one sign-off: `unavailable` (with the server's reason)
206
+ * or `unverified`. A present sign-off is never treated as carrier trust in
207
+ * this version.
208
+ */
209
+ interface SignOffResult {
210
+ role: string;
211
+ signer: string;
212
+ result: 'unavailable' | 'unverified';
213
+ reason?: string;
214
+ }
215
+ /** A record whose signature and claims passed every check. */
216
+ interface VerifiedVerificationRecord {
217
+ claims: VerificationRecordClaims;
218
+ signOffResults: SignOffResult[];
49
219
  }
50
220
 
51
221
  /**
@@ -82,6 +252,7 @@ interface RequestOptions {
82
252
  declare class MagicalAuthClient {
83
253
  private readonly config;
84
254
  private readonly tokenManager;
255
+ private readonly recordKeys;
85
256
  /**
86
257
  * Creates a new MagicalAuthClient instance.
87
258
  *
@@ -89,6 +260,17 @@ declare class MagicalAuthClient {
89
260
  * @throws {Error} If clientId or clientSecret is missing
90
261
  */
91
262
  constructor(config: MagicalAuthConfig);
263
+ /**
264
+ * Check authentication eligibility for a phone number or PLMN.
265
+ * Returns available authentication strategies with platform requirements.
266
+ *
267
+ * @param request - Eligibility request with phone_number or plmn. `client_info.user_agent` is required.
268
+ * @param options - Per-request options (e.g., correlationId)
269
+ * @returns Eligibility response with available options
270
+ * @throws {ValidationError} If request validation fails (incl. missing/blank `client_info.user_agent`)
271
+ * @throws {MagicalAuthError} For other API errors
272
+ */
273
+ checkEligibility(request: EligibilityRequest, options?: RequestOptions): Promise<EligibilityResponse>;
92
274
  /**
93
275
  * Prepares authentication by checking carrier eligibility and generating protocol-specific requests.
94
276
  *
@@ -104,6 +286,20 @@ declare class MagicalAuthClient {
104
286
  * @throws {MagicalAuthError} For other API errors
105
287
  */
106
288
  prepare(request: PrepareRequest, options?: RequestOptions): Promise<PrepareResult>;
289
+ /**
290
+ * Prepares authentication for several phone numbers at once.
291
+ *
292
+ * Fans out one ordinary {@link prepare} call per number, so each number gets
293
+ * its own carrier resolution, residency routing and session. Per-number
294
+ * failures are returned as items rather than thrown; this only throws
295
+ * {@link ValidationError}, and only before any request is issued.
296
+ *
297
+ * @param request - Shared prepare fields plus `phone_numbers` (1..10)
298
+ * @param options - Per-request options (e.g., correlationId)
299
+ * @returns One result per input number, in input order
300
+ * @throws {ValidationError} If the list is empty, over the cap, has blank entries, or a shared prepare field is invalid
301
+ */
302
+ prepareMultiple(request: PrepareMultipleRequest, options?: RequestOptions): Promise<PrepareMultipleResult[]>;
107
303
  /**
108
304
  * Validates device binding codes and completes a link protocol session.
109
305
  *
@@ -135,6 +331,20 @@ declare class MagicalAuthClient {
135
331
  * @throws {MagicalAuthError} For other API errors
136
332
  */
137
333
  verifyPhoneNumber(request: VerifyPhoneNumberRequest, options?: RequestOptions): Promise<VerifyPhoneNumberResponse>;
334
+ /**
335
+ * Verifies a verification record returned by {@link verifyPhoneNumber}: the
336
+ * ES256 signature against Glide's published record keys, then issuer,
337
+ * the expected audience (default this client's ID), validity window, shape, nonce and origin.
338
+ *
339
+ * A missing or empty record fails with `RECORD_UNAVAILABLE`, so a caller
340
+ * that requires records can pass `response.verification_record` straight in.
341
+ *
342
+ * @param record - Compact JWS from `VerifyPhoneNumberResponse.verification_record`
343
+ * @param options - Expected nonce, expected audience, expected origins, audit mode, issuer override, extra revoked kids, clock
344
+ * @returns The verified claims and how each sign-off was treated
345
+ * @throws {VerificationRecordError} On any failed check; `code` is a {@link VerificationRecordErrorCode}
346
+ */
347
+ verifyVerificationRecord(record: string | undefined, options?: VerificationRecordOptions): Promise<VerifiedVerificationRecord>;
138
348
  /**
139
349
  * Retrieves the phone number associated with the device using digital credentials.
140
350
  *
@@ -358,8 +568,13 @@ declare function clearStaleBindingCookies(cookieHeader: string | undefined, opti
358
568
  * `_glide_bind_{sessionKey}` HttpOnly cookie), and displays the result.
359
569
  *
360
570
  * On successful completion, a localStorage signal is written
361
- * (`glide_signal_{session_key}`) so the FE SDK in the original tab can
362
- * detect completion via `StorageEvent` without polling.
571
+ * (`glide_signal_{session_key}` = session_key) so the FE SDK in the original
572
+ * tab can detect completion via `StorageEvent` without polling, plus a
573
+ * sibling timestamp (`glide_sigmeta_{session_key}` = epoch ms) the FE SDK
574
+ * uses to sweep stale signals. Both keys stay for the session lifetime: the
575
+ * waiting tab may be suspended while the App Clip is in the foreground and
576
+ * must still find the signal when it resumes. The FE SDK removes them on
577
+ * consume; the page only erases them after 10 minutes as a fallback.
363
578
  *
364
579
  * @param completeEndpoint - Relative path to POST to (e.g., "/api/glide/complete")
365
580
  * @returns Complete HTML string ready to serve
@@ -416,4 +631,4 @@ declare function getCompletionPageHtml(completeEndpoint: string): string;
416
631
  */
417
632
  declare const VERSION: string;
418
633
 
419
- export { BINDING_COOKIE_MAX_AGE, BINDING_COOKIE_PREFIX, type BindingCookieOptions, type CompleteRequest, type CompleteResponse, type DesktopWaitResponse, GetPhoneNumberRequest, GetPhoneNumberResponse, HEX_64, HttpClient, Logger, MagicalAuthClient, MagicalAuthConfig, PrepareRequest, PrepareResult, ReportInvocationResponse, type RequestOptions, SENSITIVE_KEYS, StatusResponse, TokenManager, VERSION, VerifyPhoneNumberRequest, VerifyPhoneNumberResponse, assertValidFeCode, buildClearBindingCookieHeader, buildSetBindingCookieHeader, clearStaleBindingCookies, computeFeHash, generateFeCode, getBindingCookieName, getCompletionPageHtml, parseBindingCookie };
634
+ export { AuthenticationStrategy, type AvailableOption, BINDING_COOKIE_MAX_AGE, BINDING_COOKIE_PREFIX, type BindingCookieOptions, BiometricVerification, ClientInfo, type CompleteRequest, type CompleteResponse, type DesktopWaitResponse, type EligibilityRequest, type EligibilityResponse, GetPhoneNumberRequest, GetPhoneNumberResponse, HEX_64, HttpClient, Logger, MagicalAuthClient, MagicalAuthConfig, PLMN, PrepareMultipleRequest, PrepareMultipleResult, PrepareRequest, PrepareResult, ReportInvocationResponse, type RequestOptions, type Requirements, SENSITIVE_KEYS, type SignOffResult, StatusResponse, TokenManager, VERSION, type VerificationRecordAgeBand, type VerificationRecordCarrier, type VerificationRecordClaims, type VerificationRecordOptions, type VerificationRecordSignOff, type VerificationRecordSwap, type VerifiedVerificationRecord, VerifyPhoneNumberRequest, VerifyPhoneNumberResponse, assertValidFeCode, buildClearBindingCookieHeader, buildSetBindingCookieHeader, clearStaleBindingCookies, computeFeHash, generateFeCode, getBindingCookieName, getCompletionPageHtml, parseBindingCookie };