Skip to content

README.md

Latest commit

 

History

History
441 lines (337 loc) · 9.37 KB

README.md

File metadata and controls

441 lines (337 loc) · 9.37 KB
Raw

AuthLayer Python SDK

Complete Python SDK for interacting with the AuthLayer role-based access control (RBAC) contract on Stellar/Soroban.

Installation

pip install authlayer-sdk
# or
poetry add authlayer-sdk

Quick Start

from authlayer import AuthLayer, Permission, AuthLayerConfig

# Initialize the client
config = AuthLayerConfig(
    contract_id="CBDMK2XFZC5RWF5ZFRVX...",
    rpc_url="https://soroban-testnet.stellar.org",
    network_passphrase="Test SDF Network ; September 2015",
)

sg = AuthLayer(config)

# Create a role
result = sg.create_role(
    admin="GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    role_name="manager",
    permissions=[Permission.READ, Permission.WRITE, Permission.MANAGE_MEMBERS],
    description="Manager role with read/write and member management"
)

print(f"Role created: {result.tx_hash}")

# Grant role to a member
sg.grant_role(
    admin="GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    member="GYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
    role_name="manager"
)

# Check if member has permission
has_write = sg.has_permission(
    member="GYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
    permission=Permission.WRITE
)

print(f"Has write permission: {has_write}")

Configuration

from stellar_guard import StellarGuardConfig

config = StellarGuardConfig(
    contract_id="...",       # Contract ID on Soroban
    rpc_url="...",          # RPC endpoint URL
    network_passphrase="...", # Network passphrase
    timeout=30000            # Optional timeout (ms)
)

Core Features

Role Management

# Create role
sg.create_role(admin, "editor", [Permission.READ, Permission.WRITE])

# Get role details
role = sg.get_role("editor")

# List all roles
roles = sg.list_roles(limit=50, offset=0)

# Update role permissions
sg.update_role_permissions(admin, "editor", [Permission.READ])

# Delete role
sg.delete_role(admin, "editor")

# Check if role exists
exists = sg.role_exists("editor")

Permission Management

# Grant role to member
sg.grant_role(admin, member, "editor")

# Revoke role
sg.revoke_role(admin, member, "editor")

# Check role
has_role = sg.has_role(member, "editor")

# Get member's roles
member_roles = sg.get_member_roles(member)

# Check permission
has_write = sg.has_permission(member, Permission.WRITE)

# Direct permission grants (bypass roles)
sg.grant_permission(admin, member, Permission.WRITE)
sg.revoke_permission(admin, member, Permission.WRITE)

# Check any of multiple permissions
has_any = sg.has_any_permission(member, [Permission.READ, Permission.WRITE])

# Check all permissions
has_all = sg.has_all_permissions(member, [Permission.READ, Permission.WRITE])

Access Control

from stellar_guard import RoleBasedPolicy

# Set access policy for resource
sg.set_access_policy(
    admin,
    "secret_data",
    RoleBasedPolicy(roles=["manager", "admin"])
)

# Get access policy
policy = sg.get_access_policy("secret_data")

# Check resource access
can_access = sg.can_access_resource(member, "secret_data")

Delegation

# Grant delegation rights
sg.grant_delegation_rights(admin, delegator, "editor")

# Check delegation capability
can_delegate = sg.can_delegate_role(delegator, "editor")

# Member delegates role
sg.delegate_role(delegator, delegate, "editor")

Time-Based Roles

import time

# Grant role with expiration (timestamp in seconds)
sg.grant_role_with_expiry(
    admin,
    member,
    "editor",
    int(time.time()) + 86400  # 24 hours
)

# Get expiration time
expires_at = sg.get_role_expiry(member, "editor")

# Check if expired
is_expired = sg.is_role_expired(member, "editor")

# Cleanup expired roles
sg.cleanup_expired_roles(member)

Batch Operations

# Grant multiple roles
sg.grant_roles_batch(admin, member, ["editor", "reviewer"])

# Revoke multiple roles
sg.revoke_roles_batch(admin, member, ["editor", "reviewer"])

# Grant role to multiple members
sg.grant_role_to_members(admin, [member1, member2, member3], "viewer")

Queries & Statistics

# Get role member count
count = sg.get_role_member_count("editor")

# Get role members (paginated)
members = sg.get_role_members("editor", limit=50, offset=0)

# Get contract statistics
stats = sg.get_contract_stats()
# ContractStats(
#   total_roles=5,
#   total_members=100,
#   total_permissions=45,
#   last_updated=...
# )

