@uptickjs/webauth-sdk

WebAuth JavaScript SDK for React Native — 提供社交登录（Google / Apple）、邮箱验证码登录、OTP 双因素认证、MPC 钱包管理与交易签名等能力。

功能特性

• 社交登录：Google、Apple 免密登录
• 邮箱登录：基于验证码的邮箱认证
• 双因素认证（2FA）：TOTP 式验证码（支持 Google Authenticator 等）
• MPC 钱包：创建与管理 MPC 加密钱包，支持查询余额与交易记录
• 交易签名：消息签名、EIP-712 Typed Data 签名、交易签名与验签
• 令牌管理：自动携带 access_token，支持刷新与本地存储
• 事件系统：订阅登录 / 登出 / 令牌刷新 / 错误事件
• TypeScript：内置完整类型定义
• 深链回调：通过 Deep Link 完成浏览器 OAuth 登录回跳

安装

npm install @uptickjs/webauth-sdk
# 或
yarn add @uptickjs/webauth-sdk

React Native 环境需要额外安装持久化存储依赖：

npm install @react-native-async-storage/async-storage

若使用 Apple 原生 Sign In（loginWithApple 令牌方式），还需要：

npm install @invertase/react-native-apple-authentication

快速开始

import { createWebAuth, createTokenStorage, WebAuthConfig } from '@uptickjs/webauth-sdk';

// 1. 配置 SDK
// Mainnet: https://uptickauth.uptick.network/api
// Testnet: https://uptickauth.testweb.uptick.network/api

const config: WebAuthConfig = {
  apiBaseUrl: 'https://api.yourserver.com',
  apiKey: 'YOUR_API_KEY',
  redirectUri: 'yourapp://callback',
};

// 2. 创建实例（使用 React Native 持久化存储）
const webAuth = createWebAuth(config, createTokenStorage('react-native'));
// 网页端无需持久化存储时，可直接省略 tokenStorage（默认使用内存存储）：
// const webAuth = createWebAuth(config);

// 3. 处理深链回调
import { Linking } from 'react-native';
Linking.addEventListener('url', async (event) => {
  await webAuth.handleRedirect(event.url);
});

// 4. 应用启动时初始化（自动刷新令牌）
await webAuth.initialize();

// 5. 判断登录态
const authed = await webAuth.isAuthenticated();

配置项

interface WebAuthConfig {
  // 认证服务端地址（必填）
  apiBaseUrl: string;
  // OAuth 客户端标识 / API Key（必填）
  apiKey: string;
  // Deep Link 回跳 URI（必填）
  redirectUri: string;
  // 自定义 URL scheme（可选，默认 'webauth'）
  appScheme?: string;
}

必填项缺失（apiBaseUrl / apiKey / redirectUri）会在构造时抛出错误。

认证

Google 登录（浏览器 OAuth + Deep Link）

loginWithGoogleRedirect() 会在系统浏览器打开授权页，注册一次性深链监听，授权完成后自动回跳并解析令牌。

// 发起 Google 登录
const response = await webAuth.getAuth().loginWithGoogleRedirect();
// 用户授权后自动解析令牌并 resolve；超时返回 null

冷启动兜底：若系统在浏览器打开期间终止了 App，Promise 会因冷启动丢失。请在启动时通过 Linking.getInitialURL() 获取初始 URL 并调用 webAuth.handleRedirect(url) 作为兜底。

Apple 登录

支持两种方式：

// 方式一：浏览器 OAuth + Deep Link
const response = await webAuth.getAuth().loginWithAppleRedirect();

// 方式二：原生 Sign In with Apple（需 @invertase/react-native-apple-authentication）
import { appleAuth } from '@invertase/react-native-apple-authentication';

const appleAuthRequestResponse = await appleAuth.performRequest({
  requestedOperation: appleAuth.Operation.LOGIN,
  requestedScopes: [appleAuth.Scope.EMAIL, appleAuth.Scope.FULL_NAME],
});

const response = await webAuth.getAuth().loginWithApple(
  appleAuthRequestResponse.identityToken,
  appleAuthRequestResponse.authorizationCode || '',
);

邮箱登录（验证码）

// 第一步：发送验证码
const { message, expires_in } = await webAuth
  .getAuth()
  .sendEmailCode('[email protected]');

// 第二步：验证并登录（令牌会自动写入本地存储）
const response = await webAuth
  .getAuth()
  .loginWithEmail('[email protected]', '123456');

用户信息与令牌

// 获取当前用户信息
const user = await webAuth.getAuth().getUserInfo();

// 刷新令牌
const auth = await webAuth.getAuth().refreshToken(refreshToken);

OTP（双因素认证）

// 生成 OTP 密钥与二维码
const { secret, qrCodeUrl, manualEntryKey } = await webAuth.getOTP().setup();

// 验证验证码以启用 2FA
const { enabled, created_at } = await webAuth.getOTP().verify('123456');

// 查询是否已启用
const status = await webAuth.getOTP().getStatus();

// 校验验证码（不改变启用状态，常用于登录流程）
const isValid = await webAuth.getOTP().validate('123456');

// 禁用 2FA（需要当前验证码）
await webAuth.getOTP().disable('123456');

MPC 钱包管理

// 创建钱包
const wallet = await webAuth.getWallet().create('my-wallet');
console.log(wallet.address);

// 查询钱包
const info = await webAuth.getWallet().getWallet();

// 是否已有钱包
const hasWallet = await webAuth.getWallet().hasWallet();

// 导出公开信息（仅地址，不含私钥）
const publicInfo = await webAuth.getWallet().exportPublicInfo();

// 查询余额
const balances = await webAuth.getWallet().getBalance();

// 查询交易记录（分页）
const { transactions, total } = await webAuth.getWallet().getTransactions(1, 20);

交易签名

// 签名普通消息
const result = await webAuth.getSign().signMessage(
  'Hello, World!',
  wallet.address,
  1, // 可选 chainId
);
console.log(result.signature);

// EIP-712 Typed Data 签名
const typedData = {
 
};
const result = await webAuth.getSign().signTypedData(typedData, wallet.address);

// 签名交易
const tx = await webAuth.getSign().signTransaction(transaction, wallet.address);

// 验签
const isValid = await webAuth.getSign().verify(
  'Hello, World!',
  signature,
  wallet.address,
);

// 待处理签名请求管理
const pending = await webAuth.getSign().getPendingRequests();
await webAuth.getSign().cancelRequest(requestId);

事件监听

webAuth.addEventListener('my-listener', (event) => {
  switch (event.type) {
    case 'login':
      console.log('登录成功', event.data);
      break;
    case 'logout':
      console.log('已登出');
      break;
    case 'token_refresh':
      console.log('令牌已刷新');
      break;
    case 'error':
      console.error('认证错误', event.error);
      break;
  }
});

// 移除监听
webAuth.removeEventListener('my-listener');

深链配置

iOS（Info.plist）

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
    <key>CFBundleURLName</key>
    <string>com.yourcompany.yourapp</string>
  </dict>
</array>

Android（AndroidManifest.xml）

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="yourapp" />
</intent-filter>

API 参考

顶层导出

| 导出 | 说明 | | --- | --- | | createWebAuth(config, tokenStorage?) | 创建 WebAuthClient 实例 | | WebAuthClient | 主客户端类（默认导出） | | createConfig / WebAuthConfigManager | 配置管理 | | createTokenStorage / RNTokenStorage / MemoryTokenStorage | 令牌存储 | | createHttpClient / HttpClient | HTTP 客户端 | | createAuthModule / AuthModule | 认证模块 | | createOTPModule / OTPModule | OTP 模块 | | createWalletModule / WalletModule | 钱包模块 | | createSignModule / SignModule | 签名模块 |

WebAuthClient

const webAuth = createWebAuth(config, createTokenStorage('react-native'));

await webAuth.initialize();              // 初始化（自动刷新令牌）
await webAuth.isAuthenticated();          // 是否已登录
await webAuth.handleRedirect(url);        // 处理深链回调
await webAuth.logout();                   // 登出

webAuth.getAuth();                        // AuthModule
webAuth.getOTP();                         // OTPModule
webAuth.getWallet();                      // WalletModule
webAuth.getSign();                        // SignModule

webAuth.addEventListener(id, listener);   // 订阅事件
webAuth.removeEventListener(id);          // 取消订阅

AuthModule

await auth.loginWithGoogleRedirect();             // Google 浏览器登录
await auth.loginWithAppleRedirect();              // Apple 浏览器登录
await auth.loginWithApple(identityToken, code);   // Apple 原生登录
await auth.sendEmailCode(email);                  // 发送邮箱验证码
await auth.loginWithEmail(email, code);           // 邮箱验证码登录
await auth.getUserInfo();                         // 当前用户信息
await auth.refreshToken(refreshToken);            // 刷新令牌
await auth.logout();                              // 登出

OTPModule

await otp.setup();      // 生成密钥与二维码
await otp.verify(code); // 验证并启用
await otp.disable(code);// 禁用
await otp.getStatus();  // 查询状态
await otp.validate(code); // 校验验证码

WalletModule

await wallet.create(name?);            // 创建钱包
await wallet.getWallet();              // 查询钱包
await wallet.hasWallet();              // 是否已有钱包
await wallet.exportPublicInfo();       // 导出公开信息
await wallet.getBalance();             // 查询余额
await wallet.getTransactions(page, limit); // 交易记录

SignModule

await sign.sign(request);                    // 通用签名请求
await sign.signMessage(message, addr, chainId?);
await sign.signTypedData(data, addr, chainId?);
await sign.signTransaction(transaction, addr);
await sign.verify(message, signature, addr);
await sign.getPendingRequests();             // 待处理签名请求
await sign.cancelRequest(requestId);         // 取消签名请求

令牌存储

createWebAuth 的第二个参数 tokenStorage 为可选项：

• React Native 应用：建议传入 createTokenStorage('react-native') 做持久化存储；
• 网页版项目：无需传入，SDK 默认使用内存存储（createTokenStorage('memory')），即 const webAuth = createWebAuth(config)。

import { createTokenStorage } from '@uptickjs/webauth-sdk';

createTokenStorage('react-native'); // 基于 AsyncStorage 持久化（默认）
createTokenStorage('memory');       // 内存存储（Web / 测试）

也可以传入自定义存储实现 TokenStorage 接口。

更多文档

• React Native 集成指南

License

MIT