# @glideidentity/glide-be-node-magical-auth 中文文档

规范地址：https://npmcn.com/package/%40glideidentity/glide-be-node-magical-auth/

版本：3\.2\.0
npm 元数据更新时间：2026-10-08T16:25:44.039Z
中文译文更新时间：2026-11-16T16:02:09.973Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40glideidentity/glide-be-node-magical-auth
原文对照：https://npmcn.com/package/%40glideidentity/glide-be-node-magical-auth/?lang=original
项目主页：https://github.com/GlideIdentity/publish-magical-auth-be-sdks/tree/master/sdks/node#readme
源码仓库：https://github.com/GlideIdentity/publish-magical-auth-be-sdks

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：631 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-05-18T12:43:52.535Z
- 最新版本发布：2026-10-08T16:25:43.840Z
- 近 30 天下载量：3788（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Glide Magical Auth SDK for Node.js - 没有短消息/OTP的电话号码认证

## 安装

```sh
npm install @glideidentity/glide-be-node-magical-auth
```

也可以使用：`pnpm add @glideidentity/glide-be-node-magical-auth`、`yarn add @glideidentity/glide-be-node-magical-auth`、`bun add @glideidentity/glide-be-node-magical-auth`

## README

# @glideidentity/glide-be-node-magical-auth (英语)

Glide Magical Auth SDK for Node.js ——没有短信/OTP的电话号码认证,使用以载体为基础的数字证书.

## 特征

-   **无依赖** - 只使用节点(18+)
-   **类型脚本第一** - 具有出色的IntelliSense支持的全型安全
-   **叙利亚** - 将您的 HTTP 客户端引入自定义执行
-   **再见** - 带自己的Logger去自定义记录
-   **自动调试管理** - OAuth2 令牌缓存并自动刷新
-   **线索安全** - 安全地同时使用,同时减少承诺

## 安装

```bash
npm install @glideidentity/glide-be-node-magical-auth
```

## 所需资源

-   节点.js 18.0.0或以上

## 快速启动

```typescript
import { MagicalAuthClient } from '@glideidentity/glide-be-node-magical-auth';

const client = new MagicalAuthClient({
  clientId: process.env.GLIDE_CLIENT_ID!,
  clientSecret: process.env.GLIDE_CLIENT_SECRET!,
});

// 1. Prepare authentication
const prepareResponse = await client.prepare({
  phone_number: '+14155551234',
  nonce: crypto.randomUUID(),
  use_case: 'VerifyPhoneNumber',
  client_info: {
    user_agent: navigator.userAgent,
  },
});

// 2. Handle based on authentication strategy
switch (prepareResponse.authentication_strategy) {
  case 'ts43':
    // Direct credential request via the Digital Credentials API
    // (available in supported browsers and natively on Android via Credential Manager).
    // Use the data.dcql_query payload to invoke the API on your client.
    break;

  case 'link':
    // OAuth-style redirect flow on mobile.
    // Redirect the user to prepareResponse.data.url.
    break;

  case 'desktop':
    // QR-code flow for desktop browsers. The `data` field is a
    // DesktopStrategyData wrapper; the QR payload lives at `data.data`:
    //   const desktop = prepareResponse.data; // DesktopStrategyData
    //   render(desktop.data.qr_image);        // base64 PNG data URL
    //   showChallenge(prepareResponse.challenge?.pattern);
    break;
}

// 3. Verify the phone number with credential from device
const verifyResponse = await client.verifyPhoneNumber({
  session: prepareResponse.session,
  credential: credentialFromDevice,
});

if (verifyResponse.verified) {
  console.log('Phone verified:', verifyResponse.phone_number);
}
```

## API 参考

### 魔法认证客户端

与"魔法Auth API"互动的主要客户类.

#### 构造器

```typescript
new MagicalAuthClient(config: MagicalAuthConfig)
```

| 选项 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `clientId` | `string` | 对 | \- 说吧 | OAuth2 客户端标识 |
| `clientSecret` | `string` | 对 | \- 说吧 | OAuth2 客户端秘密 |
| `baseUrl` | `string` | 没有 | `https://api.glideidentity.app` | API 基础 URL |
| `httpClient` | `HttpClient` | 没有 | 原始获取 | 自定义 HTTP 客户端 |
| `logger` | `Logger` | 没有 | 无 -OP | 自定义日志 |
| `timeout` | `number` | 没有 | `30000` | 请求超时( ms) |

