@glideidentity/glide-be-node-magical-auth 3.2.0 → 3.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -9
- package/dist/index.cjs +297 -16
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +72 -8
- package/dist/index.d.ts +72 -8
- package/dist/index.js +292 -14
- package/dist/index.js.map +1 -1
- package/dist/{types-BPuPzIcL.d.cts → types-t9HAB-7Q.d.cts} +153 -40
- package/dist/{types-BPuPzIcL.d.ts → types-t9HAB-7Q.d.ts} +153 -40
- package/dist/types.d.cts +1 -1
- package/dist/types.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -126,9 +126,9 @@ const response = await client.prepare({
|
|
|
126
126
|
| `sim_swap_max_age_hours` | `number` | SIM swap query window in hours. See below. |
|
|
127
127
|
| `biometric` | `boolean` | Opt in to the TS43 biometric signal. See below. |
|
|
128
128
|
|
|
129
|
-
**`sim_swap_max_age_hours`** sets how far back a SIM/device swap check looks. Integer, **1–2400**; anything outside that range is refused with `400 VALIDATION_ERROR` before a session is created. When omitted, the server falls back to the carrier's configured `default_max_age_hours` and then to a **24
|
|
129
|
+
**`sim_swap_max_age_hours`** sets how far back a SIM/device swap check looks. Integer, **1–2400**; anything outside that range is refused with `400 VALIDATION_ERROR` before a session is created. When omitted, the server falls back to the carrier's configured `default_max_age_hours` and then to a **24-hour** default. The window that actually produced the answer comes back as `max_age_hours` on the swap payloads, so you can always tell which window you are reading. A window of 720 or more lets an undated no-swap answer grade `RISK_LEVEL_LOW`; dated answers keep their band grading (see *Reading the swap window* below).
|
|
130
130
|
|
|
131
|
-
**`biometric`** asks the device to run a biometric step during the TS43 credential ceremony and report the outcome as `biometric_verification`. It is sent as-is: `true` and explicit `false` both go on the wire; unset is omitted. On Desktop (QR), set on the parent prepare; the phone inherits it. Ignored on Link. Requesting it never makes biometric mandatory: a device that cannot perform it still authenticates.
|
|
131
|
+
**`biometric`** asks the device to run a biometric step during the TS43 credential ceremony and report the outcome as `biometric_verification`. It is sent as-is: `true` and explicit `false` both go on the wire; unset is omitted. On Desktop (QR), set on the parent prepare; the phone inherits it. Ignored on Link. Requesting it never makes biometric mandatory: a device that cannot perform it still authenticates. Biometric is unavailable on Android Chrome below 156: there Glide never asks the phone for it, avoiding the trust prompt caused by sending the claim on older Chrome, and eligibility and prepare return `biometric: "unavailable"`. Verify returns `UNSUPPORTED` when biometric was requested at prepare, or `NOT_REQUESTED` when it was requested only at invoke. Login is not blocked.
|
|
132
132
|
|
|
133
133
|
```typescript
|
|
134
134
|
const response = await client.prepare({
|
|
@@ -214,12 +214,56 @@ try {
|
|
|
214
214
|
- An empty or missing record fails closed with `RECORD_UNAVAILABLE`, so the response field can be passed straight in.
|
|
215
215
|
- Records longer than 16 KiB are rejected as `MALFORMED` before decoding.
|
|
216
216
|
- The other codes (`VerificationRecordErrorCode`) are `MALFORMED`, `DISALLOWED_HEADER`, `UNKNOWN_KEY`, `BAD_SIGNATURE`, `WRONG_ISSUER`, `WRONG_AUDIENCE` (`aud` must equal the expected audience, default your client ID), `EXPIRED`, `NOT_YET_VALID`, `NONCE_MISMATCH`, `ORIGIN_MISMATCH`, `UNSUPPORTED_VERSION` and `REVOKED_KEY`. Every failure throws `VerificationRecordError` with `status` 0.
|
|
217
|
-
- Claims that break the v1 contract fail with `MALFORMED`: `ver` must be the string `"1.0"` (otherwise `UNSUPPORTED_VERSION`), `verified` a boolean, `jti`, `nonce` and `sub` (`tel:+E164`) non-empty strings, `nbf` equal to `iat`, `use_case` exactly `VerifyPhoneNumber`, `origin` (canonical device origin, `UNKNOWN` on Link) and `biometric_verification` strings, `exp` 1 to 60 s after `iat`, and `sign_offs` an array of entries with non-empty `role`, `signer` and `status` (`unavailable` with a `reason`, or `present` with `format` and `token`), exactly one of them a `carrier` entry signed `carrier:<id>`. Optional `strategy` (`TS_43`, `LINK`, `DESKTOP__TS_43`, `DESKTOP__LINK`, `DESKTOP`), `phone_number_details`, `carrier` (`{id, name, mvno}`), `sim_swap` and `
|
|
217
|
+
- Claims that break the v1 contract fail with `MALFORMED`: `ver` must be the string `"1.0"` (otherwise `UNSUPPORTED_VERSION`), `verified` a boolean, `jti`, `nonce` and `sub` (`tel:+E164`) non-empty strings, `nbf` equal to `iat`, `use_case` exactly `VerifyPhoneNumber`, `origin` (canonical device origin, `UNKNOWN` on Link) and `biometric_verification` strings, `exp` 1 to 60 s after `iat`, and `sign_offs` an array of entries with non-empty `role`, `signer` and `status` (`unavailable` with a `reason`, or `present` with `format` and `token`), exactly one of them a `carrier` entry signed `carrier:<id>`. Optional `strategy` (`TS_43`, `LINK`, `DESKTOP__TS_43`, `DESKTOP__LINK`, `DESKTOP`, `PASSKEY`, `CALL__TS_43`, `CALL__LINK`, `CALL`), `phone_number_details`, `carrier` (`{id, name, mvno}`), `sim_swap`, `device_swap` and `live_call` are accepted when present; a wrong JSON type, a `carrier` without a non-empty string `id`, or a `carrier.id` that does not match the carrier sign-off signer (`carrier:<id>`), is `MALFORMED`. Record `sim_swap` / `device_swap` carry `age_band` `{from, to}` in hours (`-1` unknown) and omit `checked_at` — `iat` is the authoritative check time.
|
|
218
218
|
- Keys come only from `<baseUrl>/.well-known/us/jwks.json` (it carries both regions' record keys), cached per `Cache-Control` (300 s default); nothing in the token picks a URL. Only Glide's record-signing kids are accepted. Glide keeps a retired record key published for at least 90 days (the default `maxAuditAgeSeconds`); a record whose key has since been unpublished fails `UNKNOWN_KEY`, even with `allowExpired`.
|
|
219
219
|
- Set `expectedAudience` to the record audience you configured in the developer portal (empty checks your client ID). To pin the device origin, set `expectedOrigin` (a list): the record's canonical `origin` must equal one entry exactly, else `ORIGIN_MISMATCH`; Link records carry `UNKNOWN`, so leave `UNKNOWN` out of the list to reject them.
|
|
220
220
|
- To audit a stored record after `exp`, set `allowExpired: true`; `iat` must still be within `maxAuditAgeSeconds` (90 days by default) and revoked kids (`revokedKids` plus the built-in list) are always rejected. `issuer` overrides the expected `iss` (default: the base URL).
|
|
221
221
|
- In v1 `claims.sign_offs` holds one `carrier` entry with status `unavailable`; `signOffResults` reports it as `unavailable`, and a present sign-off would be reported `unverified`, never trusted.
|
|
222
222
|
- Integer claims follow `JSON.parse`, so `1.0` is accepted where an integer is required (the Go and Java SDKs reject it); Glide never signs such values.
|
|
223
|
+
- `claims.factors` lists the factors that passed (`['carrier']` when the record omits `factors`, `['passkey', 'carrier']` on a verified step-up, `['passkey']` on a passkey sign-in). A passkey-only record has no carrier sign-off; any other record needs exactly one. `claims.action_hash` is set only on a verified step-up.
|
|
224
|
+
|
|
225
|
+
##### Step-up (passkey + carrier)
|
|
226
|
+
|
|
227
|
+
Approve a specific action with both a passkey and the carrier. Prepare with the passkey origin and the action:
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
import { actionHash } from '@glideidentity/glide-be-node-magical-auth';
|
|
231
|
+
|
|
232
|
+
const action = { type: 'transfer', amount: '250.00', currency: 'USD', to: 'acct_123' };
|
|
233
|
+
const prep = await client.prepare({
|
|
234
|
+
phone_number: '+14155551234',
|
|
235
|
+
use_case: 'VerifyPhoneNumber',
|
|
236
|
+
client_info: { user_agent: req.headers['user-agent'] },
|
|
237
|
+
options: { passkey: { enabled: true, origin: 'https://app.example.com' }, step_up: { action } },
|
|
238
|
+
});
|
|
239
|
+
// prep.passkey.public_key goes to the browser's WebAuthn get(); prep.step_up.action_hash === actionHash(action)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
On verify, forward the browser's assertion JSON string as `passkey_assertion`. The response adds `passkey: 'used'` and `step_up` (`passkey`, `carrier`, `action_hash`). Before executing the action, check the record:
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
const rec = await client.verifyStepUp(result.verification_record, action, '+14155551234');
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
`verifyStepUp(record, action, phoneNumber, maxAgeSeconds = 300)` accepts the record past `exp` while `iat` is within `maxAgeSeconds` (an older record fails with `EXPIRED` even before `exp`), and fails with `STEP_UP_REJECTED` unless it is verified, has both the `passkey` and `carrier` factors, its `action_hash` equals `actionHash(action)` (keys sorted, `key=value` joined by `|`, base64url SHA-256) and `sub` is `tel:<phoneNumber>`.
|
|
249
|
+
If you configured a custom record audience, pass it as the fifth argument, `expectedAudience`.
|
|
250
|
+
|
|
251
|
+
- A record is not single-use: store `rec.claims.jti` and refuse a record whose `jti` you have already accepted before executing the action.
|
|
252
|
+
- Plain `verifyVerificationRecord` also accepts passkey-only records (`factors: ['passkey']`); to require a carrier verification, check that `claims.factors` contains `'carrier'`.
|
|
253
|
+
- `claims.strategy` can be `PASSKEY`.
|
|
254
|
+
|
|
255
|
+
##### Delete passkeys
|
|
256
|
+
|
|
257
|
+
Sign a user out of passkeys on one of your registered origins. Your backend vouches for the user; Glide checks only that the origin is registered to this application.
|
|
258
|
+
|
|
259
|
+
```typescript
|
|
260
|
+
const { deleted_credential_ids } = await client.deletePasskeys({
|
|
261
|
+
phone_number: '+14155551234',
|
|
262
|
+
origin: 'https://app.example.com',
|
|
263
|
+
});
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Returns the deleted credential ids (empty when there were none); pass each to the web SDK's `PasskeyClient.signalUnknownCredential(rpId, id)` so the browser drops it. Errors: `VALIDATION_ERROR`, `FORBIDDEN` (origin not registered), `BAD_REQUEST` (passkeys not enabled, or the scope was refused), `SERVICE_UNAVAILABLE`.
|
|
223
267
|
|
|
224
268
|
##### `getPhoneNumber(request: GetPhoneNumberRequest): Promise<GetPhoneNumberResponse>`
|
|
225
269
|
|
|
@@ -247,17 +291,17 @@ console.log(result.phone_number); // '+14157400083'
|
|
|
247
291
|
| `age_band` | `string` | When the SIM last changed, e.g. `"0-4 hours"`, `"7-14 days"`, `"more than 3 years"`, `"older than query window"`, `"temporarily unavailable"`, `"not available"`. |
|
|
248
292
|
| `carrier_name` | `string` | The carrier that performed the check. |
|
|
249
293
|
| `checked_at` | `string` | When the check ran, RFC3339. Kept as a string — the SDK passes the wire value through without parsing. |
|
|
250
|
-
| `swapped` | `boolean` | Whether a swap fell inside `max_age_hours`. **Omitted when the carrier gave no determinable answer**
|
|
294
|
+
| `swapped` | `boolean` | Whether a swap fell inside `max_age_hours`. **Omitted when the carrier gave no determinable answer** — that is not the same as `false`. |
|
|
251
295
|
| `max_age_hours` | `number` | The window this answer actually describes. |
|
|
252
296
|
| `reason` | `SimSwapFailureReason` | Only when `checked` is `false`: `timeout`, `carrier_not_supported`, `disabled`, `error`. |
|
|
253
297
|
|
|
254
298
|
###### `DeviceSwapInfo`
|
|
255
299
|
|
|
256
|
-
Device (IMEI) change, reported only by carriers that support it
|
|
300
|
+
Device (IMEI) change, reported only by carriers that support it. It is a fully independent signal, not a variant of `SimSwapInfo`: identical fields **except that it has no `reason`**, because the server never populates one.
|
|
257
301
|
|
|
258
302
|
###### Reading the swap window
|
|
259
303
|
|
|
260
|
-
An absent `swapped` means the check was inconclusive — the carrier gave no determinable age. `RISK_LEVEL_UNKNOWN` is broader
|
|
304
|
+
An absent `swapped` means the check was inconclusive — the carrier gave no determinable age. `RISK_LEVEL_UNKNOWN` is broader. A carrier that answers only whether the line changed inside the window, and confirms it did not, returns `swapped: false` and `age_band: "older than query window"`, and that undated answer is graded by the window. When `max_age_hours` is **720 (30 days) or more** it grades `RISK_LEVEL_LOW`, because any swap is at least that old. Below 720 it grades `RISK_LEVEL_UNKNOWN`, because the carrier never dated the last swap, so code reading `LOW` as "safe" falls through to its default; set `sim_swap_max_age_hours` to 720 or more to get a grade for a clean line. Branch on `swapped` for "was there a swap in my window"; read `RISK_LEVEL_UNKNOWN` as "no risk grade available", not as a good or bad outcome.
|
|
261
305
|
|
|
262
306
|
A known `age_band` together with `swapped: false` is not a contradiction: it means the carrier dated the last swap and it fell outside the window. The flag is the band overlapped with the window, and a band straddling the boundary resolves to swapped rather than to an unknown — so with a 24-hour window a `"14-30 days"` band gives `swapped: false` alongside `RISK_LEVEL_MEDIUM`, because risk comes from the band's own recency, not from the window.
|
|
263
307
|
|
|
@@ -329,6 +373,33 @@ Polls for verification status (public endpoint, no auth required).
|
|
|
329
373
|
const status = await client.checkStatusPublic(sessionKey);
|
|
330
374
|
```
|
|
331
375
|
|
|
376
|
+
### Verify a caller on a phone call
|
|
377
|
+
|
|
378
|
+
Prepare with `options.call.called_number` and `authentication_strategy` `call`, deliver `data.url` to the caller's phone over your own SMS, RCS or IVR, poll `checkStatus` for `stage` and `live_call`, then verify with `credential` set to the session key. `live_call.status` `active` means a recent call from the caller to the called number, not proof the call is still connected.
|
|
379
|
+
|
|
380
|
+
```typescript
|
|
381
|
+
import {
|
|
382
|
+
AuthenticationStrategy,
|
|
383
|
+
type CallStrategyData,
|
|
384
|
+
} from '@glideidentity/glide-be-node-magical-auth';
|
|
385
|
+
|
|
386
|
+
const prep = await client.prepare({
|
|
387
|
+
phone_number: '+12125550100',
|
|
388
|
+
nonce: 'unique-nonce',
|
|
389
|
+
use_case: 'VerifyPhoneNumber',
|
|
390
|
+
authentication_strategy: AuthenticationStrategy.CALL,
|
|
391
|
+
client_info: { user_agent: 'contact-center-backend/1.0' },
|
|
392
|
+
options: { call: { called_number: '+12125550199' } },
|
|
393
|
+
});
|
|
394
|
+
const { url } = prep.data as CallStrategyData;
|
|
395
|
+
// deliver url; poll for stage and live_call:
|
|
396
|
+
const status = await client.checkStatus(prep.session.session_key!);
|
|
397
|
+
const verify = await client.verifyPhoneNumber({
|
|
398
|
+
session: prep.session,
|
|
399
|
+
credential: prep.session.session_key!,
|
|
400
|
+
});
|
|
401
|
+
```
|
|
402
|
+
|
|
332
403
|
##### `invalidateToken(): void`
|
|
333
404
|
|
|
334
405
|
Forces a token refresh on the next request.
|
|
@@ -350,6 +421,7 @@ import {
|
|
|
350
421
|
CarrierNotEligibleError,
|
|
351
422
|
CarrierRejectedError,
|
|
352
423
|
CarrierAppUnavailableError,
|
|
424
|
+
CarrierTemporarilyUnavailableError,
|
|
353
425
|
RateLimitError,
|
|
354
426
|
} from '@glideidentity/glide-be-node-magical-auth';
|
|
355
427
|
|
|
@@ -366,6 +438,9 @@ try {
|
|
|
366
438
|
} else if (error instanceof CarrierAppUnavailableError) {
|
|
367
439
|
// Desktop (QR): the scanning phone has no working carrier app; terminal, start a new QR
|
|
368
440
|
console.log('Carrier app unavailable; start a new QR flow');
|
|
441
|
+
} else if (error instanceof CarrierTemporarilyUnavailableError) {
|
|
442
|
+
// 422: transient carrier outage; retry after error.retryAfter (Retry-After header, else details.retry_after_seconds)
|
|
443
|
+
console.log('Carrier temporarily unavailable, retry after:', error.retryAfter);
|
|
369
444
|
} else if (error instanceof RateLimitError) {
|
|
370
445
|
console.log('Rate limited, retry after:', error.retryAfter);
|
|
371
446
|
} else if (error instanceof MagicalAuthError) {
|
|
@@ -384,9 +459,12 @@ which map to a typed class. They arrive as a base `MagicalAuthError` carrying th
|
|
|
384
459
|
always keep the `instanceof MagicalAuthError` fallback last and read `error.code` from it rather
|
|
385
460
|
than assuming the specific classes are total.
|
|
386
461
|
|
|
387
|
-
The edge can also answer
|
|
388
|
-
|
|
389
|
-
|
|
462
|
+
The edge can also answer with a `text/plain` body rather than the JSON error envelope. The client
|
|
463
|
+
only parses JSON, so those surface as `code: 'UNKNOWN_ERROR'` with the status preserved. A known
|
|
464
|
+
body `code` is always typed from the code first, so a `429` carrying a recognized code (e.g.
|
|
465
|
+
`BAD_REQUEST`) becomes that code's class (`BadRequestError`); only a `429` with no known code falls
|
|
466
|
+
back to `RateLimitError`. For other statuses without a known code, branch on `error.status` as well
|
|
467
|
+
as `error.code`.
|
|
390
468
|
|
|
391
469
|
### Custom HTTP Client (BYOC)
|
|
392
470
|
|