@glideidentity/glide-be-node-magical-auth (英语)
Glide Magical Auth SDK for Node.js ——没有短信/OTP的电话号码认证,使用以载体为基础的数字证书.
特征
- 无依赖 - 只使用节点(18+)
- 类型脚本第一 - 具有出色的IntelliSense支持的全型安全
- 叙利亚 - 将您的 HTTP 客户端引入自定义执行
- 再见 - 带自己的Logger去自定义记录
- 自动调试管理 - OAuth2 令牌缓存并自动刷新
- 线索安全 - 安全地同时使用,同时减少承诺
安装
npm install @glideidentity/glide-be-node-magical-auth
所需资源
- 节点.js 18.0.0或以上
快速启动
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"互动的主要客户类.
构造器
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>
通过检查承运人资格和生成特定协议请求来准备认证.
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),设定在父准备上;电话继承. 忽略了链接。 要求它从不要求生物鉴别:无法进行生物鉴别的装置仍然具有认证性.
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)如此未经挑选的会话很快就会到期.
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>
使用数字证书验证电话号码.
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?),通过你派来准备的空格:
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字符串,exp1至60 s 后为iat,以及sign_offs非空项数组role, (中文(简体) ),signer财务报告和审定财务报表status(单位:千美元)unavailable带有reason,或present与format财务报告和审定财务报表token),确切的其中之一acarrier签名条目carrier:<id>可选strategy(单位:千美元)TS_43, (中文(简体) ),LINK, (中文(简体) ),DESKTOP__TS_43, (中文(简体) ),DESKTOP__LINK, (中文(简体) ),DESKTOP, (中文(简体) ),phone_number_details, (中文(简体) ),carrier(单位:千美元){id, name, mvno}, (中文(简体) ),sim_swap财务报告和审定财务报表device_swap; 错误的 JSON 类型, acarrier没有非空字符串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>
获取与设备相关的电话号码.
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,因为风险来自乐团本身的反思,而不是从窗口.
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>
当用户点击认证按钮时报告(用于分析).
await client.reportInvocation(sessionId);
checkStatus(sessionKey: string): Promise<StatusResponse>
核查状态的投票(认证终点).
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>
核查状态的投票(公用终点,不需要认证).
// Safe to use from browser without exposing credentials
const status = await client.checkStatusPublic(sessionKey);
invalidateToken(): void
在下次请求时强制更新一个符号 .
client.invalidateToken();
处理错误
所有 API 出错均作为打出例外 :
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)
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)
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] 前缀 :
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来写,提供了完整的类型定义.
建议: 单独类型导入
// 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';
备选案文:从主要条目导入
import { MagicalAuthClient } from '@glideidentity/glide-be-node-magical-auth';
import type { PrepareRequest, PrepareResponse } from '@glideidentity/glide-be-node-magical-auth';
许可证
分发于 Apache 许可证 2.0 看到了吗 自由主义。 。 。 .