@glideidentity/glide-be-node-magical-auth 2.0.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 ADDED
@@ -0,0 +1,35 @@
1
+ GLIDE IDENTITY — PRE-RELEASE SDK LICENSE
2
+
3
+ Copyright (c) 2026 Glide Identity, Inc. All rights reserved.
4
+
5
+ PERMITTED USE
6
+
7
+ Use of this SDK is permitted solely for the limited purpose of evaluation
8
+ and/or testing of this pre-release version of Glide Identity, Inc.'s
9
+ services, only for your own internal use. Use in production environments
10
+ or any other use outside the scope expressly permitted herein is strictly
11
+ prohibited.
12
+
13
+ NO WARRANTIES
14
+
15
+ Glide Identity, Inc. disclaims all warranties, whether express, implied,
16
+ or statutory, including without limitation implied warranties of
17
+ merchantability and fitness for a particular purpose. You expressly
18
+ acknowledge and agree that Glide Identity, Inc. does not represent or
19
+ warrant that any services and/or the operation of the SDK will be
20
+ uninterrupted or error-free.
21
+
22
+ RESTRICTIONS
23
+
24
+ You shall not reverse engineer, decompile, disassemble, modify, or
25
+ change in any manner the SDK or the associated services.
26
+
27
+ ASSUMPTION OF RISK
28
+
29
+ You assume all risks associated with your use of this SDK.
30
+
31
+ RESERVATION OF RIGHTS
32
+
33
+ All rights not expressly granted herein are reserved by Glide Identity, Inc.
34
+
35
+ For production licensing, contact: support@glideidentity.com
package/README.md ADDED
@@ -0,0 +1,341 @@
1
+ # @glideidentity/glide-be-node-magical-auth
2
+
3
+ Glide Magical Auth SDK for Node.js — phone number authentication without SMS/OTP using carrier-based digital credentials.
4
+
5
+ ## Features
6
+
7
+ - **Zero Dependencies** - Uses only Node.js built-ins (Node 18+)
8
+ - **TypeScript First** - Full type safety with excellent IntelliSense support
9
+ - **BYOC** - Bring Your Own HTTP Client for custom implementations
10
+ - **BYOL** - Bring Your Own Logger for custom logging
11
+ - **Automatic Token Management** - OAuth2 tokens cached and refreshed automatically
12
+ - **Thread-Safe** - Safe for concurrent use with promise deduplication
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install @glideidentity/glide-be-node-magical-auth
18
+ ```
19
+
20
+ ## Requirements
21
+
22
+ - Node.js 18.0.0 or higher
23
+
24
+ ## Quick Start
25
+
26
+ ```typescript
27
+ import { MagicalAuthClient } from '@glideidentity/glide-be-node-magical-auth';
28
+
29
+ const client = new MagicalAuthClient({
30
+ clientId: process.env.GLIDE_CLIENT_ID!,
31
+ clientSecret: process.env.GLIDE_CLIENT_SECRET!,
32
+ });
33
+
34
+ // 1. Prepare authentication
35
+ const prepareResponse = await client.prepare({
36
+ phone_number: '+14155551234',
37
+ nonce: crypto.randomUUID(),
38
+ use_case: 'VerifyPhoneNumber',
39
+ client_info: {
40
+ user_agent: navigator.userAgent,
41
+ },
42
+ });
43
+
44
+ // 2. Handle based on authentication strategy
45
+ switch (prepareResponse.authentication_strategy) {
46
+ case 'ts43':
47
+ // Direct credential request via the Digital Credentials API
48
+ // (available in supported browsers and natively on Android via Credential Manager).
49
+ // Use the data.dcql_query payload to invoke the API on your client.
50
+ break;
51
+
52
+ case 'link':
53
+ // OAuth-style redirect flow on mobile.
54
+ // Redirect the user to prepareResponse.data.url.
55
+ break;
56
+
57
+ case 'desktop':
58
+ // QR-code flow for desktop browsers. The `data` field is a
59
+ // DesktopStrategyData wrapper; the QR payload lives at `data.data`:
60
+ // const desktop = prepareResponse.data; // DesktopStrategyData
61
+ // render(desktop.data.qr_image); // base64 PNG data URL
62
+ // showChallenge(prepareResponse.challenge?.pattern);
63
+ break;
64
+ }
65
+
66
+ // 3. Verify the phone number with credential from device
67
+ const verifyResponse = await client.verifyPhoneNumber({
68
+ session: prepareResponse.session,
69
+ credential: credentialFromDevice,
70
+ });
71
+
72
+ if (verifyResponse.verified) {
73
+ console.log('Phone verified:', verifyResponse.phone_number);
74
+ }
75
+ ```
76
+
77
+ ## API Reference
78
+
79
+ ### MagicalAuthClient
80
+
81
+ The main client class for interacting with the Magical Auth API.
82
+
83
+ #### Constructor
84
+
85
+ ```typescript
86
+ new MagicalAuthClient(config: MagicalAuthConfig)
87
+ ```
88
+
89
+ | Option | Type | Required | Default | Description |
90
+ |--------|------|----------|---------|-------------|
91
+ | `clientId` | `string` | Yes | - | OAuth2 client ID |
92
+ | `clientSecret` | `string` | Yes | - | OAuth2 client secret |
93
+ | `baseUrl` | `string` | No | `https://api.glideidentity.app` | API base URL |
94
+ | `httpClient` | `HttpClient` | No | Native fetch | Custom HTTP client |
95
+ | `logger` | `Logger` | No | No-op | Custom logger |
96
+ | `timeout` | `number` | No | `30000` | Request timeout in ms |
97
+
98
+ #### Methods
99
+
100
+ ##### `prepare(request: PrepareRequest): Promise<PrepareResponse>`
101
+
102
+ Prepares authentication by checking carrier eligibility and generating protocol-specific requests.
103
+
104
+ ```typescript
105
+ const response = await client.prepare({
106
+ phone_number: '+14155551234', // Required for VerifyPhoneNumber
107
+ plmn: { mcc: '310', mnc: '260' }, // Optional carrier identifier
108
+ nonce: 'unique-nonce', // Required, base64url encoded
109
+ use_case: 'VerifyPhoneNumber', // or 'GetPhoneNumber'
110
+ client_info: { user_agent: '...' }, // Optional, helps strategy selection
111
+ consent_data: { ... }, // Optional consent text
112
+ options: { theme: 'dark' }, // Optional UI theme
113
+ });
114
+ ```
115
+
116
+ ##### `verifyPhoneNumber(request: VerifyPhoneNumberRequest): Promise<VerifyPhoneNumberResponse>`
117
+
118
+ Verifies a phone number using digital credentials.
119
+
120
+ ```typescript
121
+ const result = await client.verifyPhoneNumber({
122
+ session: prepareResponse.session,
123
+ credential: 'sd-jwt-credential-from-device',
124
+ });
125
+
126
+ console.log(result.verified); // true or false
127
+ console.log(result.phone_number); // '+14155551234'
128
+ console.log(result.sim_swap?.risk_level); // 'RISK_LEVEL_LOW'
129
+ ```
130
+
131
+ ##### `getPhoneNumber(request: GetPhoneNumberRequest): Promise<GetPhoneNumberResponse>`
132
+
133
+ Retrieves the phone number associated with the device.
134
+
135
+ ```typescript
136
+ const result = await client.getPhoneNumber({
137
+ session: prepareResponse.session,
138
+ credential: 'sd-jwt-credential-from-device',
139
+ });
140
+
141
+ console.log(result.phone_number); // '+14157400083'
142
+ ```
143
+
144
+ ##### `reportInvocation(sessionId: string): Promise<ReportInvocationResponse>`
145
+
146
+ Reports when a user clicks the authenticate button (for analytics).
147
+
148
+ ```typescript
149
+ await client.reportInvocation(sessionId);
150
+ ```
151
+
152
+ ##### `checkStatus(sessionKey: string): Promise<StatusResponse>`
153
+
154
+ Polls for verification status (authenticated endpoint).
155
+
156
+ ```typescript
157
+ const status = await client.checkStatus(sessionKey);
158
+
159
+ switch (status.status) {
160
+ case 'pending':
161
+ // Continue polling
162
+ break;
163
+ case 'scanned':
164
+ // QR code scanned, show device info
165
+ console.log(status.device_info);
166
+ break;
167
+ case 'completed':
168
+ // Verification complete
169
+ console.log(status.phone_number);
170
+ break;
171
+ case 'failed':
172
+ // Verification failed
173
+ console.log(status.error);
174
+ break;
175
+ }
176
+ ```
177
+
178
+ ##### `checkStatusPublic(sessionKey: string): Promise<StatusResponse>`
179
+
180
+ Polls for verification status (public endpoint, no auth required).
181
+
182
+ ```typescript
183
+ // Safe to use from browser without exposing credentials
184
+ const status = await client.checkStatusPublic(sessionKey);
185
+ ```
186
+
187
+ ##### `invalidateToken(): void`
188
+
189
+ Forces a token refresh on the next request.
190
+
191
+ ```typescript
192
+ client.invalidateToken();
193
+ ```
194
+
195
+ ### Error Handling
196
+
197
+ All API errors are thrown as typed exceptions:
198
+
199
+ ```typescript
200
+ import {
201
+ MagicalAuthError,
202
+ ValidationError,
203
+ UnauthorizedError,
204
+ SessionNotFoundError,
205
+ CarrierNotEligibleError,
206
+ RateLimitError,
207
+ } from '@glideidentity/glide-be-node-magical-auth';
208
+
209
+ try {
210
+ await client.prepare({ ... });
211
+ } catch (error) {
212
+ if (error instanceof ValidationError) {
213
+ console.log('Validation errors:', error.fieldErrors);
214
+ } else if (error instanceof CarrierNotEligibleError) {
215
+ console.log('Carrier not supported');
216
+ } else if (error instanceof RateLimitError) {
217
+ console.log('Rate limited, retry after:', error.retryAfter);
218
+ } else if (error instanceof MagicalAuthError) {
219
+ console.log('API error:', error.code, error.message);
220
+ console.log('Request ID:', error.requestId);
221
+ }
222
+ }
223
+ ```
224
+
225
+ ### Custom HTTP Client (BYOC)
226
+
227
+ ```typescript
228
+ import type { HttpClient } from '@glideidentity/glide-be-node-magical-auth';
229
+
230
+ const customHttpClient: HttpClient = {
231
+ async request(options) {
232
+ // Your custom implementation
233
+ const response = await myHttpLibrary.request({
234
+ method: options.method,
235
+ url: options.url,
236
+ headers: options.headers,
237
+ body: options.body,
238
+ });
239
+ return response;
240
+ },
241
+ };
242
+
243
+ const client = new MagicalAuthClient({
244
+ clientId: '...',
245
+ clientSecret: '...',
246
+ httpClient: customHttpClient,
247
+ });
248
+ ```
249
+
250
+ ### Custom Logger (BYOL)
251
+
252
+ ```typescript
253
+ import type { Logger } from '@glideidentity/glide-be-node-magical-auth';
254
+
255
+ const customLogger: Logger = {
256
+ debug(message, meta) { console.debug(message, meta); },
257
+ info(message, meta) { console.info(message, meta); },
258
+ warn(message, meta) { console.warn(message, meta); },
259
+ error(message, meta) { console.error(message, meta); },
260
+ };
261
+
262
+ const client = new MagicalAuthClient({
263
+ clientId: '...',
264
+ clientSecret: '...',
265
+ logger: customLogger,
266
+ });
267
+ ```
268
+
269
+ ### Built-in Console Logger
270
+
271
+ For local development and quick smoke tests, the SDK ships a default-silent console logger with PII sanitization and a `[GlideMagicalAuth]` prefix:
272
+
273
+ ```typescript
274
+ import { MagicalAuthClient, createLogger } from '@glideidentity/glide-be-node-magical-auth';
275
+
276
+ const client = new MagicalAuthClient({
277
+ clientId: process.env.GLIDE_CLIENT_ID!,
278
+ clientSecret: process.env.GLIDE_CLIENT_SECRET!,
279
+ logger: createLogger({ debug: true }),
280
+ });
281
+ ```
282
+
283
+ Sample output:
284
+
285
+ ```
286
+ [GlideMagicalAuth] Preparing auth { use_case: 'VerifyPhoneNumber' }
287
+ [GlideMagicalAuth] Refreshing access token
288
+ [GlideMagicalAuth] Auth prepared { strategy: 'ts43', session_key: 'a1b2c3d4e5f6a7b8' }
289
+ [GlideMagicalAuth] Phone number retrieved { phone: '+141***1234' }
290
+ ```
291
+
292
+ Phone numbers, JWTs, and explicit `session_key=…` values are auto-masked; fields named `phone_number`, `credential`, `token`, `password`, `secret`, or `fe_code` are redacted to `[REDACTED]`. The default is silent (`createLogger()` with no args), so the SDK stays quiet in production unless you explicitly opt in. For Pino, Winston, or other structured loggers, prefer the BYOL pattern above.
293
+
294
+ ## Authentication Strategies
295
+
296
+ The Magical Auth backend selects one of three strategies per session, based on the carrier and the end user's device. Your application code branches on `prepareResponse.authentication_strategy`.
297
+
298
+ ### TS43
299
+
300
+ Direct credential request via the Digital Credentials API. Available in supported browsers and natively on Android via Credential Manager. Selected when the user's device exposes a compatible credential surface.
301
+
302
+ ### Link
303
+
304
+ OAuth-style redirect flow on mobile. The SDK returns a redirect URL; your application sends the user to it and the carrier completes authentication out-of-band.
305
+
306
+ ### Desktop
307
+
308
+ QR-code-based flow for desktop browsers. The SDK returns a single universal QR; the Glide mobile companion app detects the device at runtime and selects the appropriate strategy when the QR is scanned.
309
+
310
+ ## TypeScript Support
311
+
312
+ This SDK is written in TypeScript and provides full type definitions.
313
+
314
+ ### Recommended: Separate Type Imports
315
+
316
+ ```typescript
317
+ // Runtime imports
318
+ import { MagicalAuthClient } from '@glideidentity/glide-be-node-magical-auth';
319
+
320
+ // Type-only imports (clean separation)
321
+ import type {
322
+ PrepareRequest,
323
+ PrepareResponse,
324
+ VerifyPhoneNumberRequest,
325
+ VerifyPhoneNumberResponse,
326
+ StatusResponse,
327
+ UseCase,
328
+ AuthenticationStrategy,
329
+ } from '@glideidentity/glide-be-node-magical-auth/types';
330
+ ```
331
+
332
+ ### Alternative: Import from Main Entry
333
+
334
+ ```typescript
335
+ import { MagicalAuthClient } from '@glideidentity/glide-be-node-magical-auth';
336
+ import type { PrepareRequest, PrepareResponse } from '@glideidentity/glide-be-node-magical-auth';
337
+ ```
338
+
339
+ ## License
340
+
341
+ Distributed under the **Glide Identity Pre-Release SDK License** — see [LICENSE](./LICENSE). Evaluation and integration-testing use only. Contact `support@glideidentity.com` for production licensing.