#### 方法

##### `prepare(request: PrepareRequest): Promise<PrepareResponse>`

通过检查承运人资格和生成特定协议请求来准备认证.

```typescript
const response = await client.prepare({
  phone_number: '+14155551234',  // Required for VerifyPhoneNumber
  plmn: { mcc: '310', mnc: '260' },  // Optional carrier identifier
  nonce: 'unique-nonce',  // Required, base64url encoded
  use_case: 'VerifyPhoneNumber',  // or 'GetPhoneNumber'
  client_info: { user_agent: '...' },  // Optional, helps strategy selection
  consent_data: { ... },  // Optional consent text
  options: { theme: 'dark' },  // Optional UI theme
});
```

###### `PrepareOptions`

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `parent_session_id` | `string` | 桌面 QR 流的父会话——将其设定在伴侣/孩子准备上. |
| `theme` | `Theme` | UI主题逐字传送到每个触点. `"dark"` 编号 : `"light"`,或任何自定义标识符(最大 32个字符). |
| `link_type` | `LinkType` | 覆盖链接发送( E)`app_clip`, (中文(简体) ), `app_link`, (中文(简体) ), `headless`, (中文(简体) ), `web_link`) (中文(简体) ). 仅限链接策略. |
| `network_origin` | `NetworkOrigin` | 这个 **服务器观测** 请求设备的IP,由您的后端所盖. 把它印在两个准备 `network_check` 回来 永远不要相信客户端提供的价值. |
| `mobile_companion_passthrough` | `Record<string, unknown>` | 不透明JSON转发到品牌相伴应用. 仅限对象, QQ16 KB. |
| `completion_redirect_url` | `string` | 浏览器在认证完成后降落的地方 。 选择您注册的应用程序之一 `completion_redirect_urls` (RFC 6749§3.1.2的精确匹配数). 从您自己的部署源头上盖上服务器的标签 — 从请求中找不到 `Host` 标题或任何客户端可控值. |
| `sim_swap_max_age_hours` | `number` | SIM 小时后互换查询窗口. 见下文. |
| `biometric` | `boolean` | 进入TS43生物识别信号 见下文. |

**`sim_swap_max_age_hours`** 设定SIM/device互换检查的外观的后退。 整数, **1–2400 (中文(简体) )**; 任何超出此范围者都会被拒绝使用 `400 VALIDATION_ERROR` 在创建会话之前。 省略时, 服务器会回到载体配置 `default_max_age_hours` 然后变成a **24小时** 默认。 真正产生答案的窗口 `max_age_hours` 在交换有效载荷,所以你总是可以 知道你正在读哪个窗口.

**`biometric`** 请设备在TS43认证仪式上运行生物鉴别步骤,并将结果报告为 `biometric_verification`以下列方式发送: `true` 和明确 `false` 两者都上线;未设置被省略. 在桌面上(QR),设定在父准备上;电话继承. 忽略了链接。 要求它从不要求生物鉴别:无法进行生物鉴别的装置仍然具有认证性.

```typescript
const response = await client.prepare({
  phone_number: '+14155551234',
  nonce: 'unique-nonce',
  use_case: 'VerifyPhoneNumber',
  client_info: { user_agent: req.headers['user-agent'] },
  options: {
    sim_swap_max_age_hours: 72,
    biometric: true,
  },
});
```

##### `prepareMultiple(request: PrepareMultipleRequest, options?: RequestOptions): Promise<PrepareMultipleResult[]>`

为最多 `PREPARE_MULTIPLE_MAX` (10) 一个电话的电话号码。 扇出一个普通的 `prepare` 每个数字——每个得到自己的非ce、会话和(用于链接策略) `feCode`编号 :`feHash`按输入顺序返回每个输入数一个结果.

偶数失败在数组中返回,而不是抛出 。 方法只针对呼叫者输入出错( 空列表、 超盖、 空白条目, 或共享准备字段) `prepare` 在发出任何HTTP请求之前.

