User Accounts & Authentication

Overview

Aurora OS features a production-grade authentication system powered by the BPE/U (Browser Processing Engine/Unit) with persistent credential storage that survives browser cache clears.

User credentials are encrypted with AES-GCM and stored across OPFS, IndexedDB, and Service Worker cache for maximum durability

Authentication System

The BPEAuth subsystem provides secure user authentication with modern cryptography.

PBKDF2 Hashing

600,000 iterations with SHA-256 and 32-byte salts

Multi-Tier Storage

OPFS → IndexedDB → Service Worker cache → localStorage

Rate Limiting

5 failed attempts trigger exponential lockout (30s, 60s, 120s…)

Session Management

30-minute inactivity timeout with automatic lock screen

Boot Sequence

Aurora OS boots through a realistic hardware-like sequence:

Phase 1: BIOS POST

AURORA BPE/U BIOS v1.0
Copyright (c) 2026 AURORA Project

BPE/U — Browser Processing Engine/Unit
Processor: Virtual BPE CPU
Cores: 8 @ 3200 MHz

Testing memory... 8192 MB OK

Detecting devices...
  Display: 1920x1080 @ 60Hz
  Input: Keyboard + Mouse
  Storage: OPFS + IndexedDB
  Network: WebSocket bridge
  Clock: Browser API (accurate to 5µs)

POST complete. All devices OK.

Booting from /dev/opfs0...

Phase 2: Bootloader

[boot] AURORA Bootloader v1.0
[boot] Loading kernel image...
[boot] Kernel WASM loaded (real C kernel → wasm32)
[kernel] AURORA OS v0.1.0 (BPE/U 1.0)
[kernel] Command line: root=/dev/opfs0 console=tty0 quiet
[kernel] Initializing BPE core engine...

Phase 3: Kernel Initialization

Memory Manager
Process Manager
Filesystem
Authentication

[mm] Initializing memory manager...
[mm] Physical allocator: WASM bitmap (real C kernel code)
[mm] 2048 frames (8192 MB)
[mm] Heap allocator: WASM kmalloc (real C kernel code)

[proc] Initializing process manager...
[proc] PID 0 (idle) created
[proc] PID 1 (init) created
[sched] Priority queue: WASM min-heap (real C kernel code)

[vfs] Initializing virtual filesystem...
[vfs] Filesystem restored from OPFS
[vfs] Mount points: / /home /dev /proc /sys /tmp

[auth] Initializing credential store...
[auth] Credential store loaded (OPFS)
[security] MAC policy: WASM (real C kernel code)
[security] Capability tokens: WASM (real C kernel code)

Phase 4: Init System

[init] Starting authentication daemon...
[init] Starting network daemon...
[init] Starting display server...
[init] Starting input manager...
[init] Starting filesystem sync daemon...
[init] Starting agent runtime...
[init] Starting GPU compositor...

[init] Boot complete.

First Boot: Out-of-Box Experience (OOBE) - Create first user
Subsequent Boots: Login screen with user selection

The entire boot sequence takes approximately 2-3 seconds with authentic POST and kernel messages

First-Time Setup (OOBE)

When no users exist, Aurora OS launches the Out-of-Box Experience.

Setup Steps

Welcome Screen

Introduction to Aurora OS with animated logo

Create Account

Enter username (1-32 alphanumeric characters and underscores)
Choose display name (shown in UI)
Select avatar from 20 emoji options
Create password (minimum 4 characters, 8+ recommended)
Confirm password

Timezone Setup

Auto-detected via Intl.DateTimeFormat
Manual override available
Confirm time display format

Appearance

Choose theme: Light, Dark, or System
Select default wallpaper (11 options)
Preview your choices

Complete Setup

User account created with UID 1000
Home directory initialized: /home/username
Entry added to /etc/passwd
First user is automatically admin
Boot to desktop

Avatar Options

Choose from 20 colorful emoji avatars:

Available Avatars

🦊 Fox • 🐼 Panda • 🦁 Lion • 🐯 Tiger • 🦄 Unicorn • 🐸 Frog • 🐙 Octopus • 🦋 Butterfly • 🐝 Bee • 🐧 Penguin • 🦉 Owl • 🦅 Eagle • 🐲 Dragon • 👽 Alien • 🤖 Robot • 🎨 Palette • 🎭 Theater • 🎪 Circus • 🚀 Rocket • ⚡ Lightning

After setup, Aurora OS boots to the login screen.

Single User Mode

When only one user exists:

Clock and date display (real-time, timezone-aware)
User avatar with display name
Password input field
“Show password” toggle button
Sign-in button (→)
Power buttons (Sleep, Restart, Shut Down)

Multi-User Mode

When multiple users exist:

Clock and date display
User selection cards with:
- Avatar
- Display name
- Role (Administrator or User)
Click a user to enter password
“Switch User” button to go back
Power buttons

Press Enter after typing your password for quick login

Security Features

Password Hashing

Aurora OS uses industry-standard PBKDF2 with aggressive parameters:

// Password hashing configuration
PBKDF2_ITERATIONS = 600000     // OWASP recommended (2023)
SALT_BYTES = 32                // 256-bit random salt
HASH_ALGO = 'SHA-256'          // SHA-256 hash function

