Core Concepts

This section delves into the fundamental principles and architectural patterns that power the @blocklet/did-space-js SDK. Understanding these concepts will help you use the library more effectively and troubleshoot issues with greater confidence. The SDK is built on three main pillars: a robust Command Pattern, flexible Authentication methods, and a secure Request Signing mechanism.

The Command Pattern#

Instead of having dozens of methods on the main SpaceClient object, the SDK adopts the Command Pattern. This design choice offers a clean and scalable architecture.

How it works:

1. Encapsulation: Every distinct operation (like uploading a file or listing a directory) is encapsulated into its own Command class. For example, to upload a file, you use PutObjectCommand.
2. Standardization: Each command has a standardized structure, accepting an input object for its parameters and returning a structured output object.
3. Execution: The SpaceClient acts as a universal executor. You create an instance of a command and then pass it to the client.send() method, which handles the underlying logic of authentication, request signing, and HTTP communication.

This separation of concerns—the command defining what to do and the client handling how to do it—makes the SDK predictable and easy to extend.

Client Initialization & Authentication#

Before you can send any commands, you must initialize a SpaceClient instance with the proper configuration and authentication credentials. The SDK is designed to be flexible, supporting multiple authentication strategies to fit different use cases, from server-side applications to client-side components.

The primary way to configure the client is through the SpaceClientOptions object passed to its constructor. This object specifies the target DID Space and the credentials needed to access it.

Secure by Design: Request Signing#

Security is a cornerstone of DID Spaces. Every API request sent by the SDK is cryptographically signed to ensure its authenticity and integrity. This prevents unauthorized access and tampering with data in transit.

Here’s a high-level overview of the process:

1. When you call client.send(command), the SDK constructs the full HTTP request.
2. It then creates a unique digital signature for that specific request by hashing its contents (URL, method, body) and signing the hash with the private key from your wallet.
3. This signature, along with your public key, is sent as part of the request headers.
4. The DID Space server receives the request, re-calculates the signature on its end, and verifies it against the one you sent using your public key.

If the signatures match, the server knows the request is authentic and came from you. If not, it rejects the request.

Next Steps#

Now that you have a high-level understanding of the core concepts, you can explore them in more detail or move on to practical guides.