Skip to content
BranchesTags

Repository files navigation

AuthLayer Frontend SDKs

Complete SDKs for integrating AuthLayer role-based access control (RBAC) into frontend applications.

Overview

This directory contains comprehensive SDKs for building applications that interact with the AuthLayer smart contract:

  • TypeScript SDK - Full-featured TypeScript/JavaScript client library
  • Python SDK - Python client library for backend services
  • Integration Guide - Step-by-step integration instructions
  • Examples - Complete working examples for React and Flask

Quick Links

What's Included

TypeScript SDK (sdk/typescript/)

  • Complete API Coverage: All 54 contract methods
  • Type Safety: Full TypeScript support with interfaces
  • Error Handling: Comprehensive error types
  • React Integration: Custom hooks and components
  • Batch Operations: Efficient multi-operation support
npm install @authlayer/sdk-ts

Key Files:

  • src/types.ts - Type definitions
  • src/client.ts - Main client class
  • src/errors.ts - Error types
  • README.md - Complete documentation

Python SDK (sdk/python/)

  • Complete API Coverage: All 54 contract methods
  • Type Hints: Full type annotations
  • Error Handling: Clear exception types
  • Flask/Django: Framework integration examples
  • Async Support: Optional async methods
pip install authlayer-sdk

Key Files:

  • stellar_guard/types.py - Type definitions
  • stellar_guard/client.py - Main client class
  • stellar_guard/errors.py - Error types
  • README.md - Complete documentation

Installation & Setup

TypeScript

cd frontend/sdk/typescript
npm install
npm run build
npm publish  # Or use locally

Python