# Verify member access (audit)
access = sg.verify_member_access(member)
# AccessCheckResult(
#   can_access=True,
#   roles=["editor"],
#   permissions=[Permission.READ, Permission.WRITE]
# )

Permission Types

Standard permissions:

from stellar_guard import Permission

Permission.READ              # Read data
Permission.WRITE             # Modify data
Permission.DELETE            # Remove data
Permission.EXECUTE           # Run functions
Permission.MANAGE_MEMBERS    # Control users
Permission.MANAGE_ROLES      # Create/edit roles
Permission.MANAGE_PERMISSIONS # Grant/revoke access
Permission.APPROVE           # Authorization authority

Custom permissions:

from stellar_guard import CustomPermission

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

Access Policies

Various access policy types:

from stellar_guard import (
    PublicPolicy,
    AuthenticatedPolicy,
    RoleBasedPolicy,
    PermissionBasedPolicy,
    WhitelistPolicy,
    CustomPolicy,
)

# Public - anyone
policy = PublicPolicy()

# Authenticated - any member
policy = AuthenticatedPolicy()

# Role-based - specific roles
policy = RoleBasedPolicy(roles=["admin", "manager"])

# Permission-based - specific permissions
policy = PermissionBasedPolicy(permissions=[Permission.READ, Permission.WRITE])

# Whitelist - explicit addresses
policy = WhitelistPolicy(addresses=["GXXX...", "GYYY..."])

# Custom - application logic
policy = CustomPolicy(value="custom_policy")

Error Handling

from stellar_guard import (
    StellarGuardError,
    AuthorizationError,
    RoleNotFoundError,
    PermissionDeniedError,
    InvalidInputError,
    NetworkError,
    TimeoutError,
    ConfigurationError,
)

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.code}): {error.message}")

Advanced Usage

Custom Permissions

# Create role with custom permissions
sg.create_role(
    admin,
    "custom_role",
    [
        Permission.READ,
        CustomPermission(value="publish_content"),
        CustomPermission(value="moderate_comments"),
    ]
)

# Check custom permission
can_publish = sg.has_permission(
    member,
    CustomPermission(value="publish_content")
)

Pagination

All list operations support pagination:

response = sg.list_roles(limit=25, offset=50)
print({
    "data": response.data,
    "limit": response.limit,
    "offset": response.offset,
    "total": response.total,
    "has_more": response.has_more,
})

Transaction Options

from stellar_guard import OperationOptions

sg.grant_role(
    admin,
    member,
    "editor",
    options=OperationOptions(
        fee=100,
        memo="Granting editor role",
        timeout=60000
    )
)

API Reference

Role Management (11 methods)

  • create_role() - Create new role
  • get_role() - Get role details
  • list_roles() - List all roles
  • update_role_permissions() - Update permissions
  • delete_role() - Delete role
  • role_exists() - Check existence

Permission Management (13 methods)

  • grant_role() - Assign role
  • revoke_role() - Unassign role
  • has_role() - Check role
  • get_member_roles() - List roles
  • grant_permission() - Direct permission
  • revoke_permission() - Revoke permission
  • has_permission() - Check permission
  • has_any_permission() - Check any (OR)
  • has_all_permissions() - Check all (AND)
  • grant_roles_batch() - Batch grant
  • revoke_roles_batch() - Batch revoke
  • grant_role_to_members() - Bulk grant
  • verify_member_access() - Audit check

Access Control (3 methods)

  • set_access_policy() - Set policy
  • get_access_policy() - Get policy
  • can_access_resource() - Check access

Delegation (3 methods)

  • grant_delegation_rights() - Allow delegation
  • can_delegate_role() - Check capability
  • delegate_role() - Member delegates

Time-Based (4 methods)

  • grant_role_with_expiry() - Expiring role
  • get_role_expiry() - Get expiry
  • is_role_expired() - Check expiry
  • cleanup_expired_roles() - Cleanup

Queries (4 methods)

  • get_role_member_count() - Count members
  • get_role_members() - List members
  • get_contract_stats() - Statistics
  • verify_member_access() - Audit

Testing

pytest
pytest --cov=stellar_guard  # With coverage

Building

python -m build

Contributing

Contributions welcome! Please ensure:

  • Type hints throughout
  • Comprehensive docstrings
  • Clear error handling
  • Tests for new features

License

MIT

Support

Changelog

v1.0.0

  • Initial release
  • Full RBAC API coverage
  • Role management
  • Permission system
  • Access control
  • Delegation
  • Time-based roles
  • Batch operations
  • Comprehensive error handling