user-authentication-system

Role-based access control for Greek accounting firms. Login, role hierarchy, per-client permissions, session management, audit logging.

# User Authentication System

This skill provides a complete authentication and authorization system for Greek accounting firm operations through OpenClaw. It manages user identities, role-based permissions, per-client access controls, and session security for multi-user accounting environments.


## Setup

```bash
export OPENCLAW_DATA_DIR="/data"
which jq openssl || sudo apt install jq openssl
mkdir -p $OPENCLAW_DATA_DIR/auth
chmod 700 $OPENCLAW_DATA_DIR/auth
```

No external auth services. User credentials are stored as salted SHA-256 hashes locally. 2FA uses SHA-256 TOTP generated by openssl.


## Core Philosophy

- **Role-Based Access**: Hierarchical permissions matching real accounting firm structures
- **Per-Client Authorization**: Granular control over which users access which client data
- **Session Security**: Secure session management with timeout and device tracking
- **Audit Integration**: Every authentication and authorization event logged
- **OpenClaw Artifact Ready**: File-based auth suitable for OpenClaw deployment

## OpenClaw Commands

### User Management
```bash
openclaw auth user-create --username "maria.g" --role assistant --full-name "Maria Georgiou" --email "maria@firm.gr"
openclaw auth user-update --username "maria.g" --role accountant --effective-date 2026-03-01
openclaw auth user-deactivate --username "maria.g" --reason "resignation" --revoke-sessions
openclaw auth user-list --active --role assistant --format table
openclaw auth password-reset --username "maria.g" --send-reset-link
openclaw auth password-policy --min-length 12 --require-special --max-age-days 90
```

### Role & Permission Management
```bash
openclaw auth role-list --include-permissions
openclaw auth role-create --name "tax_specialist" --base-role accountant --add-permissions "tax_filing,tax_optimization"
openclaw auth assign-clients --username "maria.g" --clients EL123456789,EL987654321
openclaw auth assign-clients --username "maria.g" --all-clients
openclaw auth check-access --username "maria.g" --client EL123456789 --action "view_financials"
openclaw auth access-matrix --all-users --all-clients --format xlsx
```

### Security & Audit
```bash
openclaw auth security-log --last-24h --include-failures
openclaw auth failed-logins --threshold 3 --lockout-duration 30m
openclaw auth audit-report --user "maria.g" --period last-30-days
openclaw auth audit-report --client EL123456789 --who-accessed --period last-week
openclaw auth 2fa-enable --username "maria.g" --method totp
openclaw auth sessions-list --active --format table
openclaw auth session-revoke --username "maria.g" --all-devices
```

## File System Architecture

```yaml
Auth_File_Structure:
  user_data:
    - /data/auth/users/{username}/profile.json
    - /data/auth/users/{username}/credentials.json
    - /data/auth/users/{username}/permissions.json
    - /data/auth/users/{username}/sessions/
    - /data/auth/users/{username}/2fa/

  role_definitions:
    - /data/auth/roles/senior_accountant.json
    - /data/auth/roles/accountant.json
    - /data/auth/roles/assistant.json
    - /data/auth/roles/viewer.json
    - /data/auth/roles/custom/

  access_control:
    - /data/auth/access/client_assignments.json
    - /data/auth/access/policies.json
    - /data/auth/access/ip_whitelist.json

  security_logs:
    - /data/auth/logs/logins/
    - /data/auth/logs/access/
    - /data/auth/logs/admin/
    - /data/auth/logs/security/
```

## Role Hierarchy & Permissions

### Role Definitions
```yaml
Roles:
  senior_accountant:
    description: "Senior accountant - full system access"
    level: 4
    inherits: "accountant"
    permissions:
      - all_client_access
      - user_management
      - role_assignment
      - system_configuration
      - data_export_all
      - compliance_override
      - audit_log_access
      - gdpr_operations
      - billing_management
      - skill_configuration
    client_access: "all"

  accountant:
    description: "Accountant - broad access to assigned clients"
    level: 3
    inherits: "assistant"
    permissions:
      - client_data_full_access
      - tax_filing_submit
      - tax_optimization
      - compliance_management
      - financial_reporting
      - efka_submissions
      - banking_reconciliation
      - deadline_management
      - client_communication
    client_access: "assigned_only"
    restrictions:
      - cannot_manage_users
      - cannot_change_system_config

  assistant:
    description: "Accountant assistant - operational access"
    level: 2
    inherits: "viewer"
    permissions:
      - document_upload
      - document_processing
      - data_entry
      - email_processing
      - dashboard_access
      - basic_reporting
      - client_data_edit_basic
      - alert_acknowledgement
      - ocr_processing
    client_access: "assigned_only"
    restrictions:
      - cannot_submit_tax_filings
      - cannot_export_sensitive_data
      - cannot_modify_financial_records

  viewer:
    description: "Read-only access to assigned client data"
    level: 1
    permissions:
      - dashboard_view
      - client_data_view
      - report_view
      - deadline_view
      - document_view
    client_access: "assigned_only"
    restrictions:
      - read_only
      - no_data_modification
      - no_data_export
```

### Permission Matrix
```yaml
Permission_Matrix:
  view_dashboard: "viewer"
  configure_dashboard: "accountant"
  view_client_profile: "viewer"
  edit_client_profile: "assistant"
  create_client: "accountant"
  delete_client: "senior_accountant"
  export_client_data: "accountant"
  gdpr_operations: "senior_accountant"
  view_documents: "viewer"
  upload_documents: "assistant"
  process_documents: "assistant"
  delete_documents: "accountant"
  view_financials: "viewer"
  enter_financial_data: "assistant"
  modify_financial_records: "accountant"
  submit_tax_filings: "accountant"
  view_compliance_status: "viewer"
  manage_compliance: "accountant"
  override_compliance: "senior_accountant"
  view_employee_data: "viewer"
  manage_employees: "accountant"
  submit_efka: "accountant"
  view_transactions: "viewer"
  reconcile_transactions: "assistant"
  configure_banking: "accountant"
  manage_users: "senior_accountant"
  manage_roles: "senior_accountant"
  view_audit_logs: "senior_accountant"
  system_configuration: "senior_accountant"
```

## Authentication Engine

### Core Authentication
```python
class AuthenticationEngine:
    """Handles user authentication, sessions, and credential management."""

    def __init__(self):
        self.session_timeout = 30 * 60  # 30 minutes
        self.idle_timeout = 15 * 60     # 15 minutes
        self.max_failed_attempts = 5
        self.lockout_duration = 30 * 60  # 30 minutes

    def authenticate(self, username, password, device_info=None):
        """Authenticate user and create session."""
        if self.is_account_locked(username):
            self.log_auth_event(username, 'login_blocked', 'account_locked')
            return {'success': False, 'error': 'Account is locked. Contact administrator.'}

        user = self.load_user(username)
        if not user:
            self.log_auth_event(username, 'login_failed', 'user_not_found')
            return {'success': False, 'error': 'Invalid credentials'}

        if not self.verify_password(password, user['password_hash']):
            self.record_failed_attempt(username)
            self.log_auth_event(username, 'login_failed', 'wrong_password')
            return {'success': False, 'error': 'Invalid credentials'}

        if user['status'] != 'active':
            self.log_auth_event(username, 'login_failed', f'account_{user["status"]}')
            return {'success': False, 'error': 'Account is not active'}

        if user.get('2fa_enabled', False):
            return {'success': False, 'requires_2fa': True,
                    'session_pending': self.create_pending_session(username)}

        session = self.create_session(username, device_info)
        self.clear_failed_