`CARRIER_NOT_ELIGIBLE` 财务报告和审定财务报表 `CARRIER_TEMPORARILY_UNAVAILABLE` hTTP 422都是;只有代码显示一个瞬变的、可重复试验的载体停用——每个故障项目上的分支 `error` (单位:千美元)`instanceof CarrierNotEligibleError` 或者说 `item.error.code`),不处于状态,或瞬间断开的号码被隐藏为永久不合格.

脱 `feCode` 从每个成功结果转发到浏览器之前 —— 这是设备绑定的秘密, 绝不能到达客户端的 JavaScript .

传个短 `session_timeout` (60-900秒,与 `prepare`)如此未经挑选的会话很快就会到期.

```typescript
const results = await client.prepareMultiple({
  use_case: 'VerifyPhoneNumber',
  phone_numbers: ['+14155551234', '+14155559876'],
  client_info: { user_agent: req.headers['user-agent'] },
  session_timeout: 120,
});

const picker = results
  .filter((r) => r.ok)
  .map((r) => {
    const { feCode, ...prepareForClient } = r.result;
    return {
      id: myPhoneIdFor(r.phone_number),
      label: mask(r.phone_number),
      prepare: prepareForClient,
    };
  });
```

TypeScript 使用受歧视的结合 `ok` (单位:千美元)`{ ok: true; result } | { ok: false; error }`) (中文(简体) ). Go and Java通过已失效的字段暴露出相同的语义 `OK()` 编号 : `isOk()`。 。 。 .

##### `verifyPhoneNumber(request: VerifyPhoneNumberRequest): Promise<VerifyPhoneNumberResponse>`

使用数字证书验证电话号码.

```typescript
const result = await client.verifyPhoneNumber({
  session: prepareResponse.session,
  credential: 'sd-jwt-credential-from-device',
});

console.log(result.verified);  // true or false
console.log(result.phone_number);  // '+14155551234'
console.log(result.sim_swap?.risk_level);  // 'RISK_LEVEL_LOW'
```

##### 核查已签署的核查记录

答复还附有: `verification_record`,用胶片标记的ES256 JWS的核查结果,以及 `verification_record_status` (单位:千美元)`'signed'` 或者说 `'unavailable'`) (中文(简体) ). 以后需要证明结果时保留记录,用 `verifyVerificationRecord(record, options?)`,通过你派来准备的空格:

```typescript
import { VerificationRecordError, VerificationRecordErrorCode } from '@glideidentity/glide-be-node-magical-auth';

try {
  const { claims, signOffResults } = await client.verifyVerificationRecord(result.verification_record, {
    expectedNonce: prepareNonce,
  });
  console.log(claims.verified, claims.sub);
} catch (err) {
  if (err instanceof VerificationRecordError && err.code === VerificationRecordErrorCode.RECORD_UNAVAILABLE) {
    // no signed record for this result
  }
}
```

