@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/LICENSE +190 -23
- package/README.md +167 -1
- package/dist/index.cjs +763 -23
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +220 -5
- package/dist/index.d.ts +220 -5
- package/dist/index.js +755 -21
- package/dist/index.js.map +1 -1
- package/dist/{types-DKfytuP6.d.cts → types-BPuPzIcL.d.cts} +465 -162
- package/dist/{types-DKfytuP6.d.ts → types-BPuPzIcL.d.ts} +465 -162
- package/dist/types.cjs.map +1 -1
- package/dist/types.d.cts +1 -1
- package/dist/types.d.ts +1 -1
- package/package.json +10 -3
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { M as MagicalAuthConfig,
|
|
2
|
-
export {
|
|
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
|
|
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,
|
|
2
|
-
export {
|
|
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
|
|
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 };
|