cd frontend/sdk/python
pip install -e .
# Or for publishing
python -m build
twine upload dist/*

Getting Started

TypeScript Quick Start

import { StellarGuard, Permission } from "@stellar-guard/sdk-ts";

const sg = new StellarGuard({
  contractId: "YOUR_CONTRACT_ID",
  rpcUrl: "https://soroban-testnet.stellar.org",
  networkPassphrase: "Test SDF Network ; September 2015",
});

// Check permissions
const canWrite = await sg.hasPermission(userAddress, Permission.Write);

// Grant role
await sg.grantRole(adminAddress, userAddress, "editor");

// Get user's roles
const roles = await sg.getMemberRoles(userAddress);

Python Quick Start

from stellar_guard import StellarGuard, Permission, StellarGuardConfig

config = StellarGuardConfig(
    contract_id="YOUR_CONTRACT_ID",
    rpc_url="https://soroban-testnet.stellar.org",
    network_passphrase="Test SDF Network ; September 2015",
)

sg = StellarGuard(config)

# Check permissions
can_write = sg.has_permission(user_address, Permission.WRITE)

# Grant role
sg.grant_role(admin_address, user_address, "editor")

# Get user's roles
roles = sg.get_member_roles(user_address)

API Overview

Role Management (11 methods)

// TypeScript
await sg.createRole(admin, "manager", [Permission.Read, Permission.Write]);
await sg.deleteRole(admin, "manager");
const role = await sg.getRole("manager");
const roles = await sg.listRoles();
# Python
sg.create_role(admin, "manager", [Permission.READ, Permission.WRITE])
sg.delete_role(admin, "manager")
role = sg.get_role("manager")
roles = sg.list_roles()

Permission Management (13 methods)

// TypeScript
await sg.grantRole(admin, member, "editor");
await sg.revokeRole(admin, member, "editor");
const hasRole = await sg.hasRole(member, "editor");
const hasPermission = await sg.hasPermission(member, Permission.Write);
# Python
sg.grant_role(admin, member, "editor")
sg.revoke_role(admin, member, "editor")
has_role = sg.has_role(member, "editor")
has_permission = sg.has_permission(member, Permission.WRITE)

Access Control (3 methods)

// TypeScript
await sg.setAccessPolicy(admin, "resource", { type: "RoleBased", roles: ["admin"] });
const policy = await sg.getAccessPolicy("resource");
const canAccess = await sg.canAccessResource(member, "resource");
# Python
sg.set_access_policy(admin, "resource", RoleBasedPolicy(roles=["admin"]))
policy = sg.get_access_policy("resource")
can_access = sg.can_access_resource(member, "resource")

Delegation (4 methods)

// TypeScript
await sg.grantDelegationRights(admin, delegator, "editor");
const canDelegate = await sg.canDelegateRole(delegator, "editor");
await sg.delegateRole(delegator, delegate, "editor");
# Python
sg.grant_delegation_rights(admin, delegator, "editor")
can_delegate = sg.can_delegate_role(delegator, "editor")
sg.delegate_role(delegator, delegate, "editor")

Time-Based Roles (4 methods)

// TypeScript
await sg.grantRoleWithExpiry(admin, member, "editor", expiresAt);
const expiry = await sg.getRoleExpiry(member, "editor");
const isExpired = await sg.isRoleExpired(member, "editor");
await sg.cleanupExpiredRoles(member);
# Python
sg.grant_role_with_expiry(admin, member, "editor", expires_at)
expiry = sg.get_role_expiry(member, "editor")
is_expired = sg.is_role_expired(member, "editor")
sg.cleanup_expired_roles(member)

Batch Operations (3 methods)

// TypeScript
await sg.grantRolesBatch(admin, member, ["editor", "viewer"]);
await sg.revokeRolesBatch(admin, member, ["editor", "viewer"]);
await sg.grantRoleToMembers(admin, [member1, member2], "viewer");
# Python
sg.grant_roles_batch(admin, member, ["editor", "viewer"])
sg.revoke_roles_batch(admin, member, ["editor", "viewer"])
sg.grant_role_to_members(admin, [member1, member2], "viewer")

Queries & Statistics (4 methods)

// TypeScript
const count = await sg.getRoleMemberCount("editor");
const members = await sg.getRoleMembers("editor", 50, 0);
const stats = await sg.getContractStats();
const access = await sg.verifyMemberAccess(member);
# Python
count = sg.get_role_member_count("editor")
members = sg.get_role_members("editor", limit=50, offset=0)
stats = sg.get_contract_stats()
access = sg.verify_member_access(member)

Integration Examples

React Component

See examples/typescript-react-example.tsx for a complete React example including:

  • Custom hooks for roles and permissions
  • Permission guards
  • Admin panel
  • Dashboard
# To use in your React project:
npm install @stellar-guard/sdk-ts
# Then copy relevant patterns from the example

Flask Application

See examples/python-flask-example.py for a complete Flask example including:

  • Permission decorators
  • Role-based access control
  • API endpoints
  • HTML dashboard
# To use in your Flask project:
pip install stellar-guard-sdk flask
# Then adapt the example to your needs

Configuration

Environment Variables

# .env
REACT_APP_CONTRACT_ID=CBDMK2XFZC5RWF5ZFRVX...
REACT_APP_RPC_URL=https://soroban-testnet.stellar.org
REACT_APP_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

Programmatic Configuration

TypeScript:

const config: StellarGuardConfig = {
  contractId: "...",
  rpcUrl: "...",
  networkPassphrase: "...",
  timeout: 30000,
};

Python:

config = StellarGuardConfig(
    contract_id="...",
    rpc_url="...",
    network_passphrase="...",
    timeout=30000,
)

Error Handling

TypeScript

import {
  StellarGuardError,
  AuthorizationError,
  RoleNotFoundError,
  PermissionDeniedError,
} from "@stellar-guard/sdk-ts";

try {
  await sg.grantRole(admin, member, "nonexistent");
} catch (error) {
  if (error instanceof RoleNotFoundError) {
    console.error("Role not found");
  } else if (error instanceof AuthorizationError) {
    console.error("Not authorized");
  } else if (error instanceof StellarGuardError) {
    console.error(`Error: ${error.message}`);
  }
}

Python

from stellar_guard import (
    StellarGuardError,
    AuthorizationError,
    RoleNotFoundError,
    PermissionDeniedError,
)

try:
    sg.grant_role(admin, member, "nonexistent")
except RoleNotFoundError:
    print("Role not found")
except AuthorizationError:
    print("Not authorized")
except StellarGuardError as error:
    print(f"Error: {error.message}")

Permission Types

Standard Permissions

Both SDKs support these standard permissions:

  • READ / Read - Read data
  • WRITE / Write - Modify data
  • DELETE / Delete - Remove data
  • EXECUTE / Execute - Run functions
  • MANAGE_MEMBERS / ManageMembers - Control users
  • MANAGE_ROLES / ManageRoles - Manage roles
  • MANAGE_PERMISSIONS / ManagePermissions - Manage permissions
  • APPROVE / Approve - Approve actions

Custom Permissions

Both SDKs support custom, application-defined permissions:

TypeScript:

const customPerm: CustomPermission = {
  type: "Custom",
  value: "publish_content",
};
await sg.grantPermission(admin, member, customPerm);

Python:

custom_perm = CustomPermission(value="publish_content")
sg.grant_permission(admin, member, custom_perm)

Access Policies

Both SDKs support multiple access policy types:

  • Public - Open to everyone
  • Authenticated - Any member
  • RoleBased - Specific roles
  • PermissionBased - Specific permissions
  • Whitelist - Explicit addresses
  • Custom - Application-defined

Testing

TypeScript

cd frontend/sdk/typescript
npm test
npm run lint
npm run format

Python

cd frontend/sdk/python
pytest
pytest --cov=stellar_guard
black stellar_guard tests
isort stellar_guard tests

Building & Publishing

TypeScript

cd frontend/sdk/typescript
npm run build
npm publish

Python

cd frontend/sdk/python
python -m build
twine upload dist/*

Documentation

Support & Contribution

License

MIT - See LICENSE file

Changelog

v1.0.0

  • Initial release
  • TypeScript SDK with 54 contract methods
  • Python SDK with 54 contract methods
  • Comprehensive documentation
  • React and Flask examples
  • Full error handling
  • Type safety

About

AuthLayer is a reusable Soroban smart contract that provides enterprise-grade role-based access control (RBAC) and permissions management for Stellar applications.

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages