NOVA SDK for JavaScript/TypeScript

Version: 1.0.3 License: MIT Network: NEAR Protocol (Mainnet & Testnet) Package: nova-sdk-js

A JavaScript/TypeScript SDK for NOVA's secure, decentralized file-sharing primitive on NEAR. NOVA hybridizes on-chain access control with off-chain TEE-secured keys via Shade Agents, using nonce-based ed25519-signed tokens for ephemeral, verifiable access. This ensures privacy-first data sharing for AI datasets, healthcare/financial records, and sensitive documents.

Features

• 🔐 Zero-Knowledge Architecture - Keys managed in TEE; never exposed to SDK

• 🌐 IPFS Storage - Decentralized file storage via Pinata

• ⛓️ NEAR Blockchain - Immutable access control & transaction logs

• 🛡️ API Key Auth - Secure authentication via API keys (get yours at nova-sdk.com)

• 🔑 Automated Signing - MCP server signs transactions using keys from Shade TEE

• 👥 Group Management - Fine-grained membership with automatic key rotation on revocation

• 🚀 Composite Operations - Simplified workflows for upload/retrieve

• 📦 TypeScript Support - Full type definitions included

Installation

npm install nova-sdk-js

⚠️ Mainnet Notice

NOVA SDK operates on NEAR mainnet by default. All operations consume real NEAR tokens.

Typical costs (mainnet):

• Register group: 0.05 NEAR ($0.15 USD)

• Upload file: ~0.01 NEAR (incl. IPFS storage)

• Retrieve file: ~0.001 NEAR

const sdk = new NovaSdk('yourname.nova-sdk-6.testnet', {
  apiKey: process.env.NOVA_API_KEY,
  rpcUrl: 'https://rpc.testnet.near.org',
  contractId: 'nova-sdk-6.testnet',
});

Note: On testnet, IPFS operations are mocked (in-memory storage). Blockchain operations use real testnet with faucet tokens.

Quick Start

Prerequisites

1. Create a NOVA account at nova-sdk.com

2. Generate an API key from the "Manage Account" menu

3. Fund your account with NEAR tokens for transaction fees

Simple upload/retrieve example

import { NovaSdk } from 'nova-sdk-js';

// Initialize with your account ID and API key
const sdk = new NovaSdk('alice.nova-sdk.near', {
  apiKey: process.env.NOVA_API_KEY
});

// Register group (you become owner)
await sdk.registerGroup('confidential-docs');

// Upload a file
const result = await sdk.upload('my-group', Buffer.from('Hello NOVA!'), 'hello.txt');
console.log('Uploaded:', result.cid);

// Retrieve the file
const { data } = await sdk.retrieve('my-group', result.cid);
console.log('Retrieved:', data.toString());

That's it! The SDK automatically:

• Authenticates using your API key

• Manages session tokens (auto-refresh before 24h expiry)

• Handles all encryption/decryption client-side

Configuration Options

// Standard usage (mainnet)
const sdk = new NovaSdk('alice.nova-sdk.near', {
  apiKey: process.env.NOVA_API_KEY  // Required: get yours at nova-sdk.com
});

// Testnet configuration
const sdk = new NovaSdk('alice.nova-sdk-6.testnet', {
  apiKey: process.env.NOVA_API_KEY,
  rpcUrl: 'https://rpc.testnet.near.org',
  contractId: 'nova-sdk-6.testnet',
});

// Custom MCP server (advanced)
const sdk = new NovaSdk('alice.nova-sdk.near', {
  apiKey: process.env.NOVA_API_KEY,
  mcpUrl: 'https://your-mcp-server.com',
  authUrl: 'https://your-auth-server.com',
});

📖 Core Operations

File Upload & Retrieve

import fs from 'fs';

// Upload (encrypts client-side, stores on IPFS, records on NEAR)
const fileData = fs.readFileSync('./document.pdf');
const result = await sdk.upload('my-group', fileData, 'document.pdf');

console.log('CID:', result.cid);           // IPFS content ID
console.log('TX:', result.trans_id);       // NEAR transaction ID
console.log('Hash:', result.file_hash);    // SHA-256 of plaintext

// Retrieve (fetches from IPFS, decrypts client-side)
const { data } = await sdk.retrieve('my-group', result.cid);
fs.writeFileSync('./downloaded.pdf', data);

Group Management

// Create a group (you become owner)
await sdk.registerGroup('team-files');