-   空白或缺失的记录未关闭 `RECORD_UNAVAILABLE`,所以反应场可以直接通过.
-   超过16个KiB的记录被拒绝,因为 `MALFORMED` 在解码之前.
-   其他代码( :`VerificationRecordErrorCode`已经 `MALFORMED`, (中文(简体) ), `DISALLOWED_HEADER`, (中文(简体) ), `UNKNOWN_KEY`, (中文(简体) ), `BAD_SIGNATURE`, (中文(简体) ), `WRONG_ISSUER`, (中文(简体) ), `WRONG_AUDIENCE` (单位:千美元)`aud` 必须等于预期的观众,默认客户端身份, `EXPIRED`, (中文(简体) ), `NOT_YET_VALID`, (中文(简体) ), `NONCE_MISMATCH`, (中文(简体) ), `ORIGIN_MISMATCH`, (中文(简体) ), `UNSUPPORTED_VERSION` 财务报告和审定财务报表 `REVOKED_KEY`。每次失败 `VerificationRecordError` 与 `status` 零点.
-   违反v1合同的索赔 `MALFORMED`数字 : `ver` 必须是字符串 `"1.0"` (否则) `UNSUPPORTED_VERSION`, (中文(简体) ), `verified` 一个布尔人, `jti`, (中文(简体) ), `nonce` 财务报告和审定财务报表 `sub` (单位:千美元)`tel:+E164`非空弦, `nbf` 等于 `iat`, (中文(简体) ), `use_case` 没错 `VerifyPhoneNumber`, (中文(简体) ), `origin` (脑电图来源, `UNKNOWN` (关于链接)和 `biometric_verification` 字符串, `exp` 1至60 s 后为 `iat`,以及 `sign_offs` 非空项数组 `role`, (中文(简体) ), `signer` 财务报告和审定财务报表 `status` (单位:千美元)`unavailable` 带有 `reason`,或 `present` 与 `format` 财务报告和审定财务报表 `token`),确切的其中之一a `carrier` 签名条目 `carrier:<id>`可选 `strategy` (单位:千美元)`TS_43`, (中文(简体) ), `LINK`, (中文(简体) ), `DESKTOP__TS_43`, (中文(简体) ), `DESKTOP__LINK`, (中文(简体) ), `DESKTOP`, (中文(简体) ), `phone_number_details`, (中文(简体) ), `carrier` (单位:千美元)`{id, name, mvno}`, (中文(简体) ), `sim_swap` 财务报告和审定财务报表 `device_swap` ; 错误的 JSON 类型, a `carrier` 没有非空字符串 `id`,或一个 `carrier.id` 与承运人的签出签出人不符的(`carrier:<id>`),为 `MALFORMED`记录 `sim_swap` 编号 : `device_swap` 携带 `age_band` `{from, to}` 小时数`-1` 未知)和省略 `checked_at` —— 说 `iat` 是权威检查时间.
-   钥匙只来自 `<baseUrl>/.well-known/us/jwks.json` (带有两个区域的记录密钥),缓存 `Cache-Control` (300 s 默认值); 符号中没有选择 URL 。 只有格利德的唱片签的孩子们被接受. Glide 保存已退休的记录密钥至少90天(默认) `maxAuditAgeSeconds`);该记录的密钥自此未公布 `UNKNOWN_KEY`,即使与 `allowExpired`。 。 。 .
-   设定 `expectedAudience` 用于您在开发者门户网站中配置的记录受众(空检查您的客户端身份)。 要将设备源头标出, 设置 `expectedOrigin` (一个列表):记录的犬形 `origin` 必须完全等于一个条目,否则 `ORIGIN_MISMATCH`; 链接记录携带 `UNKNOWN`离开吧 `UNKNOWN` 离开名单 拒绝他们.
-   对保存的记录进行审计 `exp`设置 `allowExpired: true`· ; `iat` 一定还在 `maxAuditAgeSeconds` (默认90天)和被吊销的儿童(`revokedKids` 加上内置列表)总是被拒绝. `issuer` 覆盖预期 `iss` (默认: 基准 URL).
-   在一年级 `claims.sign_offs` 持有一个 `carrier` 有地位的条目 `unavailable`· ; `signOffResults` 报告为: `unavailable`,并报告当前签注 `unverified`从不相信.
-   整数索赔如下 `JSON.parse`这样 `1.0` 在需要整数时被接受(Go和Java SDKs拒绝); 胶片从不标出这种价值.

##### `getPhoneNumber(request: GetPhoneNumberRequest): Promise<GetPhoneNumberResponse>`

获取与设备相关的电话号码.

```typescript
const result = await client.getPhoneNumber({
  session: prepareResponse.session,
  credential: 'sd-jwt-credential-from-device',
});

console.log(result.phone_number);  // '+14157400083'
```

##### 关于成功对策的风险信号

`VerifyPhoneNumberResponse` 财务报告和审定财务报表 `GetPhoneNumberResponse` 携带相同的信号: `biometric_verification`,加上可选 `sim_swap`, (中文(简体) ), `device_swap` 财务报告和审定财务报表 `phone_number_details`在承运人或会议未产生时,每个可选部分被省略,因此,在存在时的分支而不是假设病态值是有意义的.

