客户端初始化与身份验证

SpaceClient 是与 DID Space 网络交互的主要接口。在上传文件或管理数据之前，您必须首先使用正确的配置和身份验证凭据创建客户端实例。本指南将引导您了解初始化和验证 SpaceClient 的各种策略。

所有配置都通过其构造函数中的单个 SpaceClientOptions 对象传递给客户端。

Initializing the Client

import { SpaceClient } from '@blocklet/did-space-js';

const spaceClient = new SpaceClient({
  // ... 此处为您的选项
});

此配置中最关键的部分是 auth 对象，它决定了您的请求将如何进行身份验证。

身份验证策略

SDK 提供三种主要的身份验证方法，旨在适应不同的用例。您应选择最适合您应用程序环境和安全要求的一种。

1. 使用端点和钱包（推荐）

这是最常用且最安全的方法，尤其是在 Blocklet 环境中进行开发时，用户的钱包随时可用。它使用用户的钱包对请求进行签名，提供了一种强大、去中心化的身份验证机制。

此方法对应于 SpaceClientOptionsEndpointAuth 接口。

配置

auth object (required) — 使用钱包和端点进行身份验证的详细信息。
- wallet WalletObject (required) — 钱包对象，通常从 Blocklet SDK 中获取，用于签署请求。
- endpoint string (required) — 用户 DID Space 和应用程序的特定 API 端点。

示例

Initializing with Wallet and Endpoint

import { SpaceClient } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// 在 Blocklet 环境中，可以轻松访问钱包。
const wallet = getWallet();

// 该端点特定于用户的 space 和应用的 DID。
const endpoint =
  'https://cedcaa27-znkomkclejcfbjaxw9knzzebmzmqrxjnn9bb.did.abtnet.io/api/space/z3T6EHN7sLhH5cty1PshDeSipeG7JNxEVaRFS/app/zNKabhhwdvVmXjtRTtSHk2YQz4pdDPStV289/';

const spaceClient = new SpaceClient({
  auth: {
    wallet: wallet,
    endpoint: endpoint,
  },
});

// 客户端现在已准备好发送已签名的请求。

2. 使用授权令牌

此方法适用于您拥有短期不记名令牌的场景。这在传统 Web 应用程序或可能不存在钱包的服务器到服务器通信中很常见。

此方法对应于 SpaceClientOptionsAuthorizationAuth 接口。

配置

auth object (required) — 使用授权令牌进行身份验证的详细信息。
- authorization string (required) — 随请求发送的授权令牌（例如 JWT）。

示例

Initializing with an Authorization Token

import { SpaceClient } from '@blocklet/did-space-js';

const authToken = 'your-secure-authorization-token';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    authorization: authToken,
  },
});

// 客户端现在将使用该令牌进行身份验证。

3. 使用访问密钥

此方法专为需要长期访问 DID Space 的后端服务或自动化脚本而设计。它使用密钥进行身份验证，类似于许多云服务授予 API 访问权限的方式。

此方法对应于 SpaceClientOptionsAccessKeyAuth 接口。

配置

auth object (required) — 使用访问密钥进行身份验证的详细信息。
- secretKey string (required) — 用于验证请求的密钥。

示例

Initializing with a Secret Key

import { SpaceClient } from '@blocklet/did-space-js';

const secretKey = 'your-long-term-secret-key';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    secretKey: secretKey,
  },
});

// 客户端已配置为用于服务器端或自动化访问。

其他重要选项

除了身份验证之外，SpaceClientOptions 对象还接受一些其他有用的参数。

url string (default: https://www.didspaces.com) — DID Spaces 服务的基础 URL。SDK 会自动解析正确的应用程序挂载点。通常不需要更改此项。
delegation string — 一个 JWT 令牌，证明请求者有权代表另一个 DID 访问 space。
abortController AbortController — 一个 AbortController 实例，用于取消请求。

既然您已了解如何初始化 SpaceClient 并进行身份验证，下一步理应是了解 SDK 如何在底层保护您的请求。要深入了解安全模型，请继续阅读请求签名文档。