Prividium SDK

A TypeScript SDK for integrating with Prividium's authorization system, providing seamless authentication and secure RPC communication for blockchain applications.

Features

• 🔐 Popup-based OAuth Authentication - Secure authentication flow using popup windows
• 🔑 JWT Token Management - Automatic token storage, validation, and expiration handling
• 🌐 Viem Integration - Drop-in transport for viem clients with automatic auth headers

Installation

npm install @repo/prividium-sdk
# or
yarn add @repo/prividium-sdk

Quick Start

1. Create a Prividium Chain

import { createPrividiumChain } from '@repo/prividium-sdk';
import { defineChain, createPublicClient, http } from 'viem';

// Define your chain
const prividiumChain = defineChain({
  id: 7777,
  name: 'Prividium Chain',
  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
  rpcUrls: { default: { http: [] } },
  blockExplorers: { default: { name: 'Explorer', url: 'https://explorer.prividium.io' } }
});

// Create SDK instance
const prividium = createPrividiumChain({
  clientId: 'your-client-id',
  chain: prividiumChain,
  rpcUrl: 'https://rpc.prividium.io',
  authBaseUrl: 'https://auth.prividium.io',
  redirectUrl: window.location.origin + '/auth/callback',
  onAuthExpiry: () => {
    console.log('Authentication expired - please reconnect');
  }
});

2. Create Viem Client

// The SDK provides a pre-configured transport with automatic auth headers
const client = createPublicClient({
  chain: prividium.chain,
  transport: prividium.transport // ✨ Auth headers are automatically included!
});

3. Authenticate and Use

// Check if already authenticated
if (!prividium.isAuthorized()) {
  // Trigger authentication popup
  await prividium.authorize();
}

// Now you can make authenticated RPC calls
const balance = await client.getBalance({
  address: '0x...'
});

API Reference

createPrividiumChain(config)

Creates a new Prividium SDK instance.

Parameters:

interface PrividiumConfig {
  clientId: string; // OAuth client ID
  chain: Chain; // Viem chain configuration (without rpcUrls)
  rpcUrl: string; // Private RPC endpoint URL
  authBaseUrl: string; // Authorization service base URL
  redirectUrl: string; // OAuth redirect URL
  storage?: Storage; // Custom storage implementation (optional)
  onAuthExpiry?: () => void; // Called when authentication expires (optional)
}

Returns: PrividiumChain

PrividiumChain Methods

authorize(options?)

Opens authentication popup and handles OAuth flow.

await prividium.authorize({
  popupSize: { w: 600, h: 700 } // Optional custom popup dimensions
});

Returns: Promise<string> - JWT token

unauthorize()

Clears authentication state and tokens.

prividium.unauthorize();

isAuthorized()

Checks if user is currently authenticated with valid token.

const authenticated = prividium.isAuthorized();

Returns: boolean

getAuthHeaders()

Gets current authentication headers for manual use.

const headers = prividium.getAuthHeaders();
// Returns: { Authorization: 'Bearer <token>' } | null

Returns: Record<string, string> | null

Advanced Usage

Custom Storage

Implement custom storage for different environments:

class CustomStorage implements Storage {
  getItem(key: string): string | null {
    // Your implementation
  }

  setItem(key: string, value: string): void {
    // Your implementation
  }

  removeItem(key: string): void {
    // Your implementation
  }
}

const prividium = createPrividiumChain({
  // ... other config
  storage: new CustomStorage()
});

Multiple Chains

Support multiple Prividium chains:

const testnetPrividium = createPrividiumChain({
  clientId: 'your-testnet-client-id',
  chain: testnetChain,
  rpcUrl: 'https://testnet-rpc.prividium.io',
  authBaseUrl: 'https://testnet-auth.prividium.io',
  redirectUrl: window.location.origin + '/auth/callback'
});

const mainnetPrividium = createPrividiumChain({
  clientId: 'your-mainnet-client-id',
  chain: mainnetChain,
  rpcUrl: 'https://mainnet-rpc.prividium.io',
  authBaseUrl: 'https://mainnet-auth.prividium.io',
  redirectUrl: window.location.origin + '/auth/callback'
});

Error Handling

Handle authentication errors gracefully:

try {
  await prividium.authorize();
} catch (error) {
  if (error.message.includes('cancelled')) {
    console.log('User cancelled authentication');
  } else {
    console.error('Authentication failed:', error);
  }
}

Manual HTTP Requests

Use authentication headers with custom HTTP requests:

const headers = prividium.getAuthHeaders();
if (headers) {
  const response = await fetch('/api/protected', {
    headers: {
      ...headers,
      'Content-Type': 'application/json'
    }
  });
}

Storage Keys

The SDK uses the following localStorage keys:

• prividium_jwt_<chainId> - JWT token storage
• prividium_auth_state_<chainId> - OAuth state parameter

Security Considerations

1. Token Storage: Tokens are stored in localStorage by default. Consider custom storage for sensitive applications.

2. CSRF Protection: OAuth state parameter provides CSRF protection during authentication flow.

3. Token Expiration: SDK automatically validates token expiration and clears expired tokens.

4. Origin Validation: Popup messages are validated against the configured auth origin.

Development

Building

npm run build

Testing

npm test

Linting

npm run lint
npm run lint:fix

License

MIT