SourceHub ACP JS Client

A client/bridge library for interacting with the SourceHub ACP. This library provides both low-level client access and high-level helper functions for managing policies, objects, actor relationships, and performing access verification.

Features

• Policy Management - Create and retrieve access control policies
• Object Registration - Register objects within policy contexts
• Actor Relationships - Manage relationships between actors and objects
• Access Verification - Verify access permissions for specific operations
• Key Management - Automatic wallet creation and session management via @sourcenetwork/hublet

Installation

npm install @sourcenetwork/acp-js
# or
yarn add @sourcenetwork/acp-js

Quick Start

import { 
  createPolicy, 
  registerObject, 
  setRelationship,
  verifyAccess,
  getObjectOwner 
} from '@sourcenetwork/acp-js';

// Configure global settings (optional)
if (typeof window !== 'undefined') {
  window.globalACPConfig = {
    apiUrl: 'http://localhost:1317',
    rpcUrl: 'http://localhost:26657', 
    grpcUrl: 'http://localhost:9090',
    chainId: 'sourcehub-dev',
    denom: 'uopen',
    useZeroFees: false
  };
}

// Create a policy and get the policy ID
const policyId = await createPolicy(1, policyDefinition);

// Register an object
await registerObject(policyId, 'documents', 'doc123');

// Set actor relationship
await setRelationship(policyId, 'documents', 'doc123', 'owner', 'alice');

// Verify access
const canRead = await verifyAccess(policyId, 'documents', 'doc123', 'read', 'alice');

// Get object owner
const owner = await getObjectOwner(policyId, 'documents', 'doc123');

API Reference

SourceHubACP Class

• SourceHubACP.create(apiUrl, rpcUrl, grpcUrl, chainId, denom?, useZeroFees?) - Create with new signer
• SourceHubACP.createFromKeys(privateKey, pubkey, compressedPubkey, ...) - Create with existing keys

Helper Functions

• createPolicy(marshalType, policyContent): Promise<string> - Create policy and return ID
• registerObject(policyId, resourceName, objectId): Promise<TxResponse> - Register object
• setRelationship(policyId, resourceName, objectId, relation, targetActor): Promise<TxResponse> - Set relationship
• deleteRelationship(policyId, resourceName, objectId, relation, targetActor): Promise<TxResponse> - Delete relationship
• verifyAccess(policyId, resourceName, objectId, permission, actorId): Promise<boolean> - Verify access
• getObjectOwner(policyId, resourceName, objectId): Promise<string | null> - Get owner
• getPolicy(policyId): Promise<Policy | null> - Get policy
• initAccount(address): Promise<FaucetResponse> - Initialize account via faucet
• grantAllowance(address): Promise<FaucetResponse> - Grant fee allowance via faucet
• deleteKeypair(): Promise<void> - Clear session wallet

Configuration

window.globalACPConfig = {
  apiUrl: 'https://api.sourcehub.dev',
  rpcUrl: 'https://rpc.sourcehub.dev', 
  grpcUrl: 'https://grpc.sourcehub.dev',
  chainId: 'sourcehub-1',
  denom: 'uopen',
  useZeroFees: false
};

Development

Prerequisites

• Node.js 18+
• Yarn (recommended) or npm

Building

# Install dependencies
yarn install
# Build both ESM and CJS versions
yarn build
# Build individual formats
yarn build:esm
yarn build:cjs

Testing

yarn test

Linting

yarn lint

Proto Generation

# Generate protobuf files
./generate-proto.sh

License

This project is licensed under the Apache License 2.0.