// Process:
// 1. Generate 32-byte random salt per user
// 2. Derive 256-bit hash with 600k iterations
// 3. Store hash and salt (never plaintext password)
// 4. Constant-time comparison on login

Rate Limiting

Protection against brute-force attacks:

5 Failed Attempts

30-second lockout after 5 incorrect passwords

Exponential Backoff

Lockout doubles: 30s → 60s → 120s → 240s…

Per-Session

Counters reset on successful login

Visual Feedback

Shake animation on incorrect password

Credential Encryption

User credentials are encrypted before storage:

// Encryption: AES-GCM with machine-specific key
// 1. Generate unique machine ID (stored in OPFS)
// 2. Derive AES-256-GCM key from machine ID via PBKDF2
// 3. Encrypt credential blob with 12-byte random IV
// 4. Prepend IV to ciphertext
// 5. Store in OPFS, IndexedDB, and SW cache

// Decryption: Reverse process using machine ID
// - If machine ID is lost, credentials are unrecoverable
// - Provides protection even if storage is extracted

Multi-Tier Persistence

Credentials survive even aggressive cache clearing:

Tier 1: OPFS

Origin Private File System - Most durable, survives cache clear

Tier 2: IndexedDB

Large structured data - Survives most cache clears

Tier 3: Service Worker Cache

SW cache API - Additional redundancy

Tier 4: localStorage

Machine ID fallback (less durable, but better than nothing)

When saving, credentials are written to all tiers. When loading, Aurora tries each tier in order until successful.

Managing User Accounts

Adding New Users

Administrators can create additional accounts:

Open Settings → Users & Accounts
Click Add User
Enter username (must be unique)
Choose display name and avatar
Set password (minimum 4 characters)
Select role: Standard User or Administrator
Click Create

Via Terminal (admin only):

# User creation is handled by BPEAuth API
# CLI tool coming in future release

User Roles

Administrator
Standard User

Permissions:

Create/delete users
Modify system settings
Install/remove applications
Access all user home directories (with proper sudo)
Change system-wide preferences
View system logs
Factory reset

UID Range: 0-999 (UID 0 is reserved for root)

The first user created during OOBE is automatically an Administrator

Password Management

Changing Your Password

Open Settings → Users & Accounts
Click Change Password under your account
Enter current password
Enter new password (min 4 chars, 8+ recommended)
Confirm new password
Click Save

Password Requirements:

Minimum 4 characters (8+ recommended for security)
No maximum length
Any characters allowed (Unicode supported)
Passwords are case-sensitive

Forgotten Password

If you forget your password:

There is no password reset mechanism by design. Aurora OS cannot recover passwords due to PBKDF2 one-way hashing. You must perform a factory reset, which erases all data.

Recovery Options:

Browser DevTools: If you have browser access, you can inspect localStorage/OPFS
Factory Reset: Erases all users and data (Settings → System → Factory Reset)
Prevention: Use a password manager or write it down securely

Sessions & Lock Screen

Session Management

After successful login, Aurora OS creates a session:

// Session object structure
{
  uid: 1000,
  username: "alice",
  displayName: "Alice Smith",
  avatar: "fox",
  isAdmin: true,
  token: "64-char-hex-token",  // Random session token
  loginTime: 1709251200000,     // Unix timestamp
  lastActivity: 1709251200000   // Updated on interaction
}

Session Timeout

Default Timeout: 30 minutes of inactivity
Behavior: Session lock (not logout) - desktop remains, requires password
Activity Detection: Mouse movement, keyboard input, app interaction
Configuration: Settings → Security → Session Timeout (5, 15, 30, 60 min, or Never)

Lock Screen

Lock your session to protect privacy: Trigger Lock:

Press Super + L or Cmd + L
User menu → Lock Screen
Automatic after inactivity timeout
Close laptop lid (if detected)

Lock Screen UI:

Real-time clock and date
Locked user’s avatar and name
Password prompt
“Show password” toggle
No power buttons (different from login screen)

Lock screen keeps all apps running in the background. Logging out closes all applications.

Multi-User Support

Aurora OS fully supports multiple concurrent users (though only one active session).

User Isolation

Home Directories

Each user has /home/username with read/write permissions

Process Ownership

Processes run with user’s UID and permission checks

File Permissions

Standard Unix permissions (rwx for user/group/other)

App Sandboxing

Apps run in user context with MAC policy enforcement

Switching Users

Currently, Aurora OS supports one active session at a time:

Log out current user (closes all apps)
Return to login screen
Select different user
Enter password
Boot to new user’s desktop

Fast user switching (keeping sessions active) is planned for a future release

User Data & Files

Home Directory Structure

Each user gets a home directory at /home/username:

/home/username/
├── Desktop/       # Desktop files
├── Documents/     # User documents
├── Downloads/     # Downloaded files
├── Pictures/      # Images and photos
├── .bashrc        # Shell configuration
└── .profile       # Login script

Application Data

Apps store data in user-specific locations:

Notes: localStorage key aurora-notes (JSON array)
Tasks: localStorage key aurora-tasks (JSON array)
Settings: localStorage keys prefixed with aurora-*
Browser: IndexedDB aurora-browser database
Music: Playlist in localStorage key aurora-music-playlist

Data is scoped to the browser origin and survives across sessions and cache clears (OPFS-backed)

System Logs

Authentication events are logged to /var/log/auth.log:

# View authentication log
cat /var/log/auth.log

# Example entries:
useradd: user 'alice' created (uid=1000)
login: SUCCESS for 'alice' (uid=1000)
login: FAILED for 'bob' (user not found)
login: FAILED for 'alice' (wrong password)
logout: 'alice'
passwd: password changed for 'alice'
userdel: user 'bob' deleted

Factory Reset

Completely erase all user accounts and data.

Performing Factory Reset

This action is irreversible. All user accounts, files, and settings will be permanently deleted.

Open Settings → System
Scroll to Factory Reset
Read the warning carefully
Enter admin password to confirm
Click Reset Aurora OS
System will:
- Delete all credentials from OPFS, IndexedDB, SW cache, localStorage
- Erase machine ID
- Clear all user data
- Reset to OOBE state
Page reloads to Out-of-Box Experience

What Gets Erased

✅ All user accounts and passwords
✅ All home directory contents
✅ Application data (Notes, Tasks, Browser history, etc.)
✅ System settings and preferences
✅ Credential encryption keys
✅ Session tokens
✅ Machine ID

What Survives

✅ Operating system code (loaded from HTML/JS files)
✅ Built-in applications (part of OS)
❌ Installed apps from App Store (erased)

Security Best Practices

Strong Passwords

Use 12+ characters with mix of letters, numbers, symbols

Unique Passwords

Don’t reuse passwords from other services

Lock When Away

Press Super + L when leaving your desk

Regular Updates

Keep Aurora OS updated (check Settings → System → Updates)

Review Logs

Check /var/log/auth.log for suspicious activity

Limit Admin Accounts

Only make users admin if they need elevated privileges

Advanced: BPE/U Architecture

For developers and advanced users interested in the authentication implementation:

Components

BPEAuth
BPELogin
BPEOOBE
BPEBoot

Core authentication module with:

PBKDF2 password hashing (600k iterations)
Session management with tokens
Multi-tier credential persistence
Rate limiting and lockout
User CRUD operations

Syscalls

Authentication exposes syscalls for process integration:

// BPE syscall numbers (via BPESyscall.NR)
SPAWN      // Create new process with UID/GID
KILL       // Terminate process (permission check)
GETUID     // Get process UID
SETUID     // Set process UID (admin only)
GETEUID    // Get effective UID
AUTH_LOGIN // Authenticate user (userspace helper)

All file and process operations go through the BPE kernel with MAC (Mandatory Access Control) policy enforcement

Get Started

Architecture

User Guide

Development

Security

​Overview

​Authentication System

PBKDF2 Hashing

Multi-Tier Storage

Rate Limiting

Session Management

​Boot Sequence

​Phase 1: BIOS POST

​Phase 2: Bootloader

​Phase 3: Kernel Initialization

​Phase 4: Init System

​Phase 5: Login or OOBE

​First-Time Setup (OOBE)

​Setup Steps

​Avatar Options

​Login Screen

​Single User Mode

​Multi-User Mode

​Security Features

​Password Hashing

​Rate Limiting

5 Failed Attempts

Exponential Backoff

Per-Session

Visual Feedback

​Credential Encryption

​Multi-Tier Persistence

​Managing User Accounts

​Adding New Users

​User Roles

​Password Management

​Changing Your Password

​Forgotten Password

​Sessions & Lock Screen

​Session Management

​Session Timeout

​Lock Screen

​Multi-User Support

​User Isolation

Home Directories

Process Ownership

File Permissions

App Sandboxing

​Switching Users

​User Data & Files

​Home Directory Structure

​Application Data

​System Logs

​Factory Reset

​Performing Factory Reset

​What Gets Erased

​What Survives

​Security Best Practices

Strong Passwords

Unique Passwords

Lock When Away

Regular Updates

Review Logs

Limit Admin Accounts

​Advanced: BPE/U Architecture

​Components

​Syscalls

Build docs developers (and LLMs) love

Overview

Authentication System

Boot Sequence

Phase 1: BIOS POST

Phase 2: Bootloader

Phase 3: Kernel Initialization

Phase 4: Init System

Phase 5: Login or OOBE

First-Time Setup (OOBE)

Setup Steps

Avatar Options

Login Screen

Single User Mode

Multi-User Mode

Security Features

Password Hashing

Rate Limiting

Credential Encryption

Multi-Tier Persistence

Managing User Accounts

Adding New Users

User Roles

Password Management

Changing Your Password

Forgotten Password

Sessions & Lock Screen

Session Management

Session Timeout

Lock Screen

Multi-User Support

User Isolation

Switching Users

User Data & Files

Home Directory Structure

Application Data

System Logs

Factory Reset

Performing Factory Reset

What Gets Erased

What Survives

Security Best Practices

Advanced: BPE/U Architecture

Components

Syscalls