身份验证 | ArcBlock

@blocklet/server-js 库提供两种主要方法来验证 API 请求：Auth Token 和 Access Key。合适的方法取决于您的应用程序环境和安全要求。Auth Token 通常用于面向用户的应用程序（如浏览器），而 Access Key 则专为安全的服务器到服务器通信而设计。

本节将解释如何实现这两种身份验证策略。

Authentication

使用 Auth Token

对于用户主动登录的应用程序（例如在浏览器中运行的 Web 应用程序），这是最常见的身份验证方法。Auth Token 通常从用户会话中获取，并在有限时间内有效。

要使用此方法，请实例化客户端并使用 setAuthToken 方法提供令牌。

使用 setAuthToken

import BlockletServerClient from '@blocklet/server-js';

// 你的 Blocklet Server 的端点
const endpoint = 'http://localhost:4000/api';
const client = new BlockletServerClient(endpoint);

// 用户登录后从其会话中获取的令牌。
// 通常可以在你的 Blocklet Server 域名的浏览器 localStorage 中，通过键名 `__sst` 找到它。
const userAuthToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoidXNlciIsImRpZCI6Inoxbjd5TG5BRDV3VHJ5RjU2S0IzU3N0MVJlbVpVQTQ4OEhoIiwicm9sZSI6ImFkbWluIiwicHJvdmlkZXIiOiJ3YWxsZXQiLCJreWMiOjAsImVsZXZhdGVkIjpmYWxzZSwiZnVsbE5hbWUiOiJza3lwZXNreSIsImlhdCI6MTc2MTAzODQ1OSwiZXhwIjoxNzYxMDQyMDU5fQ.rLoDz0o2Jg83BP_IGF8bwhHT3Qnyhy8KfVQNzSa1ycY';

client.setAuthToken(userAuthToken);

// 所有后续的 API 调用都将自动进行身份验证
async function fetchNodeInfo() {
  try {
    const response = await client.getNodeInfo();
    console.log('Node Info:', response.info.name);
  } catch (error) {
    console.error('Failed to fetch node info:', error);
  }
}

fetchNodeInfo();

设置令牌后，客户端会在所有后续的 GraphQL 请求中自动包含 Authorization: Bearer <token> 头。

使用 Access Key

Access Key 专为服务器到服务器通信、后台服务或任何没有用户会话的非交互式环境而设计。此方法提供了一种更安全、更持久的编程访问授权方式。

要使用 Access Key，您必须使用客户端的原生版本，该版本包含了必要的加密库。

导入原生客户端

import BlockletServerClient from '@blocklet/server-js/native';

然后，使用 setAuthAccessKey 方法配置客户端。此方法接受一个包含以下字段的对象：

accessKeyId string (required) — 密钥的公共标识符。这通常是关联钱包的 DID 地址。
accessKeySecret string (required) — 用于签署请求的密钥（或私钥）。切勿在客户端代码中暴露此密钥。
type any (required) — 签名算法或钱包类型。支持的值包括来自 @ocap/wallet 的钱包类型（例如 eth、arc），以及 'sha256' 和 'totp'。该类型必须与在 Blocklet Server 中配置 Access Key 的方式相匹配。

使用 setAuthAccessKey

import BlockletServerClient from '@blocklet/server-js/native';

const endpoint = 'http://localhost:4000/api';
const client = new BlockletServerClient(endpoint);

client.setAuthAccessKey({
  accessKeyId: 'zNKjw25A312AbC5A1234567890abcdefABCDEF', // 你的 Access Key ID
  accessKeySecret: 'sk_1234567890abcdefABCDEF1234567890abcdef', // 你的 Access Key Secret
  type: 'eth' // 与密钥关联的钱包类型
});

// 所有后续的 API 调用都将使用签名头进行身份验证
async function fetchBlocklets() {
  try {
    const response = await client.getBlocklets();
    console.log(`Found ${response.blocklets.length} blocklets.`);
  } catch (error) {
    console.error('Failed to fetch blocklets:', error);
  }
}

fetchBlocklets();

使用 Access Key 时，客户端会为每个请求生成一个唯一的签名，并将其放在 x-access-signature 头中发送，同时还会发送 x-access-key-id 和其他必要的身份验证头。这确保了每个请求都能在不暴露密钥的情况下得到安全验证。

既然您已经了解了如何验证您的请求，您可以继续查阅 API 参考来探索可用的查询和变更。