@sschepis/resolang/assembly/identity/README.md

ResoLang - Core quantum resonance computation library for browser and Node.js

# Prime Resonance Network Identity and Domain System

## Overview

The Identity and Domain System provides enterprise-grade identity management, domain ownership, and object management capabilities for the Prime Resonance Network. It supports both self-sovereign and managed identity models with progressive KYC verification, hierarchical domains, flexible object ownership, and capability-based RBAC permissions.

## Architecture

### Core Components

1. **Identity System**
   - `Identity`: Base class for all identities
   - `SelfSovereignIdentity`: User-controlled identities with cryptographic capabilities
   - `ManagedIdentity`: Domain-managed identities with expiration and permissions

2. **Domain System**
   - `Domain`: Named containers with members and objects
   - `RootDomain`: Top-level domains with additional registry features
   - Supports nested subdomains with permission inheritance

3. **Object System**
   - `DomainObject`: Base class for all owned objects
   - `FungibleObject`: Divisible objects (tokens, currency)
   - `NonFungibleObject`: Unique, indivisible objects (NFTs, certificates)

4. **Permission System**
   - `Permission`: Individual capabilities that can be granted
   - `Role`: Collections of permissions
   - `PermissionEvaluator`: Evaluates access control decisions

## Key Features

### Identity Management
- **Hybrid Model**: Supports both self-sovereign and domain-managed identities
- **Progressive KYC**: Four levels (None, Basic, Enhanced, Full)
- **Prime Resonance Integration**: Identities can connect to PRN nodes
- **Metadata Support**: Extensible key-value metadata storage

### Domain Management
- **Hierarchical Structure**: Root domains with unlimited nesting
- **Ownership Transfer**: Secure domain ownership transfers
- **Member Management**: Add/remove members with permissions
- **KYC Requirements**: Domains can require specific KYC levels

### Object Management
- **Flexible Properties**:
  - Fungible/Non-fungible
  - Transferable/Non-transferable
  - Destructible/Indestructible
- **Ownership Tracking**: Full audit trail of ownership changes
- **Data Storage**: Extensible key-value data storage

### Permission System
- **Capability-Based**: Fine-grained permission control
- **Role-Based Access Control (RBAC)**: Assign roles to identities
- **Permission Inheritance**: Permissions can imply other permissions
- **Domain-Specific**: Domains can define custom permissions

## Usage Examples

### Creating Identities

```typescript
import { IdentitySystemFactory } from "./identity";

// Create a self-sovereign identity
const metadata = new Map<string, string>();
metadata.set("email", "user@example.com");
metadata.set("full_name", "John Doe");

const user = IdentitySystemFactory.createSelfSovereignIdentity(metadata);

// Create a managed identity
const managedUser = IdentitySystemFactory.createManagedIdentity(
  adminId,     // Creator ID
  domainId,    // Domain ID
  metadata
);
```

### Creating Domains

```typescript
// Create a root domain
const domain = IdentitySystemFactory.createRootDomain(
  "example.com",
  user.getId()
);

// Create a subdomain
const subdomain = domain.createSubdomain("app", user.getId());

// Add members
domain.addMember(newMemberId, user.getId());

// Set KYC requirements
domain.setRequiredKYCLevel(KYCLevel.BASIC, user.getId());
```

### Creating Objects

```typescript
// Create a fungible token
const token = IdentitySystemFactory.createFungibleObject(
  "token",           // Type
  user.getId(),      // Owner
  domain.getId(),    // Domain
  1000.0,           // Amount
  18,               // Decimals
  "TKN"             // Symbol
);

// Create an NFT
const nftMetadata = new Map<string, string>();
nftMetadata.set("name", "My NFT");
nftMetadata.set("description", "A unique digital asset");

const nft = IdentitySystemFactory.createNonFungibleObject(
  "nft",             // Type
  user.getId(),      // Owner
  domain.getId(),    // Domain
  "NFT-001",        // Token ID
  nftMetadata,      // Metadata
  "https://..."     // URI
);

// Transfer ownership
token.transfer(newOwnerId, user.getId());

// Split fungible objects
const splitToken = token.split(100.0, newOwnerId);

// Merge fungible objects
token.merge(otherToken);
```

### Managing Permissions

```typescript
// Create global permissions
const permissions = IdentitySystemFactory.createGlobalPermissions();

// Create system roles
const roles = IdentitySystemFactory.createSystemRoles(permissions);

// Create custom role
const customRole = IdentitySystemFactory.createRole(
  "Content Manager",
  "Can manage domain content",
  domain.getId()
);

// Add permissions to role
customRole.addPermission(permissions.get(GlobalPermissions.OBJECT_CREATE));
customRole.addPermission(permissions.get(GlobalPermissions.OBJECT_UPDATE));

// Check permissions
const evaluator = IdentitySystemFactory.createPermissionEvaluator();
const hasPermission = evaluator.hasPermission(
  userPermissions,    // User's direct permissions
  userRoles,         // User's roles
  requiredPermission, // Permission to check
  domain.getId()     // Domain context
);
```

## Global Permissions

The system includes predefined global permissions:

### Identity Permissions
- `identity.create`: Create new identities
- `identity.update`: Update identity information
- `identity.delete`: Delete identities
- `identity.view`: View identity information
- `identity.verify_kyc`: Verify identity KYC status

### Domain Permissions
- `domain.create`: Create new domains
- `domain.update`: Update domain information
- `domain.delete`: Delete domains
- `domain.transfer`: Transfer domain ownership
- `domain.add_member`: Add members to domain
- `domain.remove_member`: Remove members from domain
- `domain.create_subdomain`: Create subdomains

### Object Permissions
- `object.create`: Create new objects
- `object.update`: Update object data
- `object.delete`: Delete objects
- `object.transfer`: Transfer object ownership
- `object.view`: View object information

### System Permissions
- `system.admin`: Full system access
- `system.audit_view`: View system audit logs
- `system.registry_manage`: Manage domain registry

## System Roles

Predefined system roles include:

1. **Super Administrator**: Full system access
2. **Domain Owner**: Full control over owned domain
3. **Domain Administrator**: Manage domain members and objects
4. **Domain Member**: Basic domain access
5. **Identity Verifier**: Verify identity KYC status
6. **System Auditor**: View system audit logs

## Integration with Prime Resonance Network

Identities can be connected to Prime Resonance Network nodes:

```typescript
// Connect identity to PRN node
identity.connectToPrimeResonance(nodeId);

// Access PRN identity
const prnId = identity.getPrimeResonanceId();
```

## Security Considerations

1. **Authentication**: Implement proper authentication before granting access
2. **Authorization**: Always check permissions before allowing actions
3. **Audit Trail**: All state changes are logged for audit purposes
4. **KYC Verification**: Implement proper KYC provider integration
5. **Cryptographic Security**: Use proper key management for self-sovereign identities

## Future Enhancements

The following features are planned for future implementation:

1. **KYC Provider Integration**: Implement actual KYC verification providers
2. **Identity Recovery**: Multi-signature recovery mechanisms
3. **Domain Registry**: Decentralized domain name registration
4. **Permission Inheritance**: Automatic permission inheritance in domain hierarchy
5. **Session Management**: Secure session creation and management
6. **Audit System**: Comprehensive audit trail with blockchain integration
7. **Cryptographic Operations**: Actual signature verification for self-sovereign identities

## API Reference

For detailed API documentation, see the individual component files:
- [Interfaces](./interfaces.ts)
- [Types](./types.ts)
- [Identity](./identity.ts)
- [Domain](./domain.ts)
- [Domain Object](./domain-object.ts)
- [Permissions](./permissions.ts)