Skip to main content
ESCEID

Hive JavaScript SDK

Elastos Hive gives every user a personal data vault — a server-side container where apps read and write data on the user's behalf. Under the hood, vaults use MongoDB for structured data and IPFS for files. All access is authenticated through DIDs, so users own and control their data across every app that connects.

Installation​

npm install @elastosfoundation/hive-js-sdk

You'll also need the DID SDK for authentication:

npm install @elastosfoundation/did-js-sdk

Authentication Flow​

Hive nodes don't use passwords or API keys — they verify your app's identity through a DID challenge-response handshake:

  1. Your app presents its AppInstanceDID document to the Hive node
  2. The node returns a JWT challenge
  3. Your app signs the challenge with the AppInstanceDID's private key
  4. The node verifies the signature and issues an access token
info

Your AppInstanceDID must be published to the EID chain before authenticating. See the DID Integration guide for how to create and publish a DID.

Connecting to a Vault​

Set up an AppContext that handles the auth handshake, then connect to the vault:

import { AppContext, Vault } from "@elastosfoundation/hive-js-sdk";
import { DIDStore } from "@elastosfoundation/did-js-sdk";

const appContext = AppContext.build({
  getLocalDataDir: () => "./hive-data",
  getAppInstanceDocument: async () => {
    const store = await DIDStore.open("./did-store");
    return await store.loadDid(appInstanceDid);
  },
  getAuthorization: async (jwtChallenge: string) => {
    const store = await DIDStore.open("./did-store");
    const appDoc = await store.loadDid(appInstanceDid);
    return await appDoc.signJWT({ token: jwtChallenge }, "storepass");
  },
}, userDid);

const vault = new Vault(appContext, "https://your-hive-node.example.com");
tip

The userDid parameter identifies whose vault you're accessing. Your app authenticates as the appInstanceDid, but reads/writes happen in the user's vault space.

Database Service​

The database service wraps MongoDB — you get collections, filters, and all the query operators you'd expect.

const db = vault.getDatabaseService();

// Create a collection
await db.createCollection("tasks");

// Insert
const result = await db.insertOne("tasks", {
  title: "Ship v2",
  status: "in_progress",
  tags: ["release", "important"],
  createdAt: new Date().toISOString(),
});

// Find with filters and sorting
const tasks = await db.findMany("tasks", {
  filter: { status: "in_progress" },
  sort: { createdAt: -1 },
  limit: 20,
});

// Update
await db.updateOne("tasks", {
  filter: { _id: result.insertedId },
  update: { $set: { status: "done" } },
});

// Delete
await db.deleteOne("tasks", {
  filter: { _id: result.insertedId },
});

// Count
const count = await db.countDocuments("tasks", {
  filter: { status: "in_progress" },
});
warning

Hive vaults are per-user. You can't query across multiple users' data from a single vault connection — that's by design. For cross-user data sharing, use the Scripting Service.

Files Service​

Upload and download files stored on IPFS behind a familiar path-based API:

const files = vault.getFilesService();

// Upload
const content = Buffer.from("Hello from Elastos Hive!");
await files.upload("docs/readme.txt", content);

// Download
const data = await files.download("docs/readme.txt");
console.log(data.toString());

// List directory contents
const entries = await files.list("docs/");
for (const entry of entries) {
  console.log(`${entry.name} — ${entry.size} bytes`);
}

// File metadata
const stat = await files.stat("docs/readme.txt");
console.log("Last modified:", stat.lastModified);

// Delete
await files.delete("docs/readme.txt");

// Move / rename
await files.move("docs/draft.txt", "docs/final.txt");

Scripting Service​

Scripts let you expose controlled access to your vault data so other DIDs can read (or write) specific things — without giving them full vault access.

const scripting = vault.getScriptingService();

// Register a public profile script — anyone can call it
await scripting.registerScript(
  "get_public_profile",
  new Executable("find", {
    collection: "profile",
    filter: { visibility: "public" },
  }),
  null,  // no access condition
  false
);

// Register a restricted script — only approved DIDs
await scripting.registerScript(
  "get_shared_notes",
  new Executable("find", {
    collection: "notes",
    filter: { sharedWith: "$caller_did" },
  }),
  new Condition("check_allowlist", {
    type: "queryHasResults",
    collection: "allowed_callers",
    filter: { did: "$caller_did" },
  }),
  false
);

A caller from a different DID invokes the script like this:

const result = await callerScripting.callScript(
  "get_public_profile",
  {},
  ownerDid,
  appDid
);
info

The $caller_did placeholder is replaced at runtime with the DID of whoever calls the script. This is how you build sharing features without a centralized backend.

Backup & Migration​

Users aren't locked into a single Hive node. The SDK supports vault backup and migration so users can move their data between providers:

OperationWhat It Does
BackupSnapshots the entire vault (database + files) to a backup node
MigrationTransfers a vault from one Hive node to another
RestoreRebuilds a vault on a new node from a backup

The backup flow is initiated from the vault owner's side — no admin action needed on the Hive node. This ensures true data portability: if a Hive node goes offline or you want better performance, you move your vault without losing anything.

Available in Other Languages​

LanguageRepository
JavaElastos.Hive.Java.SDK
SwiftElastos.Hive.Swift.SDK

Hive HTTP API​

For server-side integrations or languages without a dedicated SDK, Hive nodes expose a REST/HTTP API directly. The full specification is maintained by Trinity Tech:

Hive Node HTTP API Reference

The HTTP API covers all the same operations (vault subscription, database CRUD, file upload/download, scripting, backup) but without SDK abstractions — you handle authentication tokens and request formatting yourself.

Resources​