// Add members
await sdk.addGroupMember('team-files', 'bob.nova-sdk.near');
await sdk.addGroupMember('team-files', 'carol.nova-sdk.near');

// Check authorization
const isAuthorized = await sdk.isAuthorized('team-files', 'bob.nova-sdk.near');

// Revoke access (triggers automatic key rotation)
await sdk.revokeGroupMember('team-files', 'bob.nova-sdk.near');

Read-Only Queries

These don't require authentication:

// Account balance
const balance = await sdk.getBalance();

// Group info
const owner = await sdk.getGroupOwner('team-files');
const checksum = await sdk.getGroupChecksum('team-files');

// Transaction history
const transactions = await sdk.getTransactionsForGroup('team-files');

// Fee estimation
const fee = await sdk.estimateFee('register_group');

How It Works

Upload Flow

1. SDK calls prepare_upload → MCP returns encryption key from TEE
2. SDK encrypts file locally (AES-256-GCM)
3. SDK calls finalize_upload with encrypted data
4. MCP uploads to IPFS and records on NEAR
5. Returns: { cid, trans_id, file_hash }

Retrieve Flow

1. SDK calls prepare_retrieve → MCP returns key + encrypted data
2. SDK decrypts locally (AES-256-GCM)
3. Returns: { data, ipfs_hash, group_id }

Key point: Plaintext data and encryption keys never travel together. The MCP server never sees your unencrypted files.

Authentication

The SDK uses API keys for secure authentication. Get your key at nova-sdk.com:

1. Create or log into your NOVA account

2. Click "Manage Account"

3. Click "Generate API Key"

4. Copy the key (shown only once!)

# Store in .env (never commit to git!)
NOVA_ACCOUNT_ID=alice.nova-sdk.near
NOVA_API_KEY=nova_sk_xxxxxxxxxxxxxxxxxxxxx

// Use environment variables
const sdk = new NovaSdk(process.env.NOVA_ACCOUNT_ID, {
  apiKey: process.env.NOVA_API_KEY
});

// Force refresh session token
await sdk.refreshToken();

// Get network info
const info = sdk.getNetworkInfo();

Note: One API key per account. Generating a new key invalidates the old one.

Error Handling

import { NovaSdk, NovaError } from 'nova-sdk-js';

try {
  await sdk.upload('my-group', data, 'file.txt');
} catch (e) {
  if (e instanceof NovaError) {
    if (e.message.includes('not found')) {
      console.error('Account not found - create one at nova-sdk.com');
    } else if (e.message.includes('not authorized')) {
      console.error('Not a member of this group');
    } else if (e.message.includes('Insufficient')) {
      console.error('Need more NEAR - deposit at nova-sdk.com');
    } else {
      console.error('NOVA error:', e.message);
    }
  }
}

Costs (Mainnet)

Some operations require NEAR token deposits (paid from user's NOVA account):

• registerGroup() - ~0.05 NEAR

• addGroupMember() - ~0.001 NEAR

• revokeGroupMember() - ~0.001 NEAR

• upload() - ~0.003 NEAR (claim token + record Tx)

• retrieve() - 0.001 NEAR (claim only)

Ensure your NOVA account has sufficient balance before calling these methods.

API Reference

Constructor

new NovaSdk(accountId: string, config?: NovaSdkConfig)

Methods

Method	Description
upload(groupId, data, filename)	Upload encrypted file
retrieve(groupId, cid)	Retrieve and decrypt file
registerGroup(groupId)	Create new group
addGroupMember(groupId, memberId)	Add member to group
revokeGroupMember(groupId, memberId)	Remove member (rotates key)
authStatus(groupId?)	Check authentication status
isAuthorized(groupId, userId?)	Check group authorization
getGroupOwner(groupId)	Get group owner
getGroupChecksum(groupId)	Get TEE attestation checksum
getTransactionsForGroup(groupId)	List group transactions
getBalance(accountId?)	Get NEAR balance
estimateFee(action)	Estimate operation cost
refreshToken()	Force token refresh
computeHash(data)	SHA-256 hash (sync)
computeHashAsync(data)	SHA-256 hash (async)

License

MIT LICENSE - Copyright (c) 2026 CivicTech OÜ

Resources

• NOVA Documentation

• NEAR Protocol

• IPFS

• Pinata

• Phala TEE

• NEAR JavaScript API

Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions