Skill: satoshistackalotto/user-authentication-system (version 0.1.1)

--- name: user-authentication-system description: Role-based access control for Greek accounting firms. Login, role hierarchy, per-client permissions, session management, audit logging. version: 1.0.0 author: openclaw-greek-accounting homepage: https://github.com/satoshistackalotto/openclaw-greek-accounting tags: ["greek", "accounting", "authentication", "rbac", "security"] metadata: {"openclaw": {"requires": {"bins": ["jq", "openssl", "openclaw"], "env": ["OPENCLAW_DATA_DIR"]}, "notes": "Manages local user accounts and role-based access. Credentials are stored as salted SHA-256 hashes in OPENCLAW_DATA_DIR/auth/. 2FA uses SHA-256 TOTP. No external auth services — fully local.", "path_prefix": "/data/ in examples refers to $OPENCLAW_DATA_DIR (default: /data/)"}} --- # 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 "[REDACTED_SECRET]" 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_attempts(username) self.log_auth_event(username, 'login_success', device_info=device_info) return {'success': True, 'session': session, 'user': self.get_user_summary(username)} def create_session(self, username, device_info=None): """Create a new authenticated session. Security: The raw session token is returned to the user exactly once. Only the salted SHA-256 hash is stored on disk. Validation compares the hash of the incoming token against the stored hash. """ raw_token = generate_secure_token(64) token_hash = hash_session_token(raw_token) # SHA-256 salted hash session = { 'session_id': token_hash, 'username': username, 'created_at': current_timestamp(), 'expires_at': current_timestamp() + self.session_timeout, 'last_activity': current_timestamp(), 'device_info': device_info, 'ip_address': get_request_ip(), 'role': self.get_user_role(username), 'client_access': self.get_user_client_access(username) } session_path = f"/data/auth/users/{username}/sessions/{token_hash}.json" write_json(session_path, session) # Return raw token to user — this is the only time it exists in cleartext session['bearer_token'] = raw_token return session def validate_session(self, session_id): """Validate an existing session.""" session = self.find_session(session_id) if not session: return {'valid': False, 'reason': 'session_not_found'} if current_timestamp() > session['expires_at']: self.destroy_session(session_id) return {'valid': False, 'reason': 'session_expired'} if current_timestamp() - session['last_activity'] > self.idle_timeout: self.destroy_session(session_id) return {'valid': False, 'reason': 'idle_timeout'} session['last_activity'] = current_timestamp() self.update_session(session) return {'valid': True, 'session': session} def hash_password(self, password): """Hash password using bcrypt with salt.""" return bcrypt_hash(password, rounds=12) def validate_password_strength(self, password): """Check password meets policy requirements.""" errors = [] if len(password) < 12: errors.append("Password must be at least 12 characters") if not any(c.isupper() for c in password): errors.append("Must contain uppercase letter") if not any(c.islower() for c in password): errors.append("Must contain lowercase letter") if not any(c.isdigit() for c in password): errors.append("Must contain digit") if not any(c in '!@#$%^&*()_+-=' for c in password): errors.append("Must contain special character") return {'valid': len(errors) == 0, 'errors': errors} ``` ### Authorization Engine ```python class AuthorizationEngine: """Handles permission checks and access control decisions.""" def __init__(self): self.roles = self.load_roles() self.access_matrix = self.load_access_matrix() def check_permission(self, session, action, client_vat=None): """Check if user has permission to perform an action.""" username = session['username'] user_role = session['role'] required_role = self.access_matrix.get(action) if not required_role: self.log_authorization(username, action, client_vat, 'denied', 'unknown_action') return {'allowed': False, 'reason': f'Unknown action: {action}'} user_level = self.roles[user_role]['level'] required_level = self.roles[required_role]['level'] if user_level < required_level: self.log_authorization(username, action, client_vat, 'denied', 'insufficient_role') return {'allowed': False, 'reason': f'Requires {required_role} role (you have {user_role})'} # Check client-specific access if client_vat: client_access = session.get('client_access', []) if 'all' not in client_access and client_vat not in client_access: self.log_authorization(username, action, client_vat, 'denied', 'no_client_access') return {'allowed': False, 'reason': f'Not authorized for client {AFM}'} self.log_authorization(username, action, client_vat, 'allowed') return {'allowed': True} def resolve_permissions(self, role_name): """Resolve all permissions including inherited ones.""" role = self.roles.get(role_name, {}) permissions = set(role.get('permissions', [])) parent = role.get('inherits') if parent: permissions.update(self.resolve_permissions(parent)) return permissions def get_accessible_clients(self, username): """Get list of clients this user can access.""" assignments = read_json("/data/auth/access/client_assignments.json") user_entry = assignments.get(username, {}) if user_entry.get('all_clients', False): return {'type': 'all', 'clients': 'all'} return {'type': 'specific', 'clients': user_entry.get('clients', [])} ``` ### User Management ```python class UserManager: """Manages user lifecycle operations.""" def __init__(self): self.auth_engine = AuthenticationEngine() self.authz_engine = AuthorizationEngine() def create_user(self, admin_session, user_data): """Create a new user account.""" # Verify admin has permission perm_check = self.authz_engine.check_permission(admin_session, 'manage_users') if not perm_check['allowed']: return {'success': False, 'error': perm_check['reason']} username = user_data['username'] # Check for duplicate if self.user_exists(username): return {'success': False, 'error': f'Username {username} already exists'} # Validate role if user_data['role'] not in self.authz_engine.roles: return {'success': False, 'error': f'Invalid role: {user_data["role"]}'} # Create user profile profile = { 'username': username, 'full_name': user_data['full_name'], 'email': user_data.get('email'), 'role': user_data['role'], 'status': 'active', 'created_at': current_timestamp(), 'created_by': admin_session['username'], 'password_change_required': True, '2fa_enabled': False } # Generate temporary password temp_password = generate_secure_password() credentials = { 'password_hash': self.auth_engine.hash_password(temp_password), 'password_set_at': current_timestamp(), 'password_change_required': True } # Create user directory and files user_dir = f"/data/auth/users/{username}" create_directory(user_dir) create_directory(f"{user_dir}/sessions") create_directory(f"{user_dir}/2fa") write_json(f"{user_dir}/profile.json", profile) write_json(f"{user_dir}/credentials.json", credentials) write_json(f"{user_dir}/permissions.json", {'role': user_data['role'], 'custom': []}) # Audit log self.log_admin_action(admin_session['username'], 'user_created', { 'new_user': username, 'role': user_data['role'] }) return { 'success': True, 'username': username, 'temporary_password': temp_password, 'message': f'User {username} created with role {user_data["role"]}. ' f'Password change required on first login.' } def assign_clients(self, admin_session, username, client_vats): """Assign client access to a user.""" perm_check = self.authz_engine.check_permission(admin_session, 'manage_users') if not perm_check['allowed']: return {'success': False, 'error': perm_check['reason']} assignments_path = "/data/auth/access/client_assignments.json" assignments = read_json(assignments_path) if file_exists(assignments_path) else {} if client_vats == 'all': assignments[username] = {'all_clients': True, 'clients': []} else: current = assignments.get(username, {'all_clients': False, 'clients': []}) current['clients'] = list(set(current.get('clients', []) + client_vats)) assignments[username] = current write_json(assignments_path, assignments) self.log_admin_action(admin_session['username'], 'clients_assigned', { 'user': username, 'clients': client_vats }) return {'success': True, 'username': username, 'client_access': assignments[username]} ``` ## Security Features ### File System Permissions (Production Hardening) The `/data/auth/` directory contains sensitive credential and session data. In production, OS-level file permissions must be hardened: ```bash # Restrict the entire auth directory chmod 700 /data/auth/ chown -R openclaw:openclaw /data/auth/ # Credential files must be read-only to the service user chmod 600 /data/auth/users/*/credentials.json # Session files chmod 600 /data/auth/users/*/sessions/*.json # Role definitions (read by all skills for auth checks, writable only by admin) chmod 644 /data/auth/roles/*.json # Audit logs (append-only in production if OS supports it) chmod 600 /data/auth/logs/**/*.json ``` **Note**: The OpenClaw agent and all skills share the same file system context. Without OS-level permission restrictions, any skill could read credential hashes. These permissions ensure that only the authentication skill's process can access sensitive auth data. ### Account Lockout ```yaml Lockout_Policy: max_failed_attempts: 5 lockout_duration: "30 minutes" lockout_escalation: - "5 failures: 30 minute lockout" - "10 failures: 2 hour lockout" - "15 failures: account disabled, admin notification" notification: "email admin on 3+ consecutive failures" ``` ### Two-Factor Authentication ```yaml 2FA_Configuration: methods: ["totp"] mandatory_for: ["senior_accountant"] optional_for: ["accountant", "assistant"] recovery_codes: 10 totp_settings: algorithm: "SHA256" digits: 6 period: 30 ``` ### Password Policy ```yaml Password_Policy: min_length: 12 require_uppercase: true require_lowercase: true require_digit: true require_special: true max_age_days: 90 history_count: 5 common_password_check: true ``` ### IP & Device Security ```yaml Security_Controls: ip_whitelist: enabled: true allowed_ranges: ["office_ip_range"] action_on_violation: "block_and_alert" device_tracking: track_devices: true alert_new_device: true max_concurrent_sessions: 3 session_controls: absolute_timeout: "8 hours" idle_timeout: "15 minutes" single_session_per_device: true ``` ## Integration with Other Skills ```yaml Skill_Integration: dashboard_greek_accounting: provides: ["user_session", "role_permissions", "accessible_clients"] enforces: "dashboard view permissions per user role" client_data_management: provides: ["access_decisions", "user_identity"] enforces: "per-client data access based on user assignments" integration: "authorization check before every data operation" greek_compliance_aade: enforces: "only accountant+ can submit filings" efka_api_integration: enforces: "only accountant+ can submit EFKA data" all_skills: provides: "user context for audit trail entries" enforces: "role-based action restrictions across all operations" ``` ## Audit & Compliance Reporting ### Audit Log Structure ```yaml Audit_Events: authentication: - login_success - login_failed - login_blocked - logout - session_expired - session_revoked - 2fa_success - 2fa_failed - password_changed - password_reset authorization: - access_granted - access_denied - client_access_checked - permission_checked administration: - user_created - user_updated - user_deactivated - role_changed - clients_assigned - clients_revoked - policy_changed Audit_Entry_Format: timestamp: "ISO 8601 with timezone" event_type: "category.action" username: "acting user" target: "affected resource" client_vat: "if client-specific" result: "success/failure" details: "additional context" ip_address: "source IP" session_id: "active session" ``` ## Success Metrics A successful authentication system deployment should achieve: - ✅ **Secure Authentication**: bcrypt password hashing, optional 2FA, session management - ✅ **Role Hierarchy**: Four-level role system matching accounting firm structures - ✅ **Per-Client Access**: Granular client data access assignment per user - ✅ **Session Security**: Timeout, idle detection, concurrent session limits - ✅ **Complete Audit Trail**: Every auth/authz event logged with context - ✅ **Account Protection**: Lockout policy, password requirements, brute-force prevention - ✅ **Cross-Skill Enforcement**: Authorization integrated into all data operations - ✅ **Admin Tools**: User management, access matrix, security reporting - ✅ **GDPR Compatible**: Access controls support data protection requirements - ✅ **Scalable**: Handle 50+ users across 500+ clients Remember: The authentication system is the security foundation for the entire Greek accounting platform. Every data access must pass through authorization checks, and every action must leave an audit trail.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)