luajitos

USAGE_EXAMPLE.md (10646B)

---

 # Password Prompt Usage Examples
 
 ## Quick Start
 
 ### 1. First-Time Setup
 
 Before using the password prompt system, you need to create a password hash:
 
 ```lua
 -- Boot into LuajitOS and run this code (requires crypto permission):
 
 local password = "admin"  -- Your chosen password
 local salt = "LuajitOS-AdminSalt-v1"
 
 -- Generate Argon2id hash
 local hash = crypto.Argon2id(password, salt)
 
 -- Base64 encode function
 local b64chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
 local function base64_encode(data)
     if not data or #data == 0 then return "" end
     local result = {}
     for i = 1, #data, 3 do
         local b1 = string.byte(data, i)
         local b2 = string.byte(data, i + 1) or 0
         local b3 = string.byte(data, i + 2) or 0
         local n = b1 * 65536 + b2 * 256 + b3
         local c1 = bit.band(bit.rshift(n, 18), 63) + 1
         local c2 = bit.band(bit.rshift(n, 12), 63) + 1
         local c3 = bit.band(bit.rshift(n, 6), 63) + 1
         local c4 = bit.band(n, 63) + 1
         table.insert(result, b64chars:sub(c1, c1))
         table.insert(result, b64chars:sub(c2, c2))
         if i + 1 <= #data then table.insert(result, b64chars:sub(c3, c3)) else table.insert(result, '=') end
         if i + 2 <= #data then table.insert(result, b64chars:sub(c4, c4)) else table.insert(result, '=') end
     end
     return table.concat(result)
 end
 
 -- Print the hash
 print("Password hash (base64):")
 print(base64_encode(hash))
 print("")
 print("Save this to /os/password.hash and rebuild the ISO")
 ```
 
 ### 2. Start the Password Prompt Service
 
 ```lua
 -- Run the password prompt app (stays in background)
 run("com.luajitos.passprompt")
 ```
 
 The app will export two functions:
 - `admin.requestPermission(pid, permission, callback)`
 - `admin.requestPath(pid, path, callback)`
 
 ## Example 1: Request Network Permission
 
 ```lua
 -- In your app manifest.lua, add:
 permissions = {
     "draw",
     "import"  -- Required to import from other apps
 }
 
 -- In your app code:
 local function enableNetworking()
     -- Get the passprompt app
     local passprompt = apps["com.luajitos.passprompt"]
 
     if not passprompt then
         print("ERROR: Password prompt app not running")
         print("Run: run('com.luajitos.passprompt')")
         return
     end
 
     -- Get the exported function
     local requestPerm = passprompt.exports["admin.requestPermission"]
     if not requestPerm then
         print("ERROR: admin.requestPermission not found")
         return
     end
 
     -- Request permission
     print("Requesting network permission...")
     requestPerm.func(app.pid, "network", function(granted)
         if granted then
             print("SUCCESS! Network permission granted")
             -- Now you can use network APIs
             -- local SafeHTTP = require("SafeHTTP")
             -- local response = SafeHTTP.get("http://example.com")
         else
             print("Permission denied or cancelled")
         end
     end)
 end
 
 -- Call when user clicks a "Connect" button
 window.onClick = function(mx, my)
     if clickedConnectButton(mx, my) then
         enableNetworking()
     end
 end
 ```
 
 ## Example 2: Request Filesystem Path Access
 
 ```lua
 -- Request access to system logs
 local function requestLogAccess()
     local passprompt = apps["com.luajitos.passprompt"]
 
     if not passprompt or not passprompt.exports["admin.requestPath"] then
         print("ERROR: Password prompt not available")
         return
     end
 
     local requestPath = passprompt.exports["admin.requestPath"]
 
     print("Requesting /var/log/* access...")
     requestPath.func(app.pid, "/var/log/*", function(granted)
         if granted then
             print("Path access granted!")
             -- Now you can read/write to /var/log/*
             local logs = fs:read("/var/log/system.log")
             if logs then
                 print("Log file contents:")
                 print(logs)
             end
         else
             print("Path access denied")
         end
     end)
 end
 ```
 
 ## Example 3: Request Multiple Permissions
 
 ```lua
 local function requestAllPermissions()
     local passprompt = apps["com.luajitos.passprompt"]
 
     if not passprompt then
         print("Password prompt app not running")
         return
     end
 
     local requestPerm = passprompt.exports["admin.requestPermission"].func
     local permissions = {"network", "ramdisk", "scheduling"}
     local currentIndex = 1
 
     local function requestNext()
         if currentIndex > #permissions then
             print("All permissions processed!")
             return
         end
 
         local perm = permissions[currentIndex]
         print("Requesting: " .. perm)
 
         requestPerm(app.pid, perm, function(granted)
             if granted then
                 print("Granted: " .. perm)
             else
                 print("Denied: " .. perm)
             end
 
             currentIndex = currentIndex + 1
             requestNext()  -- Request next permission
         end)
     end
 
     requestNext()
 end
 ```
 
 ## Example 4: Safe Permission Request with Retry
 
 ```lua
 local function safeRequestPermission(permission, maxRetries)
     maxRetries = maxRetries or 3
     local attempts = 0
 
     local function tryRequest()
         attempts = attempts + 1
 
         local passprompt = apps["com.luajitos.passprompt"]
         if not passprompt or not passprompt.exports["admin.requestPermission"] then
             print("ERROR: Password prompt not available")
             return
         end
 
         local requestPerm = passprompt.exports["admin.requestPermission"].func
 
         requestPerm(app.pid, permission, function(granted)
             if granted then
                 print("Permission granted: " .. permission)
                 -- Continue with your app logic
             elseif attempts < maxRetries then
                 print("Attempt " .. attempts .. " failed. " .. (maxRetries - attempts) .. " retries remaining")
                 -- Let user try again
             else
                 print("Failed to obtain permission after " .. maxRetries .. " attempts")
                 -- Gracefully degrade or exit
             end
         end)
     end
 
     tryRequest()
 end
 
 -- Usage:
 safeRequestPermission("network", 3)
 ```
 
 ## Example 5: Conditional Permission Request
 
 ```lua
 -- Only request permission if not already granted
 local function ensurePermission(permission, callback)
     -- Check if we already have the permission
     local hasPermission = false
     if app.permissions then
         for _, perm in ipairs(app.permissions) do
             if perm == permission then
                 hasPermission = true
                 break
             end
         end
     end
 
     if hasPermission then
         print("Already have permission: " .. permission)
         if callback then callback(true) end
         return
     end
 
     -- Don't have it, request it
     print("Requesting permission: " .. permission)
     local passprompt = apps["com.luajitos.passprompt"]
 
     if not passprompt or not passprompt.exports["admin.requestPermission"] then
         print("ERROR: Cannot request permission")
         if callback then callback(false) end
         return
     end
 
     local requestPerm = passprompt.exports["admin.requestPermission"].func
     requestPerm(app.pid, permission, callback)
 end
 
 -- Usage:
 ensurePermission("network", function(granted)
     if granted then
         -- Use network
     else
         -- Show error to user
     end
 end)
 ```
 
 ## Testing the Password Prompt
 
 Run the included test application:
 
 ```lua
 run("com.luajitos.passprompttest")
 ```
 
 This will create a window with two buttons:
 1. **Request Network Permission** - Tests `admin.requestPermission`
 2. **Request /var/log/* Path** - Tests `admin.requestPath`
 
 Click either button to see the password prompt appear on top of all windows.
 
 ## Password Prompt UI
 
 When the prompt appears:
 
 ### Keyboard Controls
 - **Type**: Enter your password (displayed as asterisks)
 - **Backspace**: Delete last character
 - **Enter**: Submit password
 - **Escape**: Cancel request
 
 ### Mouse Controls
 - **OK Button**: Submit password
 - **Cancel Button**: Cancel request
 - **Close (X)**: Cancel request
 
 ### Visual Feedback
 - **Blue text**: Shows PID and requested permission/path
 - **Red text**: Shows error messages (wrong password, etc.)
 - **Cursor blink**: Indicates input field is active
 
 ## Security Best Practices
 
 ### For App Developers
 
 1. **Only request what you need**: Don't request permissions unnecessarily
 2. **Explain to users**: Show why you need the permission before prompting
 3. **Handle denials gracefully**: Don't crash if permission is denied
 4. **Don't spam requests**: Only request once per user action
 5. **Clear sensitive data**: Don't store passwords or responses
 
 ### For System Administrators
 
 1. **Use strong passwords**: Minimum 12 characters, mix of types
 2. **Change default password**: Don't use "admin" in production
 3. **Monitor requests**: Check serial console logs for suspicious activity
 4. **Limit app access**: Only install trusted apps with "import" permission
 5. **Regular audits**: Review which apps have which permissions
 
 ## Troubleshooting
 
 ### "Password prompt app not running"
 ```lua
 run("com.luajitos.passprompt")
 ```
 
 ### "admin.requestPermission not found"
 The passprompt app may not have exported the function. Check logs:
 ```
 osprint("Passprompt exports: ", app.listExports())
 ```
 
 ### Password prompt doesn't appear
 - Check that passprompt has "draw" and "system-all" permissions
 - Verify window is set to `alwaysOnTop = true`
 - Check serial console for errors
 
 ### "Password file not found"
 Generate and save password hash to `/os/password.hash` (see First-Time Setup)
 
 ### "Incorrect password" even with correct password
 - Verify hash was generated with same salt: "LuajitOS-AdminSalt-v1"
 - Check for whitespace in password.hash file
 - Ensure base64 encoding is correct
 
 ## Advanced Usage
 
 ### Custom Salt (Not Recommended)
 
 If you need a different salt for security reasons:
 
 1. Modify `iso_includes/apps/com.luajitos.passprompt/src/init.lua`
 2. Change line: `local salt = "LuajitOS-AdminSalt-v1"`
 3. Regenerate password hash with new salt
 4. Rebuild ISO
 
 **Warning**: This breaks compatibility with existing password hashes.
 
 ### Integration with External Auth
 
 You can modify the `verifyPassword` function to check against:
 - LDAP servers
 - OAuth tokens
 - Hardware keys (via custom crypto hooks)
 
 This requires modifying the passprompt app source code.
 
 ## See Also
 
 - `README.md` - Full documentation
 - `/os/SETUP_PASSWORD.md` - Password setup instructions
 - `manifest.lua` - Permission requirements
 - `com.luajitos.passprompttest` - Test application source