###### `SimSwapInfo`

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `checked` | `boolean` | 检查是否完成 。 何时 `false`读取 `reason` 并无视其余的. |
| `risk_level` | `RiskLevel` | `RISK_LEVEL_HIGH` | `RISK_LEVEL_MEDIUM` | `RISK_LEVEL_LOW` | `RISK_LEVEL_UNKNOWN`。 。 。 . |
| `age_band` | `string` | 当SIM最后一次改变,例如. `"0-4 hours"`, (中文(简体) ), `"7-14 days"`, (中文(简体) ), `"more than 3 years"`, (中文(简体) ), `"older than query window"`, (中文(简体) ), `"temporarily unavailable"`, (中文(简体) ), `"not available"`。 。 。 . |
| `carrier_name` | `string` | 完成检查的承运人. |
| `checked_at` | `string` | 当支票运行,RFC3339。 被固定为字符串——SDK通过线值而不解析. |
| `swapped` | `boolean` | 交换是否坠入其中 `max_age_hours`。 。 。 . **当承运人没有给出可确定的答案时即被允许** (T-移动代码) `999` 编号 : `NA`()——这与 `false`。 。 。 . |
| `max_age_hours` | `number` | 此答案所描述的窗口 . |
| `reason` | `SimSwapFailureReason` | 只有当 `checked` 实值 `false`数字 : `timeout`, (中文(简体) ), `carrier_not_supported`, (中文(简体) ), `disabled`, (中文(简体) ), `error`。 。 。 . |

###### `DeviceSwapInfo`

设备(IMEI)改变,仅由支持它的载体报告——目前为T-Mobile. 这是一个完全独立的信号,而不是一个变体 `SimSwapInfo`: 相同的字段 **但它没有 `reason`**,因为服务器从不包含一个.

###### 读取互换窗口

缺席 `swapped` 说明检查没有结果——承运人没有给出可确定的年龄. `RISK_LEVEL_UNKNOWN` 范围更广:它涵盖这一没有定论的案件 **财务报告和审定财务报表** 一个 CAMARA 载体成功确认窗口内没有互换, 返回 `swapped: false` 财务报告和审定财务报表 `age_band: "older than query window"` 但仍保持等级 `RISK_LEVEL_UNKNOWN`,因为承运人从来没有约会 上次互换。 第二个案子曾经报告 `RISK_LEVEL_LOW`代码读取 `LOW` 因为现在"安全" 陷入默认。 分会 `swapped` "我的窗户有没有换",读 `RISK_LEVEL_UNKNOWN` 作为"没有风险等级可用",而不是作为好或坏的结果.

一个已知 `age_band` 合并 `swapped: false` 并非自相矛盾:这意味着承运人在上次互换之后掉入了窗口外。 旗帜是同窗口相重叠的乐队,一个跨越边界的乐队决心互换而不是一个未知的——所以有一个24小时的窗口 a `"14-30 days"` 带状 `swapped: false` 并行 `RISK_LEVEL_MEDIUM`,因为风险来自乐团本身的反思,而不是从窗口.

```typescript
const s = result.sim_swap;
if (s?.checked) {
  if (s.swapped === undefined) {
    // carrier could not determine an age for this window
  } else if (s.swapped) {
    console.log(`SIM swapped within ${s.max_age_hours}h (${s.age_band})`);
  }
}
```

###### `biometric_verification`

`biometric_verification` 以 `BiometricVerification`。 。 。 .

| 数值 | 含义 |
| --- | --- |
| `VERIFIED` | 该装置进行了生物鉴别核查. |
| `FAILED` | 该装置尝试并报告故障. |
| `NOT_ENROLLED` | 该装置上没有生物鉴别技术. |
| `UNSUPPORTED` | 要求进行生物测量,但没有任何可用结果. |
| `NOT_REQUESTED` | 无所报. |

在验证时,它等于签名记录 `biometric_verification` 索赔。 本列表外的值被保留为发送,因此将任何未识别出的东西视为"没有有用的信号". 这是一种信号,而不是认证结果——无论哪种方式都核实电话号码.

##### `reportInvocation(sessionId: string): Promise<ReportInvocationResponse>`

当用户点击认证按钮时报告(用于分析).

```typescript
await client.reportInvocation(sessionId);
```

