@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 +35 -0
- package/README.md +341 -0
- package/dist/index.cjs +1275 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +419 -0
- package/dist/index.d.ts +419 -0
- package/dist/index.js +1204 -0
- package/dist/index.js.map +1 -0
- package/dist/types-DKfytuP6.d.cts +858 -0
- package/dist/types-DKfytuP6.d.ts +858 -0
- package/dist/types.cjs +19 -0
- package/dist/types.cjs.map +1 -0
- package/dist/types.d.cts +1 -0
- package/dist/types.d.ts +1 -0
- package/dist/types.js +1 -0
- package/dist/types.js.map +1 -0
- package/package.json +66 -0
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.
|