User Account Management

Overview

The User Account Management system provides comprehensive user and group management, authentication, and permissions for FreeWorld OS. It includes user account creation/deletion, password management, account policies, privilege management, and access control.

Components

1. UserAccountManager

Location: system/user-accounts.js

Manages user accounts and groups:

• User creation, deletion, and modification
• Group management
• Account policies (locking, expiration)
• Persistent storage (JSON files)

2. AuthenticationSystem

Location: system/authentication.js

Handles authentication and password management:

• Password hashing (PBKDF2-SHA512)
• Password verification
• Login sessions
• Password policies

3. PermissionsManager

Location: system/permissions.js

Manages privileges and access control:

• Privilege definition and assignment
• Access control checking
• ACL (Access Control List) support
• Policy enforcement

4. FreeWorldLogon

Location: system/freeworldlogon.js

Provides login service integration:

• User login/logout
• Session management
• Integration with authentication and permissions

User Management

Creating Users

const UserAccountManager = require('./system/user-accounts');

const userAccounts = new UserAccountManager();

// Create a new user
const user = userAccounts.createUser('john', {
    home: '/home/john',
    shell: '/bin/sh',
    groups: ['Users'],
    fullName: 'John Doe',
    email: 'john@example.com',
    description: 'Regular user account'
});

console.log('Created user:', user.username, 'UID:', user.uid);

User Properties

Each user has the following properties:

• username - Username (1-32 characters)
• uid - User ID (unique numeric identifier)
• gid - Primary group ID
• home - Home directory path
• shell - Default shell
• groups - Array of group names
• passwordHash - Hashed password (PBKDF2)
• accountLocked - Whether account is locked
• accountExpires - Account expiration date
• lastLogin - Last login timestamp
• failedLoginAttempts - Number of failed login attempts

Modifying Users

// Modify user properties
userAccounts.modifyUser('john', {
    home: '/home/john.doe',
    fullName: 'John A. Doe',
    email: 'john.doe@example.com'
});

Deleting Users

// Delete user (cannot delete root or SYSTEM)
userAccounts.deleteUser('john');

Authentication

Password Management

const AuthenticationSystem = require('./system/authentication');

const auth = new AuthenticationSystem();

// Set user password (validates strength)
auth.setUserPassword('john', 'SecurePassword123!');

// Change password (requires old password)
auth.changeUserPassword('john', 'OldPassword', 'NewPassword123!');

Password Requirements

• Minimum 8 characters
• Maximum 128 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number

Login

const FreeWorldLogon = require('./system/freeworldlogon');

const logon = new FreeWorldLogon();

// Login user
const loginResult = logon.login('john', 'SecurePassword123!');

if (loginResult.success) {
    console.log('Session ID:', loginResult.session.sessionId);
    console.log('User:', loginResult.user.username);
} else {
    console.error('Login failed:', loginResult.error);
}

Password Hashing

Passwords are hashed using PBKDF2-SHA512:

• Algorithm: PBKDF2 with SHA-512
• Iterations: 100,000
• Key Length: 512 bits (64 bytes)
• Salt: 32-byte random salt per password

Account Policies

Account Locking

// Lock account
userAccounts.lockAccount('john');

// Unlock account
userAccounts.unlockAccount('john');

// Check if account is locked
const isLocked = userAccounts.isAccountLocked('john');

Account Expiration

// Set account expiration (1 year from now)
const expirationDate = new Date();
expirationDate.setFullYear(expirationDate.getFullYear() + 1);
userAccounts.setAccountExpiration('john', expirationDate.toISOString());

// Remove expiration
userAccounts.setAccountExpiration('john', null);

Failed Login Tracking

The system automatically tracks failed login attempts:

• After 5 failed attempts, account is automatically locked
• Failed attempts are reset on successful login
• Failed attempts can be manually reset

Group Management

Creating Groups

// Create a new group
const group = userAccounts.createGroup('Developers', {
    description: 'Software developers'
});

console.log('Created group:', group.name, 'GID:', group.gid);

Adding Users to Groups

// Add user to group
userAccounts.addUserToGroup('john', 'Developers');

// Remove user from group
userAccounts.removeUserFromGroup('john', 'Developers');

// Get user's groups
const groups = userAccounts.getUserGroups('john');

Default Groups

• root (GID 0) - Root user group
• wheel (GID 1) - Administrative group
• Users (GID 1000) - Regular users
• Administrators (GID 544) - Administrators
• SYSTEM (GID 18) - System accounts

Permissions and Privileges

Privileges

The system supports the following privileges:

• SeSystemtimePrivilege - Change system time
• SeShutdownPrivilege - Shut down the system
• SeBackupPrivilege - Back up files
• SeRestorePrivilege - Restore files
• SeCreateUserPrivilege - Create user accounts
• SeDeleteUserPrivilege - Delete user accounts
• SeModifyUserPrivilege - Modify user accounts
• SeTakeOwnershipPrivilege - Take ownership of files
• SeSecurityPrivilege - Manage security settings
• SeNetworkLogonRight - Network logon
• SeInteractiveLogonRight - Local logon

Granting Privileges

const PermissionsManager = require('./system/permissions');

const permissions = new PermissionsManager();

// Grant privilege to user
permissions.grantPrivilege('john', 'SeCreateUserPrivilege');

// Revoke privilege
permissions.revokePrivilege('john', 'SeCreateUserPrivilege');

// Check if user has privilege
const hasPrivilege = permissions.hasPrivilege('john', 'SeCreateUserPrivilege');

// Get user's privileges
const userPrivileges = permissions.getUserPrivileges('john');

Access Control

// Check if user can access resource
const resource = {
    path: '/home/john/document.txt',
    owner: 'john',
    ownerUid: 1001,
    group: 'Users',
    permissions: {
        owner: { read: true, write: true, execute: false },
        group: { read: true, write: false, execute: false },
        others: { read: false, write: false, execute: false }
    }
};

const accessResult = permissions.checkAccess('john', resource, 'read');
console.log('Can read:', accessResult.allowed, accessResult.reason);

Storage

User and group data is stored in JSON files:

• var/lib/users.json - User accounts
• var/lib/groups.json - Groups

Data is automatically saved after each modification operation.

Filesystem Permissions Integration

The User Account Management system is fully integrated with the filesystem API for permission checking:

Automatic Permission Checking

All filesystem operations automatically check permissions before execution:

• Read operations: Check read permission on file/directory
• Write operations: Check write permission on file or parent directory
• Delete operations: Check write/delete permission
• Create operations: Check write permission on parent directory

Setting User Context

const FileSystem = require('./system/filesystem');

const fs = new FileSystem();

// Set current user context for permission checks
fs.setCurrentUser('john');

// All operations now check permissions for 'john'
try {
    const content = fs.readFile('/home/john/document.txt');
    console.log('File read successfully');
} catch (error) {
    console.error('Access denied:', error.message);
}

Permission Checking

The filesystem uses the PermissionsManager to check access:

• Checks file ownership (owner, group, others)
• Checks file permissions (read, write, execute)
• Checks ACLs (Access Control Lists) if present
• Checks user privileges (e.g., SeTakeOwnershipPrivilege)
• Root user (UID 0) has full access to all files

File Ownership Operations

// Get file owner
const owner = fs.getOwner('/home/john/document.txt');
console.log('Owner:', owner.owner, 'UID:', owner.ownerUid);

// Take ownership (requires SeTakeOwnershipPrivilege)
try {
    fs.takeOwnership('/home/john/document.txt');
    console.log('Ownership taken successfully');
} catch (error) {
    console.error('Access denied:', error.message);
}

// Set file permissions (requires SeSecurityPrivilege or ownership)
try {
    fs.setPermissions('/home/john/document.txt', {
        owner: { read: true, write: true, execute: false },
        group: { read: true, write: false, execute: false },
        others: { read: false, write: false, execute: false }
    });
} catch (error) {
    console.error('Access denied:', error.message);
}

Access Denied Errors

When a filesystem operation is denied, an error is thrown with a descriptive message:

• Access denied: Owner access - User is owner but lacks permission
• Access denied: Group access - User is in group but lacks permission
• Access denied: Others access - User has others permission
• Access denied: ACL deny - ACL explicitly denies access
• Access denied: Requires SeSecurityPrivilege - Operation requires privilege

Integration

The User Account Management system integrates with:

• FreeWorld Logon: User authentication and login
• Security Manager: Session and token management
• File System: ✅ Fully integrated - All filesystem operations check permissions automatically
• Shell: User context for commands
• Process Management: Process ownership and privileges

Related Documentation

• Security Manager
• securityd
• FreeWorld Logon
• File System