##### `checkStatus(sessionKey: string): Promise<StatusResponse>`

核查状态的投票(认证终点).

```typescript
const status = await client.checkStatus(sessionKey);

switch (status.status) {
  case 'pending':
    // Continue polling
    break;
  case 'scanned':
    // QR code scanned, show device info
    console.log(status.device_info);
    break;
  case 'completed':
    // Verification complete
    console.log(status.phone_number);
    break;
  case 'failed':
    // Verification failed
    console.log(status.error);
    break;
}
```

##### `checkStatusPublic(sessionKey: string): Promise<StatusResponse>`

核查状态的投票(公用终点,不需要认证).

```typescript
// Safe to use from browser without exposing credentials
const status = await client.checkStatusPublic(sessionKey);
```

##### `invalidateToken(): void`

在下次请求时强制更新一个符号 .

```typescript
client.invalidateToken();
```

### 处理错误

所有 API 出错均作为打出例外 :

```typescript
import {
  MagicalAuthError,
  ValidationError,
  UnauthorizedError,
  SessionNotFoundError,
  CarrierNotEligibleError,
  CarrierRejectedError,
  CarrierAppUnavailableError,
  RateLimitError,
} from '@glideidentity/glide-be-node-magical-auth';

try {
  await client.prepare({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation errors:', error.fieldErrors);
  } else if (error instanceof CarrierNotEligibleError) {
    console.log('Carrier not supported');
  } else if (error instanceof CarrierRejectedError) {
    // Carrier rejected a device-bound (link/desktop) auth
    console.log('Carrier rejected:', error.details?.carrier_error, error.details?.stage);
  } else if (error instanceof CarrierAppUnavailableError) {
    // Desktop (QR): the scanning phone has no working carrier app; terminal, start a new QR
    console.log('Carrier app unavailable; start a new QR flow');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof MagicalAuthError) {
    console.log('API error:', error.code, error.message);
    console.log('Request ID:', error.requestId);
  }
}
```

#### 输入错误类别并非详尽无遗

上面的分类涵盖了今天值得分支的代码; API 可以返回没有的代码 课. `specs/openapi.yaml` 当前文档 `TOKEN_ACQUISITION_FAILED`, (中文(简体) ), `INVALID_PARAMETERS`, (中文(简体) ), `UNPROCESSABLE_ENTITY`, (中文(简体) ), `UNEXPECTED_ERROR` 财务报告和审定财务报表 `COMPLETION_REDIRECT_URL_NOT_REGISTERED`,没有 哪个映射到打入的类。 他们作为基地到达 `MagicalAuthError` 携带生 `code`这样 永远留着 `instanceof MagicalAuthError` 倒数最后读取 `error.code` 从它更 而不是假设特定类别是总数.

边缘也可以回答 `401` 财务报告和审定财务报表 `429` 带有 `text/plain` 身体而不是 JSON 错误 信封上写着 客户端只解析出JSON,所以这些表面是 `code: 'UNKNOWN_ERROR'` 状态 保存的—— `error.status` 那两个,而不是继续 `error.code`。 。 。 .

### 自定义 HTTP 客户端 (BYOC)

```typescript
import type { HttpClient } from '@glideidentity/glide-be-node-magical-auth';

const customHttpClient: HttpClient = {
  async request(options) {
    // Your custom implementation
    const response = await myHttpLibrary.request({
      method: options.method,
      url: options.url,
      headers: options.headers,
      body: options.body,
    });
    return response;
  },
};

const client = new MagicalAuthClient({
  clientId: '...',
  clientSecret: '...',
  httpClient: customHttpClient,
});
```

### 自定义 Logger (BYOL)

```typescript
import type { Logger } from '@glideidentity/glide-be-node-magical-auth';

const customLogger: Logger = {
  debug(message, meta) { console.debug(message, meta); },
  info(message, meta) { console.info(message, meta); },
  warn(message, meta) { console.warn(message, meta); },
  error(message, meta) { console.error(message, meta); },
};

const client = new MagicalAuthClient({
  clientId: '...',
  clientSecret: '...',
  logger: customLogger,
});
```

### 内置控制台

用于当地开发和快速烟雾测试,SDK船装了一个带有PII sanitization的默认静听控制台对接器和一个 `[GlideMagicalAuth]` 前缀 :

```typescript
import { MagicalAuthClient, createLogger } from '@glideidentity/glide-be-node-magical-auth';

const client = new MagicalAuthClient({
  clientId: process.env.GLIDE_CLIENT_ID!,
  clientSecret: process.env.GLIDE_CLIENT_SECRET!,
  logger: createLogger({ debug: true }),
});
```

样本输出 :

```
[GlideMagicalAuth] Preparing auth { use_case: 'VerifyPhoneNumber' }
[GlideMagicalAuth] Refreshing access token
[GlideMagicalAuth] Auth prepared { strategy: 'ts43', session_key: 'a1b2c3d4e5f6a7b8' }
[GlideMagicalAuth] Phone number retrieved { phone: '+141***1234' }
```

电话号码、JWT和明确数字 `session_key=…` 值是自动拼贴; 字段命名 `phone_number`, (中文(简体) ), `credential`, (中文(简体) ), `token`, (中文(简体) ), `password`, (中文(简体) ), `secret`,或 `fe_code` 编辑为 `[REDACTED]`。默认是沉默(`createLogger()` 因此SDK在生产中保持安静 除非你明确选择加入 对于皮诺,温斯顿或其他结构化的伐木者来说,更喜欢上面的BYOL模式.

## 认证策略

魔法Auth后端根据载体和终端用户的设备,每会话选择三个策略中的一个. 您的应用程序代码分支 `prepareResponse.authentication_strategy`。 。 。 .

### 图43

直接通过数字地证API的认证请求. 在支持的浏览器中可用,并在Android上通过Creditic Manager本地提供. 当用户的设备暴露出兼容的证书表面时选中.

### 链接

OAuth- system 重定向流在移动上. SDK 返回一个重定向 URL; 您的应用程序将用户发送到它, 而载体则完成脱带认证 .

### 桌面

基于QR的基于桌面浏览器的流. SDK返回一个单一的通用QR;Glide移动伴程序在运行时检测设备,并在扫描QR时选择适当的策略.

## 类型脚本支持

这个SDK被用TypeScript来写,提供了完整的类型定义.

### 建议: 单独类型导入

```typescript
// Runtime imports
import { MagicalAuthClient } from '@glideidentity/glide-be-node-magical-auth';

// Type-only imports (clean separation)
import type {
  PrepareRequest,
  PrepareResponse,
  VerifyPhoneNumberRequest,
  VerifyPhoneNumberResponse,
  StatusResponse,
  UseCase,
  AuthenticationStrategy,
} from '@glideidentity/glide-be-node-magical-auth/types';
```

### 备选案文:从主要条目导入

```typescript
import { MagicalAuthClient } from '@glideidentity/glide-be-node-magical-auth';
import type { PrepareRequest, PrepareResponse } from '@glideidentity/glide-be-node-magical-auth';
```

## 许可证

分发于 **Apache 许可证 2.0** 看到了吗 [自由主义](https://npmcn.com/package/%40glideidentity/glide-be-node-magical-auth/LICENSE)。 。 。 .

## 常见问题

### @glideidentity/glide-be-node-magical-auth 是什么？

Glide Magical Auth SDK for Node\.js - 没有短消息/OTP的电话号码认证

### 如何安装 @glideidentity/glide-be-node-magical-auth？

在项目目录运行 npm install @glideidentity/glide-be-node-magical-auth，或使用 pnpm add / yarn add / bun add。

### @glideidentity/glide-be-node-magical-auth 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @glideidentity/glide-be-node-magical-auth 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @glideidentity/glide-be-node-magical-auth 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @glideidentity/glide-be-node-magical-auth 可以商用吗？

@glideidentity/glide-be-node-magical-auth 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @glideidentity/glide-be-node-magical-auth 的下载量有多少？

根据 npm 官方下载统计，@glideidentity/glide-be-node-magical-auth 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,788 次，日均约 126 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @glideidentity/glide-be-node-magical-auth 还在维护吗？

最新版本 3\.2\.0 发布于 2026/10/09（1 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/05/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

