commit 1fea51c1d813f786f0afa1115e2b664cc3388aea
parent 2b2dda510a0464bbf3f7817902a8758eee2e668d
Author: luajitos <bbhbb2094@gmail.com>
Date: Sat, 29 Nov 2025 19:51:25 +0000
Removed Useless Files
Diffstat:
33 files changed, 0 insertions(+), 12246 deletions(-)
diff --git a/ADMIN_PERMISSION.md b/ADMIN_PERMISSION.md
@@ -1,192 +0,0 @@
-# Admin Permission System
-
-## Overview
-The `"admin"` permission grants applications the ability to modify permissions and allowed paths of running applications at runtime. This is a powerful capability designed for system management tools.
-
-## Implementation
-
-### Core Components
-
-1. **sys.lua** - Admin API Functions
- - `sys.ADMIN_AppAddPermission(pid, permission)` - Add a permission to a running app
- - `sys.ADMIN_AppAddPath(pid, path)` - Add an allowed path pattern to a running app
- - `sys.ADMIN_StartPrompt(window)` - Enter exclusive prompt mode (freezes all other apps)
- - `sys.ADMIN_FinishPrompt()` - Exit exclusive prompt mode (resumes all apps)
-
-2. **run.lua** - Permission Enforcement
- - Stores `permissions` and `allowedPaths` in app instance during launch
- - Checks for `"admin"` permission and exposes admin functions to sandbox
- - Protects admin functions in dangerous_globals whitelist
-
-3. **Application Instance Storage**
- - Each app instance now stores:
- - `app.permissions` - Array of permission strings
- - `app.allowedPaths` - Array of allowed path patterns
-
-## Usage
-
-### Requesting Admin Permission
-
-In your app's manifest.lua:
-```lua
-permissions = {
- "admin",
- "system-all" -- Usually needed to list running apps
-}
-```
-
-### Using Admin Functions
-
-```lua
--- List all running apps
-for pid, app in pairs(sys.applications) do
- print("PID " .. pid .. ": " .. app.appName)
- if app.permissions then
- print(" Permissions: " .. table.concat(app.permissions, ", "))
- end
-end
-
--- Add a permission to an app
-ADMIN_AppAddPermission(targetPid, "network")
-
--- Add an allowed path to an app
-ADMIN_AppAddPath(targetPid, "/tmp/*")
-
--- Enter exclusive prompt mode
-local promptWindow = app:newWindow(300, 200, 400, 200)
-promptWindow.onDraw = function(gfx)
- gfx:fillRect(0, 0, 400, 200, 0x000080)
- gfx:drawText(10, 10, "Enter password:", 0xFFFFFF)
-end
-promptWindow.onInput = function(key, scancode)
- if scancode == 28 then -- Enter
- ADMIN_FinishPrompt()
- promptWindow:close()
- end
-end
-ADMIN_StartPrompt(promptWindow) -- All other apps frozen!
-```
-
-## Security Model
-
-### Protection Mechanisms
-
-1. **Explicit Permission Required**: Apps must declare `"admin"` in manifest
-2. **Dangerous Globals Filtering**: Admin functions blocked unless permission granted
-3. **Function Isolation**: Only `ADMIN_AppAddPermission` and `ADMIN_AppAddPath` exposed
-4. **No Raw sys Access**: Admin apps don't automatically get full `sys` object
-
-### Security Considerations
-
-The admin permission grants **privilege escalation** capabilities:
-- Can add any permission to any running app
-- Can grant filesystem access to any path
-- Equivalent to root/superuser privileges in the permission system
-
-**Best Practices:**
-- Only grant to trusted system utilities
-- Never grant to user-facing applications
-- Audit apps requesting this permission carefully
-- Consider it a "system-critical" permission level
-
-## Runtime Behavior
-
-### Permission Addition
-When `ADMIN_AppAddPermission(pid, perm)` is called:
-1. Validates that app with PID exists
-2. Checks if permission already granted (idempotent)
-3. Adds permission to `app.permissions` array
-4. Attempts to call `env._reapplyPermissions()` if available (future hook)
-
-**Note:** New permissions don't grant access to new APIs until app restarts. This is primarily for persistent permission changes.
-
-### Path Addition
-When `ADMIN_AppAddPath(pid, path)` is called:
-1. Validates that app with PID exists
-2. Checks if path already granted (idempotent)
-3. Adds path to `app.allowedPaths` array
-4. Updates SafeFS instance via `env.fs._updateAllowedPaths()` if available
-
-**Note:** Path changes CAN take effect immediately if SafeFS supports dynamic updates.
-
-### Exclusive Prompt Mode
-When `ADMIN_StartPrompt(window)` is called:
-1. Sets `sys.promptMode.active = true`
-2. Stores the window reference in `sys.promptMode.window`
-3. Forces window to be visible and always-on-top
-4. Modifies render loop to ONLY draw the prompt window
-5. Modifies event handlers to ONLY send events to prompt window
-6. Keyboard interrupt handler checks prompt mode FIRST
-
-**Critical Security Property:** Even interrupt handlers respect prompt mode. If a malicious app tries to draw or capture input from an interrupt, it will be blocked.
-
-When `ADMIN_FinishPrompt()` is called:
-1. Clears `sys.promptMode.active`
-2. Marks all windows as dirty for redraw
-3. Normal event processing resumes
-4. All apps can draw and receive events again
-
-**Use Cases:**
-- Password prompts that must not be intercepted
-- Critical system alerts that demand immediate attention
-- UAC-style elevation prompts
-- Secure credential entry for privileged operations
-
-## Example Applications
-
-**Permission/Path Management:** See `/apps/com.luajitos.admintest/` for a working example that:
-- Lists all running applications
-- Shows current permissions and paths
-- Adds permissions and paths to itself
-- Modifies other running apps (if available)
-
-**Exclusive Prompt Mode:** See `/apps/com.luajitos.prompttest/` for a working example that:
-- Creates an exclusive password prompt
-- Freezes all other applications (drawing and events)
-- Demonstrates interrupt-safe input handling
-- Shows proper prompt entry/exit flow
-
-## Testing
-
-**Test permission/path management:**
-```bash
-# In the OS, run from shell or start menu:
-run("com.luajitos.admintest")
-```
-
-Expected output:
-- List of running apps with permissions
-- Successful addition of "network" permission
-- Successful addition of "/tmp/*" path
-- Verification that changes persisted
-
-**Test exclusive prompt mode:**
-```bash
-# In the OS, run from shell or start menu:
-run("com.luajitos.prompttest")
-```
-
-Test procedure:
-1. Click anywhere in the normal window
-2. Exclusive prompt window appears (blue background)
-3. Try clicking on other windows → they won't respond
-4. Try typing in other windows → they won't receive input
-5. Type password "test123" in prompt
-6. Press Enter → prompt closes, all apps resume
-7. Try Esc to cancel prompt mode early
-
-## Future Enhancements
-
-Potential improvements:
-1. **Dynamic Permission Application**: Implement `_reapplyPermissions()` to allow runtime API changes
-2. **Permission Removal**: Add `ADMIN_AppRemovePermission()` and `ADMIN_AppRemovePath()`
-3. **Audit Logging**: Track all admin permission changes for security review
-4. **Permission Persistence**: Save permission changes to manifest for next boot
-5. **Fine-grained Admin**: Split admin into `admin:permissions` and `admin:paths` sub-permissions
-
-## Related Files
-
-- `/iso_includes/os/libs/sys.lua` - Admin API implementation
-- `/iso_includes/os/libs/run.lua` - Permission enforcement and storage
-- `/iso_includes/apps/com.luajitos.admintest/` - Example admin app
-- `/APP_DEVELOPMENT_GUIDE.md` - Complete API documentation
diff --git a/ANIMATEDIMAGE_LIBRARY.md b/ANIMATEDIMAGE_LIBRARY.md
@@ -1,434 +0,0 @@
-# AnimatedImage Library - Animated GIF Support
-
-## Overview
-
-The AnimatedImage library provides animated GIF creation and manipulation in LuajitOS. Each frame is an `Image` object that can be manipulated independently.
-
-**Permission Required:** `"imaging"`
-
-## Quick Start
-
-```lua
-local AnimatedImage = require("AnimatedImage")
-
--- Create a 128x128 animated GIF with 30 frames
-local anim = AnimatedImage.new(128, 128, 30)
-
--- Access and modify frames
-anim.frames[1]:fill({r = 255, g = 0, b = 0}) -- Red first frame
-anim.frames[2]:fill({r = 0, g = 255, b = 0}) -- Green second frame
-anim.frames[3]:fill({r = 0, g = 0, b = 255}) -- Blue third frame
-
--- Modify individual pixels in any frame
-anim.frames[10]:writePixel(64, 64, "FFFFFF")
-
--- Save as animated GIF
-anim:saveAsGIF("/home/animation.gif")
-```
-
-## Creating Animations
-
-### AnimatedImage.new(width, height, numFrames, delay)
-Create a new animated image.
-
-**Parameters:**
-- `width` - Frame width (1-4096 pixels)
-- `height` - Frame height (1-4096 pixels)
-- `numFrames` - Number of frames (default: 1, max: 1000)
-- `delay` - Delay between frames in centiseconds (default: 10 = 100ms)
-
-**Returns:** AnimatedImage object
-
-**Example:**
-```lua
--- Create 64x64 animation with 20 frames, 50ms delay
-local anim = AnimatedImage.new(64, 64, 20, 5)
-
--- Create 256x256 animation with 60 frames (1 second at 16.67ms/frame)
-local anim = AnimatedImage.new(256, 256, 60, 1.67)
-```
-
-## Frame Access
-
-Frames are stored in the `frames` array and are `Image` objects. All `Image` methods work on frames.
-
-### Direct Frame Access
-
-```lua
-local anim = AnimatedImage.new(100, 100, 10)
-
--- Access frame by index (1-based)
-local firstFrame = anim.frames[1]
-local lastFrame = anim.frames[anim.numFrames]
-
--- Modify frames using Image methods
-anim.frames[1]:fill("FF0000")
-anim.frames[2]:writePixel(50, 50, "00FF00")
-anim.frames[3]:fillRect(10, 10, 50, 50, "0000FF")
-anim.frames[4]:drawLine(0, 0, 99, 99, "FFFFFF")
-
--- Add images to frames
-local logo = Image.open("/home/logo.png")
-anim.frames[5]:addImage(logo, 25, 25)
-
--- Copy frame content
-local frame = anim.frames[1]:clone()
-frame:fill("00FF00")
-anim.frames[10] = frame
-```
-
-### getFrame(frameIndex)
-Get a specific frame.
-
-**Parameters:**
-- `frameIndex` - Frame index (1-based)
-
-**Returns:** Image object
-
-**Example:**
-```lua
-local frame5 = anim:getFrame(5)
-frame5:fill({r = 128, g = 128, b = 255})
-```
-
-### setFrame(frameIndex, image)
-Replace a specific frame.
-
-**Parameters:**
-- `frameIndex` - Frame index (1-based)
-- `image` - Image object (must match animation dimensions)
-
-**Example:**
-```lua
-local newFrame = Image.new(100, 100)
-newFrame:fill("FF00FF")
-anim:setFrame(1, newFrame)
-```
-
-## Animation Properties
-
-```lua
-local anim = AnimatedImage.new(128, 128, 30, 10)
-
--- Read properties
-print(anim.width) -- 128
-print(anim.height) -- 128
-print(anim.numFrames) -- 30
-print(anim.delay) -- 10 (centiseconds)
-print(anim.loop) -- true (default)
-
--- Modify properties
-anim.delay = 5 -- Faster animation (50ms per frame)
-anim.loop = false -- Play once
-```
-
-## Utility Functions
-
-### fillAll(color)
-Fill all frames with a color.
-
-**Example:**
-```lua
-anim:fillAll({r = 0, g = 0, b = 0}) -- All frames black
-```
-
-### clone()
-Create a copy of the animation.
-
-**Returns:** New AnimatedImage object
-
-**Example:**
-```lua
-local copy = anim:clone()
-copy.frames[1]:fill("FF0000") -- Modify copy without affecting original
-```
-
-## Saving Animations
-
-### saveAsGIF(path, options)
-Save as animated GIF file.
-
-**Parameters:**
-- `path` - File path to save
-- `options` - Optional table:
- - `fs` - SafeFS instance for sandboxed writing
-
-**Returns:** `true` or `nil, error`
-
-**Example:**
-```lua
--- Simple save
-anim:saveAsGIF("/home/animation.gif")
-
--- With SafeFS
-local SafeFS = require("safefs")
-local safeFS = SafeFS.new(myApp)
-anim:saveAsGIF("/apps/myapp/anim.gif", { fs = safeFS })
-```
-
-## Complete Examples
-
-### Example 1: Color Fade Animation
-
-```lua
-local AnimatedImage = require("AnimatedImage")
-
--- Create 60-frame fade animation
-local anim = AnimatedImage.new(200, 200, 60, 3) -- 3cs = 30ms/frame
-
-for i = 1, 60 do
- local intensity = math.floor((i - 1) * 255 / 59)
- anim.frames[i]:fill({
- r = intensity,
- g = 0,
- b = 255 - intensity,
- a = 255
- })
-end
-
-anim:saveAsGIF("/home/fade.gif")
-```
-
-### Example 2: Bouncing Ball
-
-```lua
-local AnimatedImage = require("AnimatedImage")
-
-local anim = AnimatedImage.new(100, 100, 20, 5)
-local ballSize = 10
-
-for i = 1, 20 do
- -- Clear frame
- anim.frames[i]:fill({r = 255, g = 255, b = 255})
-
- -- Calculate ball position (bounce)
- local t = (i - 1) / 19
- local y = math.floor(45 * math.abs(math.sin(t * math.pi)))
-
- -- Draw ball
- for dy = -ballSize, ballSize do
- for dx = -ballSize, ballSize do
- if dx*dx + dy*dy <= ballSize*ballSize then
- local px = 50 + dx
- local py = 90 - y + dy
- if px >= 0 and px < 100 and py >= 0 and py < 100 then
- anim.frames[i]:writePixel(px, py, "FF0000")
- end
- end
- end
- end
-end
-
-anim:saveAsGIF("/home/bounce.gif")
-```
-
-### Example 3: Loading Spinner
-
-```lua
-local AnimatedImage = require("AnimatedImage")
-
-local anim = AnimatedImage.new(64, 64, 12, 8) -- 12 frames, ~96ms/frame
-
-for i = 1, 12 do
- -- Clear frame
- anim.frames[i]:fill({r = 240, g = 240, b = 240})
-
- -- Draw spinner
- local angle = (i - 1) * (2 * math.pi / 12)
- local cx, cy = 32, 32
- local radius = 20
-
- for j = 0, 7 do
- local a = angle + j * (2 * math.pi / 8)
- local x = cx + math.floor(radius * math.cos(a))
- local y = cy + math.floor(radius * math.sin(a))
-
- -- Fade older dots
- local alpha = 255 - j * 30
-
- -- Draw dot
- for dy = -2, 2 do
- for dx = -2, 2 do
- if dx*dx + dy*dy <= 4 then
- local px, py = x + dx, y + dy
- if px >= 0 and px < 64 and py >= 0 and py < 64 then
- anim.frames[i]:writePixel(px, py, {
- r = 0, g = 100, b = 200, a = alpha
- })
- end
- end
- end
- end
- end
-end
-
-anim:saveAsGIF("/home/spinner.gif")
-```
-
-### Example 4: Frame-by-Frame Image Sequence
-
-```lua
-local AnimatedImage = require("AnimatedImage")
-local Image = require("Image")
-
--- Load sequence of images
-local frames = {}
-for i = 1, 10 do
- frames[i] = Image.open("/home/sequence/frame" .. i .. ".png")
-end
-
--- Create animation
-local anim = AnimatedImage.new(frames[1].width, frames[1].height, 10, 10)
-
--- Set frames
-for i = 1, 10 do
- anim:setFrame(i, frames[i])
-end
-
-anim:saveAsGIF("/home/sequence.gif")
-```
-
-### Example 5: Text Animation
-
-```lua
-local AnimatedImage = require("AnimatedImage")
-
-local anim = AnimatedImage.new(150, 50, 30, 5)
-
-local text = "HELLO"
-for i = 1, 30 do
- anim.frames[i]:fill({r = 0, g = 0, b = 0})
-
- -- Animate text position
- local x = i * 5 - 50
-
- -- Draw simple pixel text (simplified)
- -- In real code, you'd use a proper font/text rendering
- for j = 1, #text do
- local charX = x + (j - 1) * 20
- if charX >= 0 and charX < 150 then
- -- Draw simple vertical line as letter
- for y = 15, 35 do
- anim.frames[i]:writePixel(charX, y, "00FF00")
- end
- end
- end
-end
-
-anim:saveAsGIF("/home/scrolltext.gif")
-```
-
-## GIF Format Details
-
-### Color Palette
-- Uses 256-color palette
-- 6×6×6 color cube (216 colors) + 40 grayscale levels
-- Automatic color quantization (nearest color matching)
-
-### Compression
-- LZW compression (simplified implementation)
-- Standard GIF89a format
-- Netscape extension for looping
-
-### Frame Timing
-- Delay specified in centiseconds (1/100 second)
-- Examples:
- - `delay = 1` → 10ms (100 FPS)
- - `delay = 3` → 30ms (~33 FPS)
- - `delay = 10` → 100ms (10 FPS)
- - `delay = 100` → 1 second (1 FPS)
-
-### Looping
-- By default, animations loop infinitely
-- Set `anim.loop = false` for single playback
-
-## Performance Notes
-
-- **Frame creation**: O(width × height × numFrames)
-- **GIF encoding**: O(width × height × numFrames)
-- **Color quantization**: O(1) per pixel (lookup table)
-- **LZW compression**: O(n) where n = pixel count per frame
-
-## Memory Usage
-
-Each animation uses:
-- Per frame: `width × height × 4` bytes (RGBA)
-- Total: `width × height × 4 × numFrames` bytes
-
-Example: A 128×128 animation with 30 frames uses ~2 MB
-
-## Limitations
-
-- Maximum frames: 1000
-- Maximum dimensions: 4096×4096
-- Color depth: 8-bit (256 colors)
-- No transparency support in current implementation
-- GIF decoding (`AnimatedImage.open()`) not yet implemented
-
-## Future Enhancements
-
-Potential improvements:
-- GIF decoding support
-- Transparency support
-- Optimized LZW compression
-- Frame disposal methods
-- Local color tables per frame
-- APNG (Animated PNG) support
-- Video codec support (WebM, MP4)
-
-## Integration with Image Library
-
-Since frames are `Image` objects, all `Image` methods work:
-
-```lua
-local anim = AnimatedImage.new(100, 100, 10)
-local logo = Image.open("/home/logo.png")
-
-for i = 1, 10 do
- -- Use Image methods on each frame
- anim.frames[i]:fill("FFFFFF")
- anim.frames[i]:addImage(logo, 10 + i*5, 10 + i*5, 50, 50, 0.8)
- anim.frames[i]:drawLine(0, 0, 99, 99, "FF0000")
-end
-
-anim:saveAsGIF("/home/animated_logo.gif")
-```
-
-## Error Handling
-
-```lua
-local anim, err = AnimatedImage.new(128, 128, 30)
-if not anim then
- print("Error: " .. err)
-end
-
-local success, err = anim:saveAsGIF("/invalid/path.gif")
-if not success then
- print("Save failed: " .. err)
-end
-```
-
-## API Summary
-
-**Creation:**
-- `AnimatedImage.new(width, height, numFrames, delay)`
-- `AnimatedImage.open(path)` - Not yet implemented
-
-**Frame Access:**
-- `anim.frames[index]` - Direct array access
-- `anim:getFrame(index)`
-- `anim:setFrame(index, image)`
-
-**Properties:**
-- `anim.width`, `anim.height`, `anim.numFrames`
-- `anim.delay` - Frame delay in centiseconds
-- `anim.loop` - Boolean for infinite looping
-
-**Utilities:**
-- `anim:fillAll(color)`
-- `anim:clone()`
-
-**Export:**
-- `anim:saveAsGIF(path, options)`
-
-The AnimatedImage library provides a complete solution for creating animated GIFs in LuajitOS!
diff --git a/APP_DEVELOPMENT_GUIDE.md b/APP_DEVELOPMENT_GUIDE.md
@@ -1,609 +0,0 @@
-# LuajitOS Application Development Guide
-
-## Overview
-LuajitOS is a bare-metal operating system built on LuaJIT with a sandboxed application model. Applications run in isolated environments with explicit permissions and restricted filesystem access.
-
-## Application Structure
-
-### Directory Layout
-```
-/apps/com.yourname.appname/
-├── manifest.lua # App metadata and permissions
-├── src/
-│ └── init.lua # Entry point (or custom file specified in manifest)
-├── data/ # App-specific data storage
-├── tmp/ # Temporary files
-└── settings/ # User settings
-```
-
-### Manifest File (manifest.lua)
-```lua
-return {
- name = "appname", -- Display name
- developer = "yourname", -- Developer identifier
- version = "1.0.0", -- Semantic version
- category = "utility", -- Category for app launcher
- description = "Brief description", -- User-facing description
- entry = "init.lua", -- Entry point (relative to $/src/)
- mode = "gui", -- "gui" or "cli"
- permissions = { -- Required permissions (see below)
- "draw",
- "filesystem"
- },
- allowedPaths = { -- Filesystem access patterns
- "$/data/*", -- App's data directory
- "$/tmp/*", -- App's temp directory
- "/tmp/*" -- System temp directory
- }
-}
-```
-
-**Important Notes:**
-- Entry path is ALWAYS relative to `$/src/` directory
-- Use `init.lua` as the default entry point
-- `$` represents the app's root directory (`/apps/com.yourname.appname`)
-
-## Permissions System
-
-Applications must declare required permissions in their manifest. The sandbox enforces these at runtime.
-
-### Available Permissions
-
-**Core Permissions:**
-- `"draw"` - Graphics API access (VESADrawPixel, VESAFillRect, etc.)
-- `"filesystem"` - File system operations via SafeFS
-- `"network"` - Network stack access (TCP, HTTP)
-- `"run"` - Launch other applications via `run(appname)`
-- `"import"` - Import data from other apps via `apps.appname.exportedData`
-- `"export"` - Export data to other apps via `apps.exportData(data)`
-
-**Advanced Permissions:**
-- `"system-all"` - Access to `sys` object (app management, screen info)
-- `"ramdisk"` - Direct ramdisk access (CRamdisk* functions)
-- `"scheduling"` - Process scheduling control
-- `"crypto"` - Cryptographic operations
-- `"admin"` - Runtime permission and path modification (ADMIN_AppAddPermission, ADMIN_AppAddPath)
-
-### Permission Security Model
-- **Principle of Least Privilege**: Only request permissions you actually need
-- **No Silent Escalation**: Users see all requested permissions before installation
-- **Runtime Enforcement**: Sandbox blocks access to unpermitted APIs
-- **No Ambient Authority**: Each permission must be explicitly declared
-
-## Filesystem API (SafeFS)
-
-SafeFS provides sandboxed filesystem access with path-based restrictions.
-
-### Sandbox Environment
-Apps with `"filesystem"` permission receive a `fs` object:
-
-```lua
--- Read file
-local content, err = fs:read("/tmp/myfile.txt")
-if not content then
- print("Error: " .. err)
-end
-
--- Write file
-local success, err = fs:write("$/data/save.dat", data)
-
--- List files
-local files = fs:files("$/data")
-for _, filename in ipairs(files) do
- print(filename)
-end
-
--- List directories
-local dirs = fs:dirs("$/data")
-
--- Check existence
-if fs:exists("$/data/config.json") then
- -- File exists
-end
-
--- Delete file
-fs:delete("$/tmp/temp.txt")
-
--- Get/set current working directory
-local cwd = fs:getCWD() -- Returns current directory
-fs:setCWD("$/data") -- Change to app's data directory
-```
-
-### Path Resolution
-- **Absolute paths**: Start with `/` (e.g., `/tmp/file.txt`)
-- **Relative paths**: Resolved from current working directory
-- **App-relative paths**: `$` expands to `/apps/com.yourname.appname`
- - `$/data/file.txt` → `/apps/com.yourname.appname/data/file.txt`
- - `$/src/lib.lua` → `/apps/com.yourname.appname/src/lib.lua`
-
-### AllowedPaths Security
-The `allowedPaths` array in manifest uses glob patterns:
-
-```lua
-allowedPaths = {
- "$/data/*", -- All files in app's data directory
- "$/tmp/*", -- App's temporary files
- "/tmp/*", -- System-wide temp directory
- "/public/*", -- Shared public files
- "/os/public/res/*" -- Read-only system resources
-}
-```
-
-**Pattern Matching:**
-- `*` matches any file/directory at that level
-- `/*` requires exact path match
-- Parent directory access (../) only allowed if parent contains allowed subdirectory
-
-**Security Best Practices:**
-- **Never use** `"/*"` (full filesystem access) unless absolutely necessary
-- Use `$/data/*` for app-specific storage
-- Use `$/tmp/*` for temporary files
-- Request minimal path access needed for functionality
-
-## Graphics API (GUI Applications)
-
-Apps with `"draw"` permission can create windows and render graphics.
-
-### Creating Windows
-```lua
--- Access Application API (available in sandbox with any permission)
-local window = app:newWindow(x, y, width, height)
-
--- Width/height are CONTENT AREA dimensions (excluding borders/titlebar)
--- Get full dimensions including chrome:
-local totalWidth = window:getTotalWidth()
-local totalHeight = window:getTotalHeight()
-
--- Window properties
-window.title = "My Application"
-window.resizable = true
-window.isBorderless = false
-window.noTaskbar = false -- Show in taskbar
-
--- Visibility control
-window:show()
-window:hide()
-window:close()
-```
-
-### Drawing API
-The `gfx` object is passed to your draw callback:
-
-```lua
-window.onDraw = function(gfx)
- -- Fill rectangle (x, y, width, height, color)
- gfx:fillRect(0, 0, 400, 300, 0x000000) -- Black background
-
- -- Draw hollow rectangle
- gfx:drawRect(10, 10, 100, 50, 0xFF0000) -- Red border
-
- -- Draw text (x, y, text, color)
- gfx:drawText(20, 30, "Hello World", 0xFFFFFF) -- White text
-
- -- Mark window for redraw when state changes
- window:markDirty()
-end
-```
-
-**Colors:** 24-bit RGB in hex format `0xRRGGBB`
-- `0x000000` = Black
-- `0xFFFFFF` = White
-- `0xFF0000` = Red
-- `0x00FF00` = Green
-- `0x0000FF` = Blue
-
-### Window Events
-```lua
--- Mouse click (coordinates relative to content area)
-window.onClick = function(mx, my)
- print("Clicked at: " .. mx .. ", " .. my)
-end
-
--- Window lifecycle
-window.onOpen = function()
- -- Called when window opens
-end
-
-window.onClose = function()
- -- Return true to cancel close
- return false -- Allow close
-end
-
-window.onFocus = function()
- -- Window gained focus
-end
-
-window.onFocusLost = function()
- -- Window lost focus
-end
-
--- Drag events
-window.onDragStart = function(x, y)
- -- User started dragging window
-end
-
-window.onDragEnd = function(x, y)
- -- Drag completed
-end
-
--- Resize events (if window.resizable = true)
-window.onResize = function(newWidth, newHeight)
- -- Window was resized
-end
-```
-
-## Running Applications
-
-### Launching Apps
-Apps with `"run"` permission can launch other apps:
-
-```lua
--- Launch another app
-local success, app_or_error = pcall(run, "com.luajitos.calculator")
-if success then
- print("App launched successfully")
-else
- print("Launch failed: " .. tostring(app_or_error))
-end
-```
-
-### App Communication (Import/Export)
-
-**Exporting Data:**
-```lua
--- App with "export" permission
-apps.exportData({
- version = "1.0",
- settings = { theme = "dark" }
-})
-```
-
-**Importing Data:**
-```lua
--- App with "import" permission
-if apps["com.luajitos.settings"] then
- local data = apps["com.luajitos.settings"].exportedData
- print("Theme: " .. data.settings.theme)
-end
-```
-
-## Admin API (Runtime Permission Management)
-
-Apps with `"admin"` permission can modify permissions and paths of running applications at runtime. This is a powerful capability that should only be granted to trusted system utilities.
-
-### Available Admin Functions
-
-**ADMIN_AppAddPermission(pid, permission)**
-```lua
--- Add a permission to a running app
-local targetPid = 12345
-ADMIN_AppAddPermission(targetPid, "network")
-print("Added network permission to PID " .. targetPid)
-
--- The app now has the permission, but cannot use new APIs until restarted
--- This is primarily useful for persistent permission changes
-```
-
-**ADMIN_AppAddPath(pid, path)**
-```lua
--- Add an allowed path to a running app
-local targetPid = 12345
-ADMIN_AppAddPath(targetPid, "/tmp/*")
-print("Added /tmp/* access to PID " .. targetPid)
-
--- If the app has filesystem permission, the SafeFS instance is updated immediately
-```
-
-**ADMIN_StartPrompt(window)**
-```lua
--- Enter exclusive prompt mode
--- Only the specified window will draw and receive events
--- ALL other apps are frozen (even their interrupt handlers!)
-local promptWindow = app:newWindow(262, 234, 500, 300)
-promptWindow.title = "Password Required"
-
-promptWindow.onDraw = function(gfx)
- gfx:fillRect(0, 0, 500, 300, 0x000080)
- gfx:drawText(10, 10, "Enter password:", 0xFFFFFF)
- -- ... draw prompt UI
-end
-
-promptWindow.onInput = function(key, scancode)
- -- Handle password entry
- if scancode == 28 then -- Enter
- ADMIN_FinishPrompt() -- Exit prompt mode
- promptWindow:close()
- end
-end
-
-ADMIN_StartPrompt(promptWindow) -- Freeze all other apps
-```
-
-**ADMIN_FinishPrompt()**
-```lua
--- Exit exclusive prompt mode
--- Re-enables all applications to draw and receive events
-ADMIN_FinishPrompt()
-
--- All windows are marked dirty and will redraw
-```
-
-### Admin Permission Requirements
-
-To use admin functions, your app must:
-1. Request `"admin"` permission in manifest
-2. Usually also request `"system-all"` to list running apps
-
-```lua
-permissions = {
- "admin",
- "system-all"
-}
-```
-
-### Example: Permission Manager App
-
-```lua
--- List all running apps and their permissions
-for pid, app in pairs(sys.applications) do
- print("PID " .. pid .. ": " .. app.appName)
- if app.permissions then
- print(" Permissions: " .. table.concat(app.permissions, ", "))
- end
-end
-
--- Grant network permission to a specific app
-local targetPid = 39082 -- Shell app PID
-ADMIN_AppAddPermission(targetPid, "network")
-ADMIN_AppAddPath(targetPid, "/home/*")
-
-print("Permissions updated for PID " .. targetPid)
-```
-
-**Security Warning:** The `"admin"` permission grants the ability to escalate privileges of any running application. Only system-critical applications should request this permission.
-
-## Network API
-
-Apps with `"network"` permission can access the network stack.
-
-### SafeHTTP (Recommended)
-SafeHTTP provides sandboxed HTTP with automatic safety checks:
-
-```lua
-local SafeHTTP = require("SafeHTTP")
-
--- GET request
-local response, err = SafeHTTP.get("http://example.com/api/data")
-if response then
- print("Status: " .. response.status)
- print("Body: " .. response.body)
-end
-
--- POST request
-local response, err = SafeHTTP.post("http://example.com/api/submit", {
- headers = { ["Content-Type"] = "application/json" },
- body = '{"key": "value"}'
-})
-```
-
-**SafeHTTP Security Features:**
-- Validates URLs and prevents malformed requests
-- Enforces timeouts to prevent hanging
-- Blocks dangerous redirects
-- Sanitizes headers
-
-## Sandbox Environment
-
-### Available Global Functions
-```lua
--- Standard Lua
-print, pairs, ipairs, next, tostring, tonumber, type
-table, string, math, os.time, os.date, os.clock
-
--- LuajitOS Specific
-app -- Application API (window management)
-fs -- Filesystem (with "filesystem" permission)
-run -- Launch apps (with "run" permission)
-apps -- App communication (with "import"/"export")
-sys -- System API (with "system-all" permission)
-crypto -- Cryptography (with "crypto" permission)
-ADMIN_AppAddPermission -- Add permission to app (with "admin" permission)
-ADMIN_AppAddPath -- Add allowed path to app (with "admin" permission)
-ADMIN_StartPrompt -- Enter exclusive prompt mode (with "admin" permission)
-ADMIN_FinishPrompt -- Exit exclusive prompt mode (with "admin" permission)
-
--- Utilities
-bit -- Bitwise operations (bit.band, bit.bor, etc.)
-osprint -- Debug output to serial console
-```
-
-### Restricted Functions
-The sandbox BLOCKS access to:
-- `load`, `loadfile`, `dofile` (arbitrary code execution)
-- `getfenv`, `setfenv` (environment manipulation)
-- `rawget`, `rawequal` (bypassing metatables)
-- `_G` (global environment access)
-- Direct file I/O (`io.*`) - use SafeFS instead
-- Unrestricted ramdisk access - use SafeFS or request "ramdisk" permission
-
-### Error Handling
-Accessing undefined globals throws an error:
-```lua
--- This will error: "Attempt to access undefined global: _G"
-local env = _G
-
--- This will error if you don't have "network" permission
-local socket = Socket.new() -- Error: Socket is undefined
-```
-
-## Security Best Practices
-
-### 1. Validate All Input
-```lua
-window.onClick = function(mx, my)
- -- Validate coordinates before use
- if mx < 0 or my < 0 or mx >= width or my >= height then
- return
- end
- -- Safe to process click
-end
-```
-
-### 2. Minimize Permissions
-Request only what you need:
-```lua
--- Bad: Requesting unnecessary permissions
-permissions = { "filesystem", "network", "ramdisk", "system-all" }
-
--- Good: Only what's needed
-permissions = { "draw" }
-```
-
-### 3. Restrict Filesystem Access
-```lua
--- Bad: Broad filesystem access
-allowedPaths = { "/*" }
-
--- Good: Specific directories
-allowedPaths = { "$/data/*", "$/tmp/*" }
-```
-
-### 4. Handle Errors Gracefully
-```lua
--- Always check for errors from I/O operations
-local content, err = fs:read("$/data/config.json")
-if not content then
- print("Failed to read config: " .. err)
- -- Provide defaults or fail gracefully
- return
-end
-```
-
-### 5. Use pcall for External Operations
-```lua
--- Wrap potentially failing operations
-local success, result = pcall(function()
- return fs:read("/tmp/data.txt")
-end)
-
-if not success then
- print("Operation failed: " .. tostring(result))
-end
-```
-
-## Example Application
-
-```lua
--- manifest.lua
-return {
- name = "notepad",
- developer = "myname",
- version = "1.0.0",
- category = "productivity",
- description = "Simple text editor",
- entry = "init.lua",
- mode = "gui",
- permissions = { "draw", "filesystem" },
- allowedPaths = { "$/data/*" }
-}
-```
-
-```lua
--- src/init.lua
-local text = ""
-local filename = "$/data/note.txt"
-
--- Load existing note
-local content = fs:read(filename)
-if content then
- text = content
-end
-
--- Create window
-local window = app:newWindow(400, 300)
-window.title = "Notepad"
-
--- Draw function
-window.onDraw = function(gfx)
- gfx:fillRect(0, 0, 400, 300, 0xFFFFFF)
- gfx:drawText(10, 10, text, 0x000000)
-end
-
--- Save on close
-window.onClose = function()
- local success, err = fs:write(filename, text)
- if not success then
- print("Failed to save: " .. err)
- end
- return false -- Allow close
-end
-
-print("Notepad loaded")
-```
-
-## Debugging
-
-### Serial Console Output
-Use `osprint()` for debugging (output goes to serial console):
-```lua
-osprint("Debug: variable = " .. tostring(myvar) .. "\n")
-```
-
-### Common Issues
-
-**"Attempt to access undefined global"**
-- Missing permission for that API
-- Typo in variable name
-- Add required permission to manifest
-
-**"Error: Entry file not found"**
-- Check `entry` path in manifest (should be relative to `$/src/`)
-- Verify file exists in correct location
-
-**"Access denied" from SafeFS**
-- Path not in `allowedPaths`
-- Add required path pattern to manifest
-
-## Summary Checklist
-
-Before deploying your app:
-- [ ] Minimal permissions requested
-- [ ] Specific filesystem paths in allowedPaths
-- [ ] All user input validated
-- [ ] Errors handled gracefully
-- [ ] No access to restricted globals
-- [ ] Testing with actual permission constraints
-- [ ] Manifest metadata complete
-- [ ] Entry path relative to `$/src/`
-
-## API Quick Reference
-
-### Window Methods
-- `app:newWindow(x, y, width, height)` - Create window
-- `window:show()`, `window:hide()`, `window:close()`
-- `window:markDirty()` - Request redraw
-- `window:getTotalWidth()`, `window:getTotalHeight()`
-
-### Graphics Methods (gfx)
-- `gfx:fillRect(x, y, w, h, color)`
-- `gfx:drawRect(x, y, w, h, color)`
-- `gfx:drawText(x, y, text, color)`
-
-### Filesystem Methods (fs)
-- `fs:read(path)` → content, error
-- `fs:write(path, content)` → success, error
-- `fs:exists(path)` → boolean
-- `fs:delete(path)` → success, error
-- `fs:files(directory)` → array
-- `fs:dirs(directory)` → array
-- `fs:getCWD()` → path
-- `fs:setCWD(path)` → success, error
-
-### System Methods (sys - requires "system-all")
-- `sys.screen[1].width`, `sys.screen[1].height`
-- `sys.applications` - Table of running apps
-- `sys.addHotkeyString(key, callback)`
-
----
-
-**Remember:** Security is paramount. Always code with the assumption that your app runs in a hostile environment alongside untrusted applications. The sandbox protects the system and other apps from bugs and malicious behavior in your code.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,3 +0,0 @@
-- i want you to always think about the security implications of what you are doing
-- never use bitwise operators use the bit library!
-- alway check the actual poutput for GPF's
-\ No newline at end of file
diff --git a/COMPRESSION_IMPLEMENTATION.md b/COMPRESSION_IMPLEMENTATION.md
@@ -1,354 +0,0 @@
-# Compression Implementation Summary
-
-## What Was Implemented
-
-### Full Deflate/Zlib Compression ✅
-
-Implemented a complete deflate compression algorithm from scratch:
-
-#### Core Components:
-
-1. **deflate_impl.c** (~500 lines)
- - LZ77 sliding window compression
- - Fixed Huffman coding (RFC 1951)
- - Bit-level packing/unpacking
- - Compression and decompression
-
-2. **Deflate.c** (Updated)
- - Zlib wrapper (header + Adler-32)
- - Integrates deflate_impl for actual compression
- - Lua bindings: `DeflateCompress()`, `DeflateDecompress()`
-
-3. **GZip.c** (Updated)
- - Gzip wrapper (header + CRC32)
- - Uses deflate_impl internally
- - Lua bindings: `GZipCompress()`, `GZipDecompress()`
-
-### PNG Decoder Integration ✅
-
-Updated PNG decoder to use the new compression:
-
-1. **decoder_PNG.c** (Updated)
- - Accumulates IDAT chunks
- - Decompresses using deflate
- - Converts PNG scanlines to RGB/RGBA
- - Supports RGB, RGBA, Grayscale formats
-
-### Technical Details
-
-#### Deflate Algorithm
-
-**Compression Process:**
-1. Find repeated patterns using LZ77 (3-258 byte matches in 32KB window)
-2. Encode as literals or length/distance pairs
-3. Apply fixed Huffman coding
-4. Pack bits efficiently
-
-**Decompression Process:**
-1. Read Huffman-coded symbols
-2. Decode literals directly
-3. Decode length/distance pairs
-4. Copy from history buffer
-5. Build output stream
-
-#### Huffman Coding
-
-Uses **fixed Huffman trees** as defined in RFC 1951:
-- Literals 0-143: 8 bits (codes 00110000-10111111)
-- Literals 144-255: 9 bits (codes 110010000-111111111)
-- Literals 256-279: 7 bits (codes 0000000-0010111)
-- Literals 280-287: 8 bits (codes 11000000-11000111)
-- Distances 0-29: 5 bits (codes 00000-11101)
-
-#### Data Structures
-
-```c
-/* Bit buffer for output */
-typedef struct {
- uint8_t* buffer;
- uint32_t byte_pos;
- uint32_t bit_pos;
-} bit_buffer_t;
-
-/* Huffman code */
-typedef struct {
- uint16_t code;
- uint8_t length;
-} huffman_code_t;
-```
-
-### File Structure
-
-```
-compression/
-├── compression.h # Common structures, error codes
-├── compression.c # Adler-32, CRC32, Lua bindings
-├── deflate_impl.h # Deflate algorithm interface
-├── deflate_impl.c # Core deflate implementation ⭐ NEW
-├── Deflate.c # Zlib wrapper (updated)
-├── LZMA.c # LZMA framework (unchanged)
-└── GZip.c # Gzip wrapper (updated)
-```
-
-### Build System
-
-Updated `build.sh`:
-```bash
-# Compile deflate implementation
-${CC} -c compression/deflate_impl.c -o build/deflate_impl.o
-
-# Link all compression modules
-${LD} ... build/deflate_impl.o build/Deflate.o build/LZMA.o build/GZip.o ...
-```
-
-## Usage Examples
-
-### Compress and Decompress
-
-```lua
--- Compress text
-local text = "Hello, World! " .. string.rep("ABCDEFGH", 100)
-print("Original: " .. #text .. " bytes")
-
-local compressed = DeflateCompress(text, 6)
-if compressed then
- print("Compressed: " .. #compressed .. " bytes")
- print("Ratio: " .. string.format("%.1f%%", (#compressed / #text) * 100))
-
- local decompressed = DeflateDecompress(compressed)
- if decompressed == text then
- print("Success! Data matches.")
- end
-end
-```
-
-### Load PNG Image
-
-```lua
--- Load PNG using deflate decompression
-local png_data = read_file("/images/photo.png")
-local img = PNGLoad(png_data)
-
-if img then
- print("PNG loaded successfully!")
- ImageDraw(img, 0, 0)
- ImageDestroy(img)
-end
-```
-
-### GZip Files
-
-```lua
--- Create gzip file
-local data = read_file("/data/large.txt")
-local gzipped = GZipCompress(data, 9)
-
-if gzipped then
- write_file("/data/large.txt.gz", gzipped)
- print("Saved gzip file")
-end
-```
-
-### Checksums
-
-```lua
--- Verify file integrity
-local file_data = read_file("/important/data.bin")
-local checksum = CRC32(file_data)
-
-print(string.format("CRC32: 0x%08X", checksum))
-
--- Later, verify
-local loaded_data = read_file("/important/data.bin")
-if CRC32(loaded_data) == checksum then
- print("File verified OK")
-else
- print("WARNING: File corrupted!")
-end
-```
-
-## Performance Characteristics
-
-### Compression Speed
-- **Fast**: Simple LZ77 matching
-- **No complex hashing**: Brute force search
-- **Good for small files**: <100KB optimal
-- **Reasonable ratio**: 40-60% typical
-
-### Decompression Speed
-- **Very fast**: Linear scan through data
-- **Low memory**: Only needs output buffer
-- **No lookups**: Direct Huffman decoding
-
-### Memory Usage
-- **Compression**: ~50KB (sliding window + output buffer)
-- **Decompression**: 2-4x output size estimate
-- **No global state**: Reentrant
-
-## Testing
-
-### Test Compression
-
-```lua
--- Test various data types
-local tests = {
- text = "The quick brown fox jumps over the lazy dog",
- repeated = string.rep("A", 1000),
- binary = string.char(0x00, 0xFF, 0xAA, 0x55),
- mixed = "ABC" .. string.rep("XYZ", 50) .. "123"
-}
-
-for name, data in pairs(tests) do
- local compressed = DeflateCompress(data)
- local decompressed = DeflateDecompress(compressed)
-
- if decompressed == data then
- local ratio = (#compressed / #data) * 100
- print(string.format("%s: %.1f%% OK", name, ratio))
- else
- print(name .. ": FAILED")
- end
-end
-```
-
-### Test PNG Loading
-
-```lua
--- Test PNG decoder
-local test_pngs = {
- "/images/rgb.png",
- "/images/rgba_alpha.png",
- "/images/grayscale.png"
-}
-
-for _, path in ipairs(test_pngs) do
- local data = read_file(path)
- local img = PNGLoad(data)
-
- if img then
- local info = ImageGetInfo(img)
- print(path .. ": " .. info.width .. "x" .. info.height .. " OK")
- ImageDestroy(img)
- else
- print(path .. ": FAILED")
- end
-end
-```
-
-## Comparison to Libraries
-
-### vs. miniz
-| Feature | Our Implementation | miniz |
-|---------|-------------------|-------|
-| Size | ~500 lines | ~8000 lines |
-| Compression | Fixed Huffman | Dynamic + Fixed |
-| Speed | Fast | Faster |
-| Ratio | Good | Better |
-| Dependencies | None | None |
-
-### vs. zlib
-| Feature | Our Implementation | zlib |
-|---------|-------------------|-------|
-| Size | ~500 lines | ~20000 lines |
-| Features | Basic deflate | Full deflate + gzip + zlib |
-| Speed | Fast | Faster |
-| Memory | Low | Configurable |
-| Standard | Yes (RFC 1951) | Yes (reference) |
-
-## Advantages
-
-1. **Self-Contained**: No external dependencies
-2. **Small**: ~500 lines of core compression code
-3. **Educational**: Easy to understand and modify
-4. **Working**: Real compression with size reduction
-5. **Standard**: RFC 1951 compliant
-6. **Integrated**: Works with PNG decoder
-
-## Future Improvements
-
-### Dynamic Huffman Trees
-Currently uses fixed trees. Dynamic trees would improve compression ratio by 10-30%.
-
-### Better Matching
-Use hash chains or binary search trees instead of brute force:
-```c
-// Current: O(n²) brute force
-for (uint32_t i = window_start; i < pos; i++) {
- // Check match
-}
-
-// Better: O(n) with hash chain
-hash = hash_func(data, pos);
-for (match = hash_table[hash]; match; match = match->next) {
- // Check match
-}
-```
-
-### Compression Levels
-Implement multiple levels:
-- **Level 1**: No LZ77, only Huffman
-- **Level 6**: Current implementation
-- **Level 9**: Extended search, lazy matching
-
-### Lazy Matching
-Don't encode first match - look ahead one byte for better match:
-```c
-if (current_match_len >= 3) {
- next_match = find_match(pos + 1);
- if (next_match_len > current_match_len + 1) {
- // Use next match instead
- }
-}
-```
-
-## References
-
-- **RFC 1951**: DEFLATE Compressed Data Format Specification
-- **RFC 1950**: ZLIB Compressed Data Format Specification
-- **RFC 1952**: GZIP File Format Specification
-- **PNG Spec**: https://www.w3.org/TR/PNG/
-
-## Integration Notes
-
-### Using Compression in Other Code
-
-```c
-#include "compression/compression.h"
-
-// Compress
-compression_result_t* result = deflate_compress(data, size, 6);
-if (result->error == COMPRESS_OK) {
- // Use result->data, result->size
-}
-compression_result_destroy(result);
-
-// Decompress
-compression_result_t* result = deflate_decompress(compressed, compressed_size);
-if (result->error == COMPRESS_OK) {
- // Use result->data, result->size
-}
-compression_result_destroy(result);
-```
-
-### Adding New Compression Formats
-
-Follow this pattern:
-1. Create `compression/NewFormat.c`
-2. Implement compress/decompress using `deflate_impl.h`
-3. Add wrapper with format-specific headers
-4. Create Lua bindings
-5. Register in kernel.c
-6. Update build.sh
-
-## Conclusion
-
-We've implemented a **complete, working compression system** from scratch:
-
-✅ Full deflate/zlib with Huffman coding
-✅ GZip wrapper
-✅ PNG image support
-✅ Checksums (Adler-32, CRC32)
-✅ Lua bindings
-✅ Real compression with size reduction
-
-The system is production-ready for basic use and can be enhanced with dynamic Huffman trees and better matching algorithms for improved compression ratios.
diff --git a/COMPRESSION_README.md b/COMPRESSION_README.md
@@ -1,558 +0,0 @@
-# Compression System
-
-LuajitOS now includes a comprehensive compression system with support for multiple compression algorithms.
-
-## Features
-
-### Supported Formats
-
-#### Deflate/Zlib (Fully Implemented ✅)
-- **Full Huffman coding** with LZ77 compression
-- Fixed Huffman trees (RFC 1951)
-- Zlib header and Adler-32 checksum
-- **Working compression and decompression**
-
-#### LZMA (Framework Ready ⚠️)
-- LZMA header structure implemented
-- Uncompressed storage (placeholder)
-- **Requires LZMA SDK** for full compression
-
-#### GZip (Fully Implemented ✅)
-- **Full Huffman coding** via deflate
-- GZip header and footer with CRC32
-- **Working compression and decompression**
-
-### Checksum Utilities ✅
-
-- **Adler-32**: Used by zlib format
-- **CRC32**: Used by gzip format
-
-## API Reference
-
-### Deflate/Zlib Compression
-
-```lua
--- Compress data with deflate (zlib format)
-local compressed, error = DeflateCompress(data, level)
-if compressed then
- print("Compressed: " .. #data .. " -> " .. #compressed .. " bytes")
-else
- print("Error: " .. error)
-end
-
--- Decompress deflate data
-local decompressed, error = DeflateDecompress(compressed)
-if decompressed then
- print("Decompressed successfully")
-else
- print("Error: " .. error)
-end
-```
-
-**Parameters:**
-- `data`: String containing data to compress
-- `level`: Compression level (1=fastest, 6=default, 9=best) - currently unused in simplified version
-
-**Returns:**
-- Success: compressed/decompressed data (string)
-- Failure: nil, error message (string)
-
-### LZMA Compression
-
-```lua
--- Compress data with LZMA
-local compressed, error = LZMACompress(data, level)
-if compressed then
- print("LZMA compressed: " .. #data .. " -> " .. #compressed .. " bytes")
-else
- print("Error: " .. error)
-end
-
--- Decompress LZMA data
-local decompressed, error = LZMADecompress(compressed)
-if decompressed then
- print("Decompressed successfully")
-else
- print("Error: " .. error)
-end
-```
-
-**Benefits of LZMA:**
-- Excellent compression ratio (better than gzip/bzip2)
-- Good decompression speed
-- Used by 7-Zip and XZ Utils
-- Dictionary size up to 4GB
-
-### GZip Compression
-
-```lua
--- Compress data with GZip
-local compressed, error = GZipCompress(data, level)
-if compressed then
- print("GZip compressed: " .. #data .. " -> " .. #compressed .. " bytes")
-else
- print("Error: " .. error)
-end
-
--- Decompress GZip data
-local decompressed, error = GZipDecompress(compressed)
-if decompressed then
- print("Decompressed successfully")
-else
- print("Error: " .. error)
-end
-```
-
-**Benefits of GZip:**
-- Widely supported (web, curl, gunzip)
-- CRC32 for data integrity
-- File metadata support
-- Streaming capable
-
-### Checksum Functions
-
-```lua
--- Calculate Adler-32 checksum
-local checksum = Adler32(data)
-print(string.format("Adler-32: 0x%08X", checksum))
-
--- Calculate Adler-32 incrementally
-local checksum1 = Adler32(chunk1)
-local checksum2 = Adler32(chunk2, checksum1) -- Continue from previous
-
--- Calculate CRC32 checksum
-local crc = CRC32(data)
-print(string.format("CRC32: 0x%08X", crc))
-
--- Calculate CRC32 incrementally
-local crc1 = CRC32(chunk1)
-local crc2 = CRC32(chunk2, crc1) -- Continue from previous
-```
-
-## Compression Levels
-
-All compression functions accept an optional level parameter:
-
-```lua
-local COMPRESS_LEVEL_FASTEST = 1 -- Fast, larger output
-local COMPRESS_LEVEL_FAST = 3 -- Good balance
-local COMPRESS_LEVEL_DEFAULT = 6 -- Default (if omitted)
-local COMPRESS_LEVEL_BEST = 9 -- Best compression, slower
-```
-
-**Note:** In the simplified implementations, compression level affects only metadata, not actual compression (since they use uncompressed blocks).
-
-## Complete Examples
-
-### Basic Compression
-
-```lua
--- Simple compression example
-local original = "Hello, World! This is a test string for compression."
-
-print("Original size: " .. #original)
-
--- Try deflate
-local compressed = DeflateCompress(original)
-if compressed then
- print("Deflate size: " .. #compressed)
-
- local decompressed = DeflateDecompress(compressed)
- if decompressed == original then
- print("Deflate: Success!")
- else
- print("Deflate: Data mismatch!")
- end
-end
-
--- Try GZip
-local gzipped = GZipCompress(original)
-if gzipped then
- print("GZip size: " .. #gzipped)
-
- local unzipped = GZipDecompress(gzipped)
- if unzipped == original then
- print("GZip: Success!")
- else
- print("GZip: Data mismatch!")
- end
-end
-```
-
-### Checksum Verification
-
-```lua
--- Verify data integrity with checksums
-local data = "Important data that must not be corrupted"
-
--- Calculate checksums
-local adler = Adler32(data)
-local crc = CRC32(data)
-
-print(string.format("Adler-32: 0x%08X", adler))
-print(string.format("CRC32: 0x%08X", crc))
-
--- Later, verify the data
-local data_received = receive_data()
-local adler_check = Adler32(data_received)
-local crc_check = CRC32(data_received)
-
-if adler_check == adler and crc_check == crc then
- print("Data verified: OK")
-else
- print("Data corrupted!")
-end
-```
-
-### Compression Comparison
-
-```lua
--- Compare different compression algorithms
-local data = string.rep("ABCDEFGHIJKLMNOPQRSTUVWXYZ", 100) -- 2600 bytes
-
-print("Original size: " .. #data)
-print("")
-
--- Test Deflate
-local deflate_compressed = DeflateCompress(data, 9)
-if deflate_compressed then
- print("Deflate:")
- print(" Compressed: " .. #deflate_compressed .. " bytes")
- print(" Ratio: " .. string.format("%.1f%%", (#deflate_compressed / #data) * 100))
-end
-
--- Test LZMA
-local lzma_compressed = LZMACompress(data, 9)
-if lzma_compressed then
- print("LZMA:")
- print(" Compressed: " .. #lzma_compressed .. " bytes")
- print(" Ratio: " .. string.format("%.1f%%", (#lzma_compressed / #data) * 100))
-end
-
--- Test GZip
-local gzip_compressed = GZipCompress(data, 9)
-if gzip_compressed then
- print("GZip:")
- print(" Compressed: " .. #gzip_compressed .. " bytes")
- print(" Ratio: " .. string.format("%.1f%%", (#gzip_compressed / #data) * 100))
-end
-```
-
-### Stream Processing
-
-```lua
--- Process large data in chunks with checksums
-function compress_stream(read_chunk_func, write_chunk_func)
- local adler = 1 -- Initial Adler-32 value
- local total_size = 0
-
- while true do
- local chunk = read_chunk_func()
- if not chunk or #chunk == 0 then break end
-
- -- Update checksum
- adler = Adler32(chunk, adler)
- total_size = total_size + #chunk
-
- -- Compress and write
- local compressed = DeflateCompress(chunk)
- if compressed then
- write_chunk_func(compressed)
- end
- end
-
- print("Processed " .. total_size .. " bytes")
- print(string.format("Checksum: 0x%08X", adler))
-end
-```
-
-## Current Capabilities
-
-### Fully Implemented ✅
-
-1. **Deflate/Zlib**: Complete implementation with Huffman coding
- - LZ77 sliding window matching
- - Fixed Huffman trees (RFC 1951 compliant)
- - Proper zlib wrapper with Adler-32
- - **Real compression with size reduction**
-
-2. **GZip**: Full gzip format support
- - Uses deflate compression internally
- - CRC32 integrity checking
- - Gzip headers and metadata
- - **Real compression with size reduction**
-
-3. **PNG Images**: Now working! ✅
- - Deflate decompression for IDAT chunks
- - RGB, RGBA, Grayscale support
- - 8-bit depth images
-
-### Simplified Implementations ⚠️
-
-1. **LZMA**: Framework with uncompressed storage
- - Valid header structure
- - No actual compression yet
- - Integrate LZMA SDK for full support
-
-### What This Means
-
-The compression system now provides:
-- ✅ **Real compression** - Files actually get smaller!
-- ✅ **Proper decompression** - Can read standard deflate/gzip files
-- ✅ **PNG support** - Can load and display PNG images
-- ✅ **Industry standard** - RFC 1951 compliant deflate
-- ✅ **Data integrity** - Adler-32 and CRC32 checksums
-
-## Implementation Details
-
-### Deflate Algorithm
-
-The implementation includes:
-- **LZ77 Compression**: Sliding window of 32KB, matches of 3-258 bytes
-- **Fixed Huffman Trees**: Pre-defined codes for literals, lengths, and distances
-- **Bit-level Output**: Efficient bit packing for compressed data
-- **Proper Formatting**: RFC 1951 compliant deflate streams
-
-### Performance
-
-Current implementation:
-- **Fast compression**: Optimized for speed over ratio
-- **Good decompression**: Handles all fixed Huffman blocks
-- **Small code size**: ~500 lines of core deflate logic
-- **No dependencies**: Pure C implementation
-
-### Future Enhancements
-
-To further improve compression:
-
-1. **Dynamic Huffman Trees**: Currently uses fixed trees; dynamic trees would improve compression ratio
-2. **Better LZ77 Matching**: Hash chains or binary search trees for faster match finding
-3. **Compression Levels**: Currently one level; add fast/normal/best modes
-4. **Lazy Matching**: Defer matches to find better ones
-
-Or integrate existing libraries:
-
-### Option 2: LZMA SDK
-
-**For full LZMA compression:**
-
-1. Download LZMA SDK from https://www.7-zip.org/sdk.html
-2. Add files to project:
- ```
- compression/LzmaDec.c
- compression/LzmaEnc.c
- compression/LzFind.c
- compression/LzmaDec.h
- compression/LzmaEnc.h
- ```
-
-3. Update `compression/LZMA.c` with SDK functions (see integration notes in LZMA.c)
-
-4. Update `build.sh` to compile all LZMA SDK files
-
-**Benefits:**
-- Official implementation
-- Excellent compression ratios
-- Public domain
-
-### Option 3: Full zlib
-
-**Standard library approach:**
-
-1. Cross-compile zlib for i686:
- ```bash
- wget https://zlib.net/zlib-1.3.tar.gz
- tar -xzf zlib-1.3.tar.gz
- cd zlib-1.3
- CFLAGS="-m32" ./configure --static
- make
- ```
-
-2. Link with zlib:
- ```bash
- ${LD} ${LDFLAGS} ... -lz
- ```
-
-3. Use zlib API in compression files (see integration notes in Deflate.c and GZip.c)
-
-## Integration Priority
-
-Recommended integration order:
-
-1. **MINIZ first** - Enables deflate and gzip with minimal effort
-2. **LZMA SDK second** - Adds high-ratio compression
-3. **PNG support** - Use miniz for PNG image decompression (see IMAGE_DECODER_README.md)
-
-## Error Handling
-
-All compression functions return nil + error message on failure:
-
-```lua
-local compressed, error = DeflateCompress(data)
-if not compressed then
- print("Compression failed: " .. error)
- -- Handle error
-end
-```
-
-Common errors:
-- `"Memory allocation failed"` - Out of memory
-- `"Input too small"` - Data too small for format
-- `"Invalid header"` - Corrupted compressed data
-- `"Checksum mismatch"` - Data corrupted during transmission
-- `"Huffman compressed blocks not supported"` - Need library integration
-
-## Use Cases
-
-### File Compression
-
-```lua
--- Compress file data before storing
-local file_data = read_file("/data/large_file.txt")
-local compressed = GZipCompress(file_data, 9)
-
-if compressed then
- write_file("/data/large_file.txt.gz", compressed)
- print("Saved " .. (#file_data - #compressed) .. " bytes")
-end
-```
-
-### Network Data
-
-```lua
--- Compress data before sending over network
-local message = create_large_message()
-local compressed = DeflateCompress(message, 6)
-
-if compressed then
- network_send(compressed)
- print("Sent " .. #compressed .. " bytes instead of " .. #message)
-end
-```
-
-### Data Integrity
-
-```lua
--- Verify data hasn't been corrupted
-local important_data = "Critical system data"
-local checksum = CRC32(important_data)
-
--- Store checksum separately
-save_checksum(checksum)
-
--- Later, verify
-local loaded_data = load_data()
-if CRC32(loaded_data) == checksum then
- print("Data integrity verified")
-else
- print("WARNING: Data corruption detected!")
-end
-```
-
-### PNG Image Support
-
-The compression system enables PNG support:
-
-```lua
--- PNG images require deflate decompression
--- Once miniz is integrated, PNG decoding will work automatically
-
-local png_data = read_file("/images/photo.png")
-local img = PNGLoad(png_data) -- Uses DeflateDecompress internally
-
-if img then
- ImageDraw(img, 0, 0)
- ImageDestroy(img)
-end
-```
-
-## Performance Notes
-
-### Current Implementation
-- **Very fast** - No actual compression, just copying
-- **No size reduction** - Data stays same size (plus headers)
-- **Good for testing** - Validates format structures
-
-### With Full Compression
-- **Deflate**: Fast compression, good ratio (gzip standard)
-- **LZMA**: Slower compression, excellent ratio (7-Zip)
-- **Trade-offs**: Speed vs. compression ratio
-
-### Recommendations
-- **Small data (<1KB)**: Checksums only, compression overhead not worth it
-- **Medium data (1-100KB)**: Deflate with fast level
-- **Large data (>100KB)**: LZMA with best level
-- **Network**: GZip (widely supported)
-- **Archival**: LZMA (best compression)
-
-## Format Comparison
-
-| Format | Header | Checksum | Compression | Best For |
-|--------|--------|----------|-------------|----------|
-| Deflate/Zlib | 2 bytes | Adler-32 | LZ77+Huffman | General purpose, fast |
-| LZMA | 13 bytes | None | LZMA | High compression ratio |
-| GZip | 10+ bytes | CRC32 | Deflate | Web, HTTP, widely supported |
-
-## Files
-
-- `compression/compression.h` - Common structures and declarations
-- `compression/compression.c` - Checksums and utilities
-- `compression/Deflate.c` - Deflate/zlib implementation
-- `compression/LZMA.c` - LZMA implementation
-- `compression/GZip.c` - GZip implementation
-
-## Building
-
-The compression system is automatically built with:
-
-```bash
-./build.sh
-```
-
-Build steps:
-1. Compiles all compression/*.c files
-2. Links compression objects into kernel
-3. Registers Lua bindings globally
-
-## Troubleshooting
-
-### "Huffman compressed blocks not supported"
-- Expected with current implementation
-- Integrate miniz or zlib for full support
-- Only uncompressed blocks work now
-
-### "Checksum mismatch"
-- Data corrupted during transmission/storage
-- File format may be incompatible
-- Ensure complete data was transferred
-
-### Out of memory
-- Compression allocates temporary buffers
-- Reduce data size or free other memory
-- Check available RAM
-
-### Build errors
-- Ensure all compression/*.c files exist
-- Check build.sh includes all compression objects
-- Verify compression/compression.h is included in kernel.c
-
-## Future Enhancements
-
-Potential additions:
-- [ ] Full deflate compression (via miniz)
-- [ ] Full LZMA compression (via SDK)
-- [ ] Bzip2 support
-- [ ] LZ4 (extremely fast)
-- [ ] Zstd (modern, excellent ratio)
-- [ ] Compression benchmarking utility
-- [ ] Streaming compression API
-- [ ] Dictionary training for LZMA
-
-## References
-
-- **DEFLATE**: RFC 1951 - https://www.ietf.org/rfc/rfc1951.txt
-- **ZLIB**: RFC 1950 - https://www.ietf.org/rfc/rfc1950.txt
-- **GZIP**: RFC 1952 - https://www.ietf.org/rfc/rfc1952.txt
-- **MINIZ**: https://github.com/richgel999/miniz
-- **LZMA SDK**: https://www.7-zip.org/sdk.html
-- **PNG Spec**: https://www.w3.org/TR/PNG/ (uses DEFLATE)
diff --git a/C_RAMDISK_README.md b/C_RAMDISK_README.md
@@ -1,505 +0,0 @@
-# C Ramdisk Implementation
-
-This document describes the C-based ramdisk filesystem implementation in LuajitOS. The C ramdisk provides a high-performance in-memory filesystem that runs alongside the original Lua-based ramdisk.
-
-## Architecture
-
-The C ramdisk uses a tree structure with:
-- **Nodes**: Represent files or directories
-- **Directory Entries**: Linked list of children in each directory
-- **File Handles**: Track position and mode for open files
-
-### Data Structures
-
-```c
-// Node types
-typedef enum {
- RAMDISK_FILE = 0,
- RAMDISK_DIR = 1
-} ramdisk_node_type_t;
-
-// Filesystem node (file or directory)
-typedef struct ramdisk_node {
- char* name;
- ramdisk_node_type_t type;
- struct ramdisk_node* parent;
-
- union {
- // For files
- struct {
- uint8_t* data;
- uint32_t size;
- uint32_t capacity;
- } file;
-
- // For directories
- struct {
- ramdisk_dir_entry_t* entries;
- uint32_t entry_count;
- } dir;
- };
-} ramdisk_node_t;
-
-// File handle
-typedef struct {
- ramdisk_node_t* node;
- uint32_t position;
- char mode; // 'r', 'w', 'a'
-} ramdisk_handle_t;
-```
-
-## Lua API
-
-All C ramdisk functions are accessible from Lua with the `CRamdisk` prefix.
-
-### CRamdiskCreate()
-
-Creates a new ramdisk root.
-
-```lua
--- Create a new C ramdisk
-local root = CRamdiskCreate()
-if not root then
- print("Failed to create ramdisk")
-end
-```
-
-**Returns:** Lightuserdata pointer to ramdisk root, or nil on error
-
-### CRamdiskMkdir(root, path)
-
-Creates a directory at the specified path.
-
-```lua
-local root = CRamdiskCreate()
-
--- Create directory
-local success = CRamdiskMkdir(root, "/home")
-if success then
- print("Directory created")
-end
-
--- Create nested directories
-CRamdiskMkdir(root, "/home/user")
-CRamdiskMkdir(root, "/home/user/documents")
-```
-
-**Parameters:**
-- `root`: Ramdisk root (lightuserdata)
-- `path`: Directory path (string)
-
-**Returns:** true on success, false on error
-
-### CRamdiskOpen(root, path, mode)
-
-Opens a file and returns a file handle.
-
-```lua
--- Open file for reading
-local handle = CRamdiskOpen(root, "/home/user/file.txt", "r")
-
--- Open file for writing (creates if doesn't exist)
-local handle = CRamdiskOpen(root, "/home/user/output.txt", "w")
-
--- Open file for appending
-local handle = CRamdiskOpen(root, "/home/user/log.txt", "a")
-```
-
-**Parameters:**
-- `root`: Ramdisk root (lightuserdata)
-- `path`: File path (string)
-- `mode`: Open mode - "r" (read), "w" (write), "a" (append)
-
-**Returns:** File handle (lightuserdata) or nil on error
-
-**Modes:**
-- `"r"`: Read only, file must exist
-- `"w"`: Write, creates file or truncates existing
-- `"a"`: Append, creates file if doesn't exist
-
-### CRamdiskRead(handle, size)
-
-Reads data from an open file handle.
-
-```lua
-local handle = CRamdiskOpen(root, "/home/user/file.txt", "r")
-
--- Read 100 bytes
-local data = CRamdiskRead(handle, 100)
-if data then
- print("Read " .. #data .. " bytes")
-end
-
--- Read entire file (use large size)
-local all_data = CRamdiskRead(handle, 1048576) -- 1MB max
-
-CRamdiskClose(handle)
-```
-
-**Parameters:**
-- `handle`: File handle (lightuserdata)
-- `size`: Maximum bytes to read (number)
-
-**Returns:** String containing data read, or nil at EOF/error
-
-### CRamdiskWrite(handle, data)
-
-Writes data to an open file handle.
-
-```lua
-local handle = CRamdiskOpen(root, "/home/user/output.txt", "w")
-
--- Write string data
-local bytes_written = CRamdiskWrite(handle, "Hello, World!\n")
-print("Wrote " .. bytes_written .. " bytes")
-
--- Write more data
-CRamdiskWrite(handle, "Second line\n")
-
-CRamdiskClose(handle)
-```
-
-**Parameters:**
-- `handle`: File handle (lightuserdata)
-- `data`: String data to write
-
-**Returns:** Number of bytes written, or 0 on error
-
-### CRamdiskSeek(handle, offset, whence)
-
-Moves the file position.
-
-```lua
-local handle = CRamdiskOpen(root, "/home/user/file.txt", "r")
-
--- Seek to beginning
-CRamdiskSeek(handle, 0, 0) -- SEEK_SET
-
--- Seek 10 bytes forward from current position
-CRamdiskSeek(handle, 10, 1) -- SEEK_CUR
-
--- Seek to end of file
-CRamdiskSeek(handle, 0, 2) -- SEEK_END
-
-CRamdiskClose(handle)
-```
-
-**Parameters:**
-- `handle`: File handle (lightuserdata)
-- `offset`: Byte offset (number)
-- `whence`: Reference point - 0 (SEEK_SET), 1 (SEEK_CUR), 2 (SEEK_END)
-
-**Returns:** New position in file, or -1 on error
-
-**Whence values:**
-- `0` (SEEK_SET): Offset from beginning of file
-- `1` (SEEK_CUR): Offset from current position
-- `2` (SEEK_END): Offset from end of file
-
-### CRamdiskClose(handle)
-
-Closes an open file handle.
-
-```lua
-local handle = CRamdiskOpen(root, "/home/user/file.txt", "r")
--- ... use handle ...
-CRamdiskClose(handle)
-```
-
-**Parameters:**
-- `handle`: File handle (lightuserdata)
-
-**Returns:** Nothing
-
-### CRamdiskExists(root, path)
-
-Checks if a file or directory exists.
-
-```lua
-if CRamdiskExists(root, "/home/user/file.txt") then
- print("File exists")
-else
- print("File not found")
-end
-```
-
-**Parameters:**
-- `root`: Ramdisk root (lightuserdata)
-- `path`: Path to check (string)
-
-**Returns:** true if exists, false otherwise
-
-### CRamdiskList(root, path)
-
-Lists contents of a directory.
-
-```lua
-local entries = CRamdiskList(root, "/home/user")
-if entries then
- for i = 1, #entries do
- local entry = entries[i]
- local type_str = entry.type == 0 and "FILE" or "DIR"
- print(type_str .. ": " .. entry.name)
- end
-end
-```
-
-**Parameters:**
-- `root`: Ramdisk root (lightuserdata)
-- `path`: Directory path (string)
-
-**Returns:** Table of entries, each with:
-- `name`: Entry name (string)
-- `type`: Entry type (0 = file, 1 = directory)
-
-Returns nil on error.
-
-### CRamdiskRemove(root, path)
-
-Removes a file or directory.
-
-```lua
--- Remove a file
-if CRamdiskRemove(root, "/home/user/temp.txt") then
- print("File removed")
-end
-
--- Remove empty directory
-CRamdiskRemove(root, "/home/user/temp")
-```
-
-**Parameters:**
-- `root`: Ramdisk root (lightuserdata)
-- `path`: Path to remove (string)
-
-**Returns:** true on success, false on error
-
-**Note:** Directories must be empty before removal.
-
-## Complete Examples
-
-### Example 1: Create and Write File
-
-```lua
--- Initialize ramdisk
-local root = CRamdiskCreate()
-
--- Create directory structure
-CRamdiskMkdir(root, "/data")
-CRamdiskMkdir(root, "/data/logs")
-
--- Write log file
-local handle = CRamdiskOpen(root, "/data/logs/system.log", "w")
-CRamdiskWrite(handle, "System started\n")
-CRamdiskWrite(handle, "Loading modules...\n")
-CRamdiskWrite(handle, "Ready\n")
-CRamdiskClose(handle)
-
-print("Log file created")
-```
-
-### Example 2: Read File Contents
-
-```lua
-local root = CRamdiskCreate()
-CRamdiskMkdir(root, "/config")
-
--- Write config file
-local handle = CRamdiskOpen(root, "/config/settings.txt", "w")
-CRamdiskWrite(handle, "resolution=1024x768\n")
-CRamdiskWrite(handle, "color_depth=32\n")
-CRamdiskWrite(handle, "fullscreen=true\n")
-CRamdiskClose(handle)
-
--- Read config file
-handle = CRamdiskOpen(root, "/config/settings.txt", "r")
-local content = CRamdiskRead(handle, 1024)
-CRamdiskClose(handle)
-
-print("Config file contents:")
-print(content)
-```
-
-### Example 3: Append to File
-
-```lua
-local root = CRamdiskCreate()
-
--- Create initial file
-local handle = CRamdiskOpen(root, "/log.txt", "w")
-CRamdiskWrite(handle, "Initial entry\n")
-CRamdiskClose(handle)
-
--- Append more entries
-handle = CRamdiskOpen(root, "/log.txt", "a")
-CRamdiskWrite(handle, "Second entry\n")
-CRamdiskWrite(handle, "Third entry\n")
-CRamdiskClose(handle)
-
--- Read complete file
-handle = CRamdiskOpen(root, "/log.txt", "r")
-local all_data = CRamdiskRead(handle, 1024)
-CRamdiskClose(handle)
-
-print(all_data)
-```
-
-### Example 4: Directory Listing
-
-```lua
-local root = CRamdiskCreate()
-
--- Create some files and directories
-CRamdiskMkdir(root, "/projects")
-CRamdiskMkdir(root, "/projects/game")
-CRamdiskMkdir(root, "/projects/tools")
-
-local handle = CRamdiskOpen(root, "/projects/readme.txt", "w")
-CRamdiskWrite(handle, "Project documentation\n")
-CRamdiskClose(handle)
-
-handle = CRamdiskOpen(root, "/projects/todo.txt", "w")
-CRamdiskWrite(handle, "Task list\n")
-CRamdiskClose(handle)
-
--- List directory contents
-print("Contents of /projects:")
-local entries = CRamdiskList(root, "/projects")
-for i = 1, #entries do
- local entry = entries[i]
- local type_str = entry.type == 0 and "[FILE]" or "[DIR] "
- print(" " .. type_str .. " " .. entry.name)
-end
-```
-
-### Example 5: File Seeking
-
-```lua
-local root = CRamdiskCreate()
-
--- Create file with known structure
-local handle = CRamdiskOpen(root, "/data.bin", "w")
-CRamdiskWrite(handle, "HEADER") -- 6 bytes
-CRamdiskWrite(handle, "DATA123") -- 7 bytes
-CRamdiskWrite(handle, "FOOTER") -- 6 bytes
-CRamdiskClose(handle)
-
--- Read specific sections
-handle = CRamdiskOpen(root, "/data.bin", "r")
-
--- Read header
-CRamdiskSeek(handle, 0, 0) -- Start
-local header = CRamdiskRead(handle, 6)
-print("Header: " .. header)
-
--- Read data section
-CRamdiskSeek(handle, 6, 0) -- Skip header
-local data = CRamdiskRead(handle, 7)
-print("Data: " .. data)
-
--- Read footer
-CRamdiskSeek(handle, -6, 2) -- 6 bytes from end
-local footer = CRamdiskRead(handle, 6)
-print("Footer: " .. footer)
-
-CRamdiskClose(handle)
-```
-
-### Example 6: Check and Create
-
-```lua
-local root = CRamdiskCreate()
-
--- Check if file exists before creating
-local path = "/users/admin/profile.txt"
-
-if not CRamdiskExists(root, path) then
- -- Create directory if needed
- CRamdiskMkdir(root, "/users")
- CRamdiskMkdir(root, "/users/admin")
-
- -- Create file
- local handle = CRamdiskOpen(root, path, "w")
- CRamdiskWrite(handle, "username=admin\n")
- CRamdiskWrite(handle, "role=administrator\n")
- CRamdiskClose(handle)
-
- print("Profile created")
-else
- print("Profile already exists")
-end
-```
-
-## Performance Characteristics
-
-- **Memory Management**: Files use dynamic allocation with capacity doubling
-- **Path Traversal**: O(n) where n is path depth
-- **Directory Operations**: O(m) where m is number of entries (linked list)
-- **File I/O**: O(1) for reads/writes at current position
-- **Seeking**: O(1) position update
-
-## Comparison: C Ramdisk vs Lua Ramdisk
-
-| Feature | C Ramdisk | Lua Ramdisk (io.open) |
-|---------|-----------|----------------------|
-| Performance | Fast (native C) | Slower (Lua table operations) |
-| Memory | Efficient (direct allocation) | Higher overhead (Lua strings) |
-| API | C function calls | Lua-style io API |
-| Compatibility | Custom functions | Standard Lua io API |
-| Use Case | High-performance operations | Quick scripting, compatibility |
-
-## Integration with Lua Ramdisk
-
-Both ramdisk systems can coexist:
-
-```lua
--- Use Lua ramdisk with io.open (from init.lua)
-local lua_file = io.open("/config.txt", "w")
-lua_file:write("Setting=Value\n")
-lua_file:close()
-
--- Use C ramdisk with CRamdisk functions
-local c_root = CRamdiskCreate()
-local c_file = CRamdiskOpen(c_root, "/config.txt", "w")
-CRamdiskWrite(c_file, "Setting=Value\n")
-CRamdiskClose(c_file)
-```
-
-Choose based on your needs:
-- **Lua ramdisk**: Standard API, integration with existing Lua code
-- **C ramdisk**: Performance-critical operations, larger datasets
-
-## Error Handling
-
-All functions return nil/false on error:
-
-```lua
-local root = CRamdiskCreate()
-
--- Check for errors
-local handle = CRamdiskOpen(root, "/nonexistent.txt", "r")
-if not handle then
- print("Error: Could not open file")
- return
-end
-
--- Always close handles
-CRamdiskClose(handle)
-```
-
-## Memory Considerations
-
-- Each file allocates memory dynamically
-- File capacity doubles when expanding
-- Directory entries use linked lists
-- Remember to close file handles to release resources
-- The C ramdisk persists as long as the root pointer is retained
-
-## Implementation Details
-
-Located in:
-- **ramdisk.h**: Data structures and function declarations
-- **ramdisk.c**: Complete implementation (~900 lines)
-- **kernel.c**: Lua binding registration
-
-The C ramdisk is compiled into the kernel and available immediately at boot.
diff --git a/DEVELOPMENT_PROMPT.md b/DEVELOPMENT_PROMPT.md
@@ -1,696 +0,0 @@
-# LuajitOS Application Development Guide
-
-You are developing applications for **LuajitOS**, a bare-metal operating system written in C with LuaJIT integration. Applications are sandboxed Lua programs that run in a controlled environment with permission-based access to system resources.
-
----
-
-## Application Folder Structure
-
-Applications follow a strict directory structure under `/apps/`:
-
-```
-/apps/com.<developer>.<appname>/
-├── manifest.lua # Required: Application metadata and configuration
-├── src/ # Required: Source code directory
-│ └── <entry_file>.lua # Entry point file (defined by 'entry' in manifest)
-├── data/ # Optional: Application data storage (read/write)
-├── tmp/ # Optional: Temporary files
-├── settings/ # Optional: Application settings
-└── res/ # Optional: Resources (images, etc.)
-```
-
-### Folder Naming Convention
-- **Format**: `com.<developer>.<appname>`
-- **Examples**:
- - `com.luajitos.calculator`
- - `com.luajitos.shell`
- - `com.dev.myapp`
-
-### Standard Directories
-
-| Directory | Purpose | Access | Auto-created |
-|-----------|---------|--------|--------------|
-| `src/` | Source code files | Read-only | No (required) |
-| `data/` | Persistent data storage | Read/write | Yes (if filesystem permission granted) |
-| `tmp/` | Temporary files | Read/write | No |
-| `settings/` | Configuration files | Read/write | No |
-| `res/` | Static resources (images, fonts) | Read-only | No |
-
----
-
-## The `$` Shortcut
-
-The `$` symbol is a **path shortcut** that refers to your application's root directory.
-
-### Usage in manifest.lua:
-```lua
-allowedPaths = {
- "$/data/*", -- Expands to /apps/com.dev.myapp/data/*
- "$/tmp/*", -- Expands to /apps/com.dev.myapp/tmp/*
- "$/src/*" -- Expands to /apps/com.dev.myapp/src/*
-}
-```
-
-### Default Behavior:
-- `$/data/*` is **always enabled by default** when `filesystem` permission is granted
-- Other paths using `$` must be explicitly listed in `allowedPaths`
-
----
-
-## manifest.lua - Application Manifest
-
-The `manifest.lua` file defines your application's metadata, permissions, and configuration.
-
-### Required Fields
-
-```lua
-return {
- name = "myapp", -- Application name (string)
- developer = "dev", -- Developer namespace (string)
- version = "1.0.0", -- Version string
- entry = "src/myapp.lua", -- Entry point: path to main .lua file (relative to app root)
- -- Can be any filename, e.g., "src/main.lua", "src/background.lua"
- mode = "gui", -- "gui" or "cli"
-}
-```
-
-**Note**: The `entry` field specifies which Lua file to execute when your app starts. It can be any `.lua` file in your app directory - there's no requirement to use `init.lua`.
-
-### Optional Fields
-
-```lua
-return {
- -- Required fields...
-
- author = "Your Name", -- Author name
- description = "App description", -- Short description
-
- permissions = { -- Array of permission strings
- "filesystem",
- "draw",
- "ramdisk",
- -- ... see Permissions section
- },
-
- allowedPaths = { -- Filesystem paths (when filesystem permission granted)
- "$/tmp/*",
- "$/settings/*",
- "/os/public/res/*" -- Absolute paths allowed
- }
-}
-```
-
-### Application Modes
-
-| Mode | Description | Use Case |
-|------|-------------|----------|
-| `"gui"` | Graphical application | Apps with windows and graphics |
-| `"cli"` | Command-line application | Terminal apps, background services |
-
----
-
-## Permissions System
-
-Applications must declare required permissions in their manifest. Permissions control access to system resources.
-
-### Available Permissions
-
-| Permission | Grants Access To | Description |
-|------------|------------------|-------------|
-| `"filesystem"` | SafeFS API | Read/write files in allowed paths (defaults to `$/data/*`) |
-| `"ramdisk"` | CRamdisk* functions | Direct ramdisk access (bypasses SafeFS) |
-| `"draw"` | Graphics API | Drawing functions for windows |
-| `"background"` | Background rendering | Allows app to render as desktop background |
-| `"fullscreen"` | Fullscreen mode | Request fullscreen window |
-| `"stdio"` | Standard I/O | Access to `print()`, `cli.buffer` |
-| `"scheduling"` | Scheduler API | Access to `os.schedule` for delayed tasks |
-| `"export"` | Function exports | Export functions for other apps |
-| `"import"` | Function imports | Call exported functions from other apps |
-| `"run"` | App execution | Run other applications via `run()` |
-
-### Permission Examples
-
-```lua
--- Minimal CLI app
-permissions = {
- "stdio"
-}
-
--- GUI app with file access
-permissions = {
- "draw",
- "filesystem"
-}
-
--- Background desktop wallpaper
-permissions = {
- "ramdisk",
- "draw",
- "background"
-}
-
--- Advanced shell application
-permissions = {
- "filesystem",
- "scheduling",
- "export",
- "import",
- "draw",
- "fullscreen",
- "run"
-}
-```
-
----
-
-## Application Interface (`app` object)
-
-When your application starts, it receives an `app` instance that provides the Application API.
-
-### Core Properties
-
-```lua
-app.appName -- string: Application name
-app.appPath -- string: Full path (e.g., "/apps/com.dev.myapp")
-app.pid -- number: Process ID (unique)
-app.status -- string: "running" | "stopped" | "terminated"
-app.startTime -- number: Timestamp when app started
-```
-
-### Window Management
-
-#### Create a Window
-```lua
--- Create window at specific position
-local window = app:newWindow(x, y, width, height)
-
--- Create centered window
-local window = app:newWindow(width, height)
-```
-
-#### Window Properties
-```lua
-window.x -- number: X position
-window.y -- number: Y position
-window.width -- number: Width in pixels
-window.height -- number: Height in pixels
-window.visible -- boolean: Visibility state
-window.isBorderless -- boolean: If true, no title bar or border
-window.title -- string: Window title text
-```
-
-#### Window Methods
-
-```lua
--- Set draw callback (called every frame)
-window:onDraw(function(gfx)
- -- gfx is a SafeGFX instance
- gfx.vesa_fill_rect(0, 0, 100, 100, 0xFF0000) -- Red rectangle
-end)
-
--- Set input callback (keyboard/mouse events)
-window:onInput(function(event)
- if event.type == "key" then
- print("Key pressed: " .. event.key)
- end
-end)
-
--- Move window
-window.x = 100
-window.y = 200
-
--- Hide/show window
-window.visible = false
-window.visible = true
-
--- Remove title bar and border
-window.isBorderless = true
-```
-
-### Function Export/Import
-
-#### Export Functions
-```lua
-app:export({
- name = "myFunction",
- func = function(arg1, arg2)
- return arg1 + arg2
- end,
- description = "Adds two numbers",
- parameters = "number,number", -- Optional: parameter types
- returns = "number" -- Optional: return type
-})
-```
-
-#### Import and Call Functions
-```lua
--- Get another app's exported function
-local otherApp = apps["com.dev.otherapp"]
-if otherApp then
- local result = otherApp:call("myFunction", 5, 10)
-end
-```
-
-### Process Information
-
-```lua
--- Get process info (creates /proc/<PID>/process)
-local info = app:getProcessInfo()
--- info = {
--- pid = 12345,
--- appPath = "/apps/com.dev.myapp",
--- appName = "myapp",
--- status = "running",
--- startTime = 1234567890
--- }
-```
-
-### Application Lifecycle
-
-```lua
--- Terminate the application
-app:terminate()
-
--- Change status
-app:setStatus("stopped") -- "running" | "stopped"
-```
-
----
-
-## SafeGFX - Sandboxed Graphics API
-
-SafeGFX provides coordinate-bounded drawing within a window's content area. All coordinates are **relative to the window's content area** (0,0 is top-left of drawable area).
-
-### Coordinate System
-
-- **Origin**: Top-left corner of window content area (excluding title bar/border)
-- **Bounds**: Coordinates outside the content area are clipped
-- **Units**: Pixels
-
-### Drawing Functions
-
-All graphics functions are accessed through the `gfx` parameter in `window:onDraw(function(gfx) ... end)`.
-
-#### Rectangle Drawing
-```lua
--- Fill rectangle
-gfx.vesa_fill_rect(x, y, width, height, color)
--- color: 0xRRGGBB format (24-bit RGB)
-
--- Example: Red 50x50 square at (10, 10)
-gfx.vesa_fill_rect(10, 10, 50, 50, 0xFF0000)
-```
-
-#### Text Drawing
-```lua
--- Draw text
-gfx.vesa_draw_text(x, y, text, color)
-
--- Example: White text
-gfx.vesa_draw_text(10, 10, "Hello World", 0xFFFFFF)
-```
-
-#### Image Drawing
-```lua
--- Draw image (from loaded image handle)
-ImageDraw(image, x, y)
-
--- Load BMP image
-local handle = CRamdiskOpen("/os/public/res/image.bmp", "r")
-local data = CRamdiskRead(handle)
-CRamdiskClose(handle)
-local image = BMPLoad(data)
-
--- Draw in window
-window:onDraw(function(gfx)
- ImageDraw(image, 0, 0) -- Draw at top-left
-end)
-```
-
-### Color Format
-
-Colors use **24-bit RGB** hex format: `0xRRGGBB`
-
-```lua
-local RED = 0xFF0000
-local GREEN = 0x00FF00
-local BLUE = 0x0000FF
-local WHITE = 0xFFFFFF
-local BLACK = 0x000000
-local GRAY = 0x808080
-```
-
-### SafeGFX Bounds Checking
-
-SafeGFX automatically:
-- Clips drawing operations to window content area
-- Transforms local coordinates (0,0) to screen coordinates
-- Prevents drawing outside window bounds
-- Accounts for title bar and border (unless `isBorderless = true`)
-
-### Example: Complete Window Drawing
-
-```lua
-local window = app:newWindow(400, 300)
-window.title = "My App"
-
-window:onDraw(function(gfx)
- -- Clear background (white)
- gfx.vesa_fill_rect(0, 0, 400, 300, 0xFFFFFF)
-
- -- Draw colored rectangles
- gfx.vesa_fill_rect(10, 10, 100, 100, 0xFF0000) -- Red
- gfx.vesa_fill_rect(120, 10, 100, 100, 0x00FF00) -- Green
- gfx.vesa_fill_rect(230, 10, 100, 100, 0x0000FF) -- Blue
-
- -- Draw text
- gfx.vesa_draw_text(10, 120, "Hello from SafeGFX!", 0x000000)
-end)
-```
-
----
-
-## SafeFS - Sandboxed Filesystem API
-
-SafeFS provides path-restricted file access. Applications can only access paths listed in their `allowedPaths` (defaults to `$/data/*`).
-
-### File Operations
-
-#### Check if File/Directory Exists
-```lua
-if SafeFS.exists("$/data/myfile.txt") then
- print("File exists")
-end
-```
-
-#### Read File
-```lua
-local content = SafeFS.read("$/data/myfile.txt")
-if content then
- print(content)
-else
- print("Failed to read file")
-end
-```
-
-#### Write File
-```lua
-local success = SafeFS.write("$/data/myfile.txt", "Hello World!")
-if not success then
- print("Failed to write file")
-end
-```
-
-#### List Directory
-```lua
-local entries = SafeFS.list("$/data/")
-if entries then
- for _, entry in ipairs(entries) do
- print(entry.type .. ": " .. entry.name)
- -- entry.type: "file" or "dir"
- -- entry.name: filename/dirname
- end
-end
-```
-
-#### Create Directory
-```lua
-local success = SafeFS.mkdir("$/data/subdir")
-```
-
-#### Delete File
-```lua
-local success = SafeFS.remove("$/data/oldfile.txt")
-```
-
-### Path Resolution
-
-The `$` shortcut expands to your app's root path:
-
-```lua
--- In com.dev.myapp:
-"$/data/file.txt" → "/apps/com.dev.myapp/data/file.txt"
-"$/tmp/cache" → "/apps/com.dev.myapp/tmp/cache"
-```
-
-### Direct Ramdisk Access (Advanced)
-
-If you have the `"ramdisk"` permission, you can bypass SafeFS and access the ramdisk directly:
-
-```lua
--- Open file
-local handle, err = CRamdiskOpen("/os/public/res/image.bmp", "r")
-if not handle then
- print("Error: " .. err)
- return
-end
-
--- Read file
-local data = CRamdiskRead(handle)
-
--- Close file
-CRamdiskClose(handle)
-
--- Write file
-local handle = CRamdiskOpen("/path/to/file.txt", "w")
-CRamdiskWrite(handle, "content")
-CRamdiskClose(handle)
-
--- Check existence
-if CRamdiskExists("/path/to/file") then
- -- file exists
-end
-
--- List directory
-local items = CRamdiskList("/path/to/dir")
-for _, item in ipairs(items) do
- print(item.type .. ": " .. item.name)
-end
-
--- Create directory
-local success, err = CRamdiskMkdir("/path/to/newdir")
-
--- Remove file/directory
-CRamdiskRemove("/path/to/file")
-```
-
-**Warning**: Ramdisk access bypasses security restrictions. Only use for system-level operations.
-
----
-
-## Complete Example Application
-
-### Directory Structure
-```
-/apps/com.dev.hello/
-├── manifest.lua
-└── src/
- └── hello.lua
-```
-
-### manifest.lua
-```lua
-return {
- name = "hello",
- developer = "dev",
- version = "1.0.0",
- author = "Your Name",
- description = "Hello World GUI Application",
- entry = "src/hello.lua", -- Entry point (can be any .lua file)
- mode = "gui",
- permissions = {
- "draw",
- "filesystem"
- },
- allowedPaths = {
- "$/data/*"
- }
-}
-```
-
-### src/hello.lua
-```lua
--- Create a 400x300 window
-local window = app:newWindow(400, 300)
-window.title = "Hello World"
-
--- Track click count
-local clicks = 0
-
--- Load click count from file
-if SafeFS then
- local savedClicks = SafeFS.read("$/data/clicks.txt")
- if savedClicks then
- clicks = tonumber(savedClicks) or 0
- end
-end
-
--- Draw callback
-window:onDraw(function(gfx)
- -- White background
- gfx.vesa_fill_rect(0, 0, 400, 300, 0xFFFFFF)
-
- -- Blue rectangle
- gfx.vesa_fill_rect(50, 50, 300, 100, 0x3399FF)
-
- -- Display text
- gfx.vesa_draw_text(60, 60, "Hello, LuajitOS!", 0xFFFFFF)
- gfx.vesa_draw_text(60, 90, "Clicks: " .. clicks, 0xFFFFFF)
-end)
-
--- Input callback
-window:onInput(function(event)
- if event.type == "mouse" and event.button == 1 then
- clicks = clicks + 1
-
- -- Save to file
- if SafeFS then
- SafeFS.write("$/data/clicks.txt", tostring(clicks))
- end
- end
-end)
-
--- Export a function
-app:export({
- name = "getClicks",
- func = function()
- return clicks
- end,
- description = "Returns the current click count",
- returns = "number"
-})
-```
-
----
-
-## Process Filesystem (/proc)
-
-Every running application automatically gets a `/proc/<PID>/` directory:
-
-```
-/proc/
-├── 12345/
-│ └── process # Contains app path and PID
-└── 67890/
- └── process
-```
-
-### /proc/<PID>/process Format
-```
-/apps/com.dev.myapp
-12345
-```
-
-Line 1: Full application path
-Line 2: Process ID
-
-### Accessing /proc
-
-```lua
--- List all running processes
-local procs = CRamdiskList("/proc")
-for _, proc in ipairs(procs) do
- local pid = proc.name
- local handle = CRamdiskOpen("/proc/" .. pid .. "/process", "r")
- local info = CRamdiskRead(handle)
- CRamdiskClose(handle)
- print("PID " .. pid .. ": " .. info)
-end
-```
-
-**Note**: `/proc` entries are automatically created when apps start and removed when they terminate.
-
----
-
-## Best Practices
-
-1. **Always check return values** from SafeFS operations
-2. **Use `$` shortcut** for app-relative paths in manifest
-3. **Request minimal permissions** - only what your app needs
-4. **Free resources** - close file handles, clean up on terminate
-5. **Handle errors gracefully** - use `pcall()` for risky operations
-6. **Optimize drawing** - avoid redrawing entire window every frame
-7. **Use `isBorderless = true`** for full-window content (like background apps)
-
----
-
-## Common Patterns
-
-### Read Configuration File
-```lua
-local config = SafeFS.read("$/settings/config.lua")
-if config then
- local configFunc = load(config)
- if configFunc then
- local settings = configFunc()
- -- Use settings table
- end
-end
-```
-
-### Save Application State
-```lua
-local state = {
- score = 100,
- level = 5
-}
-
-local serialized = "return " .. serialize(state)
-SafeFS.write("$/data/save.lua", serialized)
-```
-
-### Load and Display Image
-```lua
-local handle = CRamdiskOpen("/os/public/res/logo.bmp", "r")
-local data = CRamdiskRead(handle)
-CRamdiskClose(handle)
-
-local image = BMPLoad(data)
-
-window:onDraw(function(gfx)
- ImageDraw(image, 0, 0)
-end)
-```
-
-### Inter-App Communication
-```lua
--- App A exports a function
-app:export({
- name = "sendMessage",
- func = function(msg)
- print("Received: " .. msg)
- end
-})
-
--- App B calls it
-local appA = apps["com.dev.appA"]
-if appA then
- appA:call("sendMessage", "Hello from App B!")
-end
-```
-
----
-
-## Debugging Tips
-
-1. **Use `osprint()`** for kernel-level debug output (appears in serial console)
-2. **Check `/proc/<PID>/process`** to verify your app is running
-3. **Wrap code in `pcall()`** to catch and log errors
-4. **Use `app:getProcessInfo()`** to inspect app state
-5. **Test permissions** - missing permissions cause silent failures
-
----
-
-## Summary
-
-You now have everything you need to build LuajitOS applications:
-
-- ✅ Folder structure: `/apps/com.dev.appname/`
-- ✅ `manifest.lua` with all fields and permissions
-- ✅ `app` object API for windows, exports, process info
-- ✅ **SafeGFX** for sandboxed drawing (coordinate-bounded)
-- ✅ **SafeFS** for sandboxed filesystem (path-restricted)
-- ✅ `/proc` filesystem for process tracking
-- ✅ Complete example application
-
-Start building by creating your `manifest.lua` with the `entry` field pointing to your main source file (e.g., `src/myapp.lua`)!
diff --git a/FILESYSTEM_API.md b/FILESYSTEM_API.md
@@ -1,573 +0,0 @@
-# Filesystem API Documentation
-
-LuajitOS now includes a complete in-memory filesystem with standard Lua `io` API compatibility!
-
-## Features
-
-✅ **File Handles** - Standard `io.open()` with read/write support
-✅ **Read Modes** - `*a`, `*l`, `*n`, or byte count
-✅ **Write/Append** - Full write and append support
-✅ **File Creation** - Auto-create files in write/append mode
-✅ **Seek Operations** - Random access with `seek()`
-✅ **Line Iteration** - `for line in file:lines()` support
-✅ **Helper Functions** - `readFile()` and `writeFile()` shortcuts
-
-## API Reference
-
-### io.open(filepath, mode)
-
-Opens a file and returns a file handle.
-
-**Parameters:**
-- `filepath` (string) - Path to file (e.g., "/test.txt" or "/os/data/config.lua")
-- `mode` (string) - File mode (default: "r")
- - `"r"` - Read mode (file must exist)
- - `"w"` - Write mode (creates or truncates file)
- - `"a"` - Append mode (creates if doesn't exist)
- - `"r+"` - Read/write mode (file must exist)
- - `"w+"` - Read/write mode (truncates)
- - `"a+"` - Read/append mode
-
-**Returns:**
-- File handle on success
-- `nil, error` on failure
-
-**Example:**
-```lua
-local file, err = io.open("/test.txt", "r")
-if not file then
- print("Error: " .. err)
- return
-end
-```
-
-### File Handle Methods
-
-#### file:read(format)
-
-Reads from file according to format.
-
-**Formats:**
-- `"*a"` or `"*all"` - Read entire file
-- `"*l"` or `"*line"` - Read single line (default)
-- `"*n"` or `"*number"` - Read number
-- `number` - Read specified number of bytes
-
-**Examples:**
-```lua
--- Read entire file
-local content = file:read("*a")
-
--- Read line by line
-local line = file:read("*l")
-local line2 = file:read("*l")
-
--- Read 10 bytes
-local data = file:read(10)
-
--- Read number
-local num = file:read("*n")
-```
-
-#### file:write(...)
-
-Writes data to file. Accepts multiple arguments.
-
-**Example:**
-```lua
-file:write("Hello, ")
-file:write("World!\n")
-
--- Multiple arguments
-file:write("Line 1\n", "Line 2\n", "Line 3\n")
-
--- Returns file handle for chaining
-file:write("A"):write("B"):write("C")
-```
-
-#### file:lines()
-
-Returns iterator for reading lines.
-
-**Example:**
-```lua
-for line in file:lines() do
- print(line)
-end
-```
-
-#### file:seek(whence, offset)
-
-Sets file position for next read/write.
-
-**Parameters:**
-- `whence` (string) - Reference point
- - `"set"` - From beginning of file (default)
- - `"cur"` - From current position
- - `"end"` - From end of file
-- `offset` (number) - Offset in bytes (default: 0)
-
-**Returns:**
-- New position on success
-- `nil, error` on failure
-
-**Examples:**
-```lua
--- Go to beginning
-file:seek("set", 0)
-
--- Skip 10 bytes forward
-file:seek("cur", 10)
-
--- Go to end
-file:seek("end", 0)
-
--- Go 5 bytes before end
-file:seek("end", -5)
-```
-
-#### file:close()
-
-Closes the file handle.
-
-**Example:**
-```lua
-file:close()
-```
-
-#### file:flush()
-
-Flushes write buffer (no-op for ramdisk).
-
-**Example:**
-```lua
-file:flush()
-```
-
-## Helper Functions
-
-### readFile(filepath)
-
-Convenience function to read entire file.
-
-**Example:**
-```lua
-local content, err = readFile("/test.txt")
-if content then
- print("File contents:", content)
-else
- print("Error:", err)
-end
-```
-
-### writeFile(filepath, content)
-
-Convenience function to write entire file.
-
-**Example:**
-```lua
-local success, err = writeFile("/test.txt", "Hello, World!")
-if not success then
- print("Error:", err)
-end
-```
-
-## Complete Examples
-
-### Example 1: Read Entire File
-
-```lua
--- Simple way
-local content = readFile("/os/libs/graphicslib.lua")
-print("File size:", #content)
-
--- Standard way
-local file = io.open("/os/libs/graphicslib.lua", "r")
-if file then
- local content = file:read("*a")
- print("File size:", #content)
- file:close()
-end
-```
-
-### Example 2: Write and Read File
-
-```lua
--- Write a file
-local file = io.open("/test.txt", "w")
-file:write("Line 1\n")
-file:write("Line 2\n")
-file:write("Line 3\n")
-file:close()
-
--- Read it back
-local file = io.open("/test.txt", "r")
-for line in file:lines() do
- print(line)
-end
-file:close()
-
--- Output:
--- Line 1
--- Line 2
--- Line 3
-```
-
-### Example 3: Append to File
-
-```lua
--- Create file
-writeFile("/log.txt", "Start\n")
-
--- Append more lines
-local file = io.open("/log.txt", "a")
-file:write("Event 1\n")
-file:write("Event 2\n")
-file:write("Event 3\n")
-file:close()
-
--- Read result
-print(readFile("/log.txt"))
-
--- Output:
--- Start
--- Event 1
--- Event 2
--- Event 3
-```
-
-### Example 4: Read Line by Line
-
-```lua
--- Create test file
-writeFile("/data.txt", "apple\nbanana\ncherry\ndate\n")
-
--- Read line by line
-local file = io.open("/data.txt", "r")
-local count = 0
-for line in file:lines() do
- count = count + 1
- print(count .. ": " .. line)
-end
-file:close()
-
--- Output:
--- 1: apple
--- 2: banana
--- 3: cherry
--- 4: date
-```
-
-### Example 5: Random Access with Seek
-
-```lua
--- Create file
-writeFile("/test.bin", "ABCDEFGHIJKLMNOP")
-
--- Random access reading
-local file = io.open("/test.bin", "r")
-
--- Read first 3 bytes
-print(file:read(3)) -- ABC
-
--- Jump to position 10
-file:seek("set", 10)
-print(file:read(3)) -- KLM
-
--- Go back 5 bytes
-file:seek("cur", -5)
-print(file:read(3)) -- IJK
-
--- Go to end and read backwards
-file:seek("end", -3)
-print(file:read(3)) -- NOP
-
-file:close()
-```
-
-### Example 6: Read Numbers
-
-```lua
--- Create file with numbers
-writeFile("/numbers.txt", "42 3.14 -10 2.5")
-
--- Read numbers
-local file = io.open("/numbers.txt", "r")
-local a = file:read("*n") -- 42
-local b = file:read("*n") -- 3.14
-local c = file:read("*n") -- -10
-local d = file:read("*n") -- 2.5
-file:close()
-
-print(a, b, c, d) -- 42 3.14 -10 2.5
-print(a + b) -- 45.14
-```
-
-### Example 7: Read/Write Mode
-
-```lua
--- Create file
-writeFile("/config.txt", "option1=value1\noption2=value2\n")
-
--- Open for read and write
-local file = io.open("/config.txt", "r+")
-
--- Read first line
-local line = file:read("*l")
-print("First line:", line)
-
--- Append new line
-file:seek("end", 0)
-file:write("option3=value3\n")
-
-file:close()
-
--- Check result
-print(readFile("/config.txt"))
-
--- Output:
--- option1=value1
--- option2=value2
--- option3=value3
-```
-
-### Example 8: Process Log File
-
-```lua
--- Create a log
-local log = io.open("/app.log", "w")
-log:write("2024-01-01 10:00:00 - App started\n")
-log:write("2024-01-01 10:01:00 - User logged in\n")
-log:write("2024-01-01 10:02:00 - ERROR: Connection failed\n")
-log:write("2024-01-01 10:03:00 - Retrying...\n")
-log:write("2024-01-01 10:04:00 - SUCCESS: Connected\n")
-log:close()
-
--- Find all ERROR lines
-local errors = {}
-local file = io.open("/app.log", "r")
-for line in file:lines() do
- if line:match("ERROR") then
- table.insert(errors, line)
- end
-end
-file:close()
-
-print("Found " .. #errors .. " errors:")
-for _, err in ipairs(errors) do
- print(err)
-end
-
--- Output:
--- Found 1 errors:
--- 2024-01-01 10:02:00 - ERROR: Connection failed
-```
-
-### Example 9: CSV Parser
-
-```lua
--- Create CSV file
-writeFile("/data.csv", "name,age,city\nAlice,30,NYC\nBob,25,LA\nCharlie,35,Chicago\n")
-
--- Parse CSV
-local records = {}
-local file = io.open("/data.csv", "r")
-
--- Read header
-local header = file:read("*l")
-
--- Read data rows
-for line in file:lines() do
- local name, age, city = line:match("([^,]+),([^,]+),([^,]+)")
- table.insert(records, {
- name = name,
- age = tonumber(age),
- city = city
- })
-end
-file:close()
-
--- Display
-for _, record in ipairs(records) do
- print(record.name .. " is " .. record.age .. " years old and lives in " .. record.city)
-end
-
--- Output:
--- Alice is 30 years old and lives in NYC
--- Bob is 25 years old and lives in LA
--- Charlie is 35 years old and lives in Chicago
-```
-
-### Example 10: Configuration File
-
-```lua
--- Write config
-local function saveConfig(filepath, config)
- local file = io.open(filepath, "w")
- for key, value in pairs(config) do
- file:write(key .. "=" .. tostring(value) .. "\n")
- end
- file:close()
-end
-
--- Read config
-local function loadConfig(filepath)
- local config = {}
- local file = io.open(filepath, "r")
- if not file then
- return nil, "file not found"
- end
-
- for line in file:lines() do
- local key, value = line:match("([^=]+)=([^\n]+)")
- if key then
- config[key] = value
- end
- end
- file:close()
-
- return config
-end
-
--- Use it
-local my_config = {
- width = 1024,
- height = 768,
- fullscreen = true,
- username = "player1"
-}
-
-saveConfig("/game.cfg", my_config)
-
--- Later...
-local loaded = loadConfig("/game.cfg")
-print("Width:", loaded.width)
-print("Height:", loaded.height)
-print("Fullscreen:", loaded.fullscreen)
-```
-
-## Error Handling
-
-Always check for errors when opening files:
-
-```lua
-local file, err = io.open("/nonexistent.txt", "r")
-if not file then
- print("Failed to open file:", err)
- return
-end
-
--- File opened successfully
-local content = file:read("*a")
-file:close()
-```
-
-## Mode Comparison
-
-| Mode | File Must Exist | Truncate | Create | Position | Read | Write |
-|------|----------------|----------|--------|----------|------|-------|
-| `"r"` | Yes | No | No | Start | ✅ | ❌ |
-| `"w"` | No | Yes | Yes | Start | ❌ | ✅ |
-| `"a"` | No | No | Yes | End | ❌ | ✅ |
-| `"r+"` | Yes | No | No | Start | ✅ | ✅ |
-| `"w+"` | No | Yes | Yes | Start | ✅ | ✅ |
-| `"a+"` | No | No | Yes | End | ✅ | ✅ |
-
-## Tips and Best Practices
-
-### Always Close Files
-
-```lua
--- Good
-local file = io.open("/test.txt", "r")
-if file then
- local content = file:read("*a")
- file:close() -- Always close!
-end
-
--- Better (with pcall)
-local file = io.open("/test.txt", "r")
-if file then
- local success, result = pcall(function()
- return file:read("*a")
- end)
- file:close() -- Close even if error occurs
-
- if success then
- print(result)
- end
-end
-```
-
-### Use Helper Functions for Simple Cases
-
-```lua
--- Instead of:
-local file = io.open("/test.txt", "r")
-local content = file:read("*a")
-file:close()
-
--- Use:
-local content = readFile("/test.txt")
-```
-
-### Check Errors
-
-```lua
-local file, err = io.open("/path/to/file.txt", "r")
-if not file then
- print("Error:", err)
- return
-end
-```
-
-### Use Append Mode for Logs
-
-```lua
-function log(message)
- local file = io.open("/app.log", "a")
- if file then
- file:write(os.date("%Y-%m-%d %H:%M:%S") .. " - " .. message .. "\n")
- file:close()
- end
-end
-```
-
-## Limitations
-
-- **In-Memory Only**: All files are stored in RAM (no persistence to disk)
-- **No Permissions**: No file permissions or access control
-- **No Locking**: No file locking mechanism
-- **No Directories in open()**: Must create directories separately with `root_fs:newDir()`
-
-## Integration with Existing Code
-
-The ramdisk filesystem from `root_fs` can still be accessed directly:
-
-```lua
--- Old way (still works)
-local file_node = root_fs:traverse("/test.txt")
-local content = file_node:read()
-
--- New way (preferred)
-local content = readFile("/test.txt")
-```
-
-## Compatibility
-
-This implementation provides compatibility with standard Lua file operations:
-
-```lua
--- Standard Lua code works!
-local file = io.open("test.txt", "w")
-file:write("Hello\n")
-file:close()
-
-local file = io.open("test.txt", "r")
-for line in file:lines() do
- print(line)
-end
-file:close()
-```
-
-Note: Paths must be absolute (start with `/`) in the ramdisk.
diff --git a/FILESYSTEM_TODO.md b/FILESYSTEM_TODO.md
@@ -1,34 +0,0 @@
-# Filesystem Implementation TODO
-
-## Current State
-- `init.lua` is embedded in kernel binary at compile time
-- Copy also placed in `/boot/init.lua` in ISO for reference only
-- No runtime file reading capability yet
-
-## To Enable Runtime File Loading
-
-### Option 1: GRUB Modules (Easiest)
-1. Modify `isodir/boot/grub/grub.cfg` to load init.lua as module:
- ```
- module /boot/init.lua
- ```
-2. Parse multiboot info structure in kernel to find module
-3. Read module from memory (already loaded by GRUB)
-
-### Option 2: ISO9660 Filesystem (More Complex)
-Requires implementing:
-1. BIOS INT 13h disk I/O (or UEFI equivalents)
-2. ISO9660 directory parsing
-3. File lookup and reading
-
-### Option 3: RAM Filesystem
-1. Create simple in-memory filesystem
-2. Populate from embedded data or GRUB modules
-3. Lua can read/write files in RAM
-
-## Disabled LuaJIT Features
-- JIT compilation (interpreter only)
-- FFI (Foreign Function Interface)
-- Secure PRNG (uses fixed seed)
-
-All other Lua features work: tables, metatables, closures, coroutines, etc.
diff --git a/HTTP_IMPLEMENTATION_COMPLETE.md b/HTTP_IMPLEMENTATION_COMPLETE.md
@@ -1,429 +0,0 @@
-# HTTP Implementation - Complete
-
-## Overview
-
-LuajitOS now has a complete, secure HTTP stack with automatic sandboxing for applications.
-
-## Architecture Layers
-
-```
-┌─────────────────────────────────────────────┐
-│ User Applications │
-│ (Automatic http global via sandbox) │
-├─────────────────────────────────────────────┤
-│ SafeHTTP (Sandboxed) │
-│ (Domain whitelist enforcement) │
-├─────────────────────────────────────────────┤
-│ HTTP Library (Client/Server) │
-│ (Request/Response, URL parsing, JSON) │
-├─────────────────────────────────────────────┤
-│ Socket API (BSD-like interface) │
-├─────────────────────────────────────────────┤
-│ TCP/UDP (Network Stack) │
-├─────────────────────────────────────────────┤
-│ RTL8139 Driver (Ethernet layer) │
-├─────────────────────────────────────────────┤
-│ Hardware (RTL8139 NIC in QEMU) │
-└─────────────────────────────────────────────┘
-```
-
-## Components Implemented
-
-### 1. RTL8139 Driver (`/os/libs/RTL8139.lua`)
-- ✅ Low-level Ethernet driver
-- ✅ Packet TX/RX
-- ✅ MAC address management
-- ✅ Callback-based packet handling
-
-### 2. Network Stack (`/os/libs/NetworkStack.lua`)
-- ✅ IPv4 protocol
-- ✅ ARP (address resolution)
-- ✅ ICMP (ping)
-- ✅ UDP protocol
-- ✅ TCP integration
-- ✅ Packet routing
-
-### 3. TCP Module (`/os/libs/TCP.lua`)
-- ✅ TCP state machine
-- ✅ Connection establishment (3-way handshake)
-- ✅ Data transmission
-- ✅ Connection teardown
-- ✅ Sequence numbers
-- ✅ Checksums
-
-### 4. Socket API (`/os/libs/Socket.lua`)
-- ✅ BSD-like socket interface
-- ✅ TCP and UDP sockets
-- ✅ Unified API
-- ✅ Event-driven callbacks
-
-### 5. HTTP Library (`/os/libs/HTTP.lua`)
-- ✅ HTTP/1.1 client
-- ✅ HTTP/1.1 server
-- ✅ Request/response parsing
-- ✅ URL parsing and encoding
-- ✅ Header management
-- ✅ JSON encoding
-- ✅ GET, POST, PUT, DELETE methods
-
-### 6. SafeHTTP (`/os/libs/SafeHTTP.lua`)
-- ✅ Domain whitelisting
-- ✅ Wildcard patterns (*.example.com)
-- ✅ Callback-based async API
-- ✅ Request timeout
-- ✅ Response size limits
-- ✅ Request cancellation
-- ✅ Concurrent requests
-
-### 7. Sandbox Integration (`/os/libs/run.lua`)
-- ✅ Automatic SafeHTTP provision
-- ✅ Manifest-based permissions
-- ✅ Domain whitelist from manifest
-- ✅ Per-app isolation
-- ✅ Security enforcement
-
-### 8. DHCP Client (`/os/libs/DHCP.lua`)
-- ✅ DHCP discovery
-- ✅ IP configuration
-- ✅ DNS resolution (basic)
-
-## Example Applications
-
-### 1. HTTP Server Demo (`/apps/com.luajitos.httpserver/`)
-- Full-featured HTTP server
-- Multiple routes
-- JSON API endpoints
-- HTML serving
-
-### 2. HTTP Client Demo (`/apps/com.luajitos.httpclient/`)
-- GET/POST examples
-- URL parsing tests
-- JSON encoding demos
-
-### 3. Network Test (`/apps/com.luajitos.networktest/`)
-- Comprehensive network stack tests
-- All protocol tests
-- Packet monitoring
-
-### 4. SafeHTTP Test (`/apps/com.luajitos.safehttptest/`)
-- Domain whitelisting tests
-- Callback API demos
-- Security validation
-
-### 5. Weather App (`/apps/com.luajitos.weatherapp/`)
-- Real-world example
-- Sandboxed HTTP usage
-- Best practices demo
-
-### 6. HTTP Sandbox Test (`/apps/com.luajitos.httpsandboxtest/`)
-- Quick integration test
-- Verifies automatic provision
-- API validation
-
-## Documentation
-
-### User Guides
-- **SANDBOXED_HTTP.md** - App developer guide for using http global
-- **HTTP_QUICKSTART.md** - Quick start guide for HTTP library
-
-### Technical References
-- **SAFEHTTP.md** - Complete SafeHTTP API reference
-- **HTTP_LIBRARY.md** - HTTP protocol library documentation
-- **NETWORK_STACK.md** - Network stack architecture and APIs
-
-### Summaries
-- **SANDBOXED_HTTP_SUMMARY.md** - Implementation details
-- **HTTP_IMPLEMENTATION_COMPLETE.md** - This file
-
-## Usage for App Developers
-
-### Step 1: Declare Permissions
-
-```lua
--- manifest.lua
-return {
- name = "My App",
- identifier = "com.dev.myapp",
- version = "1.0.0",
- author = "Developer",
- developer = "Developer",
- description = "My awesome app",
- executable = "/apps/com.dev.myapp/src/main.lua",
-
- -- Request network access
- permissions = {
- network = true,
- },
-
- -- Whitelist allowed domains
- allowedDomains = {
- "api.myservice.com",
- "cdn.myservice.com"
- }
-}
-```
-
-### Step 2: Use HTTP
-
-```lua
--- main.lua
-
--- http is automatically available!
-
-http:get("http://api.myservice.com/data",
- function(response)
- osprint("Success: " .. response.body)
- end,
- function(error_msg)
- osprint("Error: " .. error_msg)
- end
-)
-
--- Poll to process requests
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-That's it! No imports, no setup, just use `http`.
-
-## Security Model
-
-### Three-Layer Security
-
-1. **Permission Declaration** (Manifest)
- - Apps must declare `network` permission
- - Apps must list `allowedDomains`
- - User can review before running
-
-2. **Sandbox Enforcement** (run.lua)
- - Only apps with permission get `http`
- - SafeHTTP created with domain whitelist
- - Isolated per-app instances
-
-3. **Runtime Validation** (SafeHTTP)
- - Every URL validated against whitelist
- - Domain extraction and matching
- - Size and timeout limits
-
-### What's Protected
-
-✅ Domain restriction (whitelist only)
-✅ Response size limits (default 10MB)
-✅ Request timeouts (default 30s)
-✅ Per-app isolation
-✅ Callback error isolation
-✅ No sandbox escape
-
-### What's Not Protected (Yet)
-
-❌ No HTTPS/SSL (plaintext only)
-❌ No rate limiting
-❌ No bandwidth quotas
-❌ No DNS security
-❌ No connection pooling
-
-## Testing
-
-### Quick Test
-
-```bash
-# Run sandbox integration test
-lpm.run("com.luajitos.httpsandboxtest")
-
-# Expected output:
-# Test 1: Check http global exists... PASS
-# Test 2: Check http methods... PASS
-# Test 3: Check allowed domains... PASS (found 2 domains)
-# ...
-# === Test Complete ===
-```
-
-### Full Test Suite
-
-```bash
-# Network stack tests
-lpm.run("com.luajitos.networktest")
-
-# SafeHTTP tests
-lpm.run("com.luajitos.safehttptest")
-
-# HTTP server demo
-lpm.run("com.luajitos.httpserver")
-
-# HTTP client demo
-lpm.run("com.luajitos.httpclient")
-
-# Weather app example
-lpm.run("com.luajitos.weatherapp")
-```
-
-### QEMU Setup
-
-```bash
-# Basic networking
-qemu-system-x86_64 \
- -netdev user,id=net0 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-
-# With HTTP server port forwarding
-qemu-system-x86_64 \
- -netdev user,id=net0,hostfwd=tcp::8080-:8080 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-
-# Then access from host:
-curl http://localhost:8080/
-```
-
-## Performance Characteristics
-
-- **Throughput**: ~2-4 Mbps (TCP limitation)
-- **Latency**: ~10-50ms (local network)
-- **Concurrent Connections**: 1 per app (no multi-threading)
-- **Max Request Size**: Configurable (default 10MB)
-- **Timeout**: Configurable (default 30s)
-
-## Known Limitations
-
-1. **No HTTPS**: All HTTP traffic is plaintext
-2. **Simplified TCP**: No retransmission, congestion control
-3. **No HTTP/2**: Only HTTP/1.1 supported
-4. **No WebSocket**: Not implemented
-5. **No DNS**: Must use IP addresses or known hosts
-6. **Single-threaded**: One request at a time per app
-
-## Future Enhancements
-
-### Priority 1 (Security)
-- [ ] HTTPS/TLS support
-- [ ] Rate limiting per app
-- [ ] Bandwidth quotas
-- [ ] Request logging
-
-### Priority 2 (Features)
-- [ ] HTTP/2 protocol
-- [ ] WebSocket support
-- [ ] Cookie management
-- [ ] Session handling
-- [ ] DNS client
-
-### Priority 3 (Performance)
-- [ ] Connection pooling
-- [ ] Response streaming
-- [ ] Chunked encoding
-- [ ] Compression (gzip)
-
-## Migration Guide
-
-### For Existing Apps
-
-If your app currently uses HTTP library directly:
-
-**Before:**
-```lua
-local HTTP = require("HTTP")
-local client = HTTP.create_client(NetworkStack)
-local response = client.get("http://example.com/")
-```
-
-**After:**
-```lua
--- In manifest.lua:
--- permissions = { network = true }
--- allowedDomains = { "example.com" }
-
--- In main.lua:
-http:get("http://example.com/",
- function(response)
- -- use response
- end
-)
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-### For System Code
-
-System utilities can still use HTTP library directly if needed.
-
-## File Locations
-
-### Core Libraries
-- `/os/libs/RTL8139.lua` - Ethernet driver
-- `/os/libs/NetworkStack.lua` - Network protocols
-- `/os/libs/TCP.lua` - TCP implementation
-- `/os/libs/Socket.lua` - Socket API
-- `/os/libs/HTTP.lua` - HTTP protocol
-- `/os/libs/SafeHTTP.lua` - Sandboxed HTTP
-- `/os/libs/DHCP.lua` - DHCP client
-- `/os/libs/run.lua` - Sandbox integration (modified)
-
-### Example Apps
-- `/apps/com.luajitos.httpserver/` - HTTP server
-- `/apps/com.luajitos.httpclient/` - HTTP client
-- `/apps/com.luajitos.networktest/` - Network tests
-- `/apps/com.luajitos.safehttptest/` - SafeHTTP tests
-- `/apps/com.luajitos.weatherapp/` - Weather app example
-- `/apps/com.luajitos.httpsandboxtest/` - Sandbox integration test
-
-### Documentation
-- `SANDBOXED_HTTP.md` - App developer guide
-- `SAFEHTTP.md` - SafeHTTP reference
-- `HTTP_LIBRARY.md` - HTTP protocol reference
-- `HTTP_QUICKSTART.md` - Quick start
-- `NETWORK_STACK.md` - Network architecture
-- `SANDBOXED_HTTP_SUMMARY.md` - Implementation summary
-- `HTTP_IMPLEMENTATION_COMPLETE.md` - This file
-
-## Credits
-
-Implemented as part of LuajitOS network stack development.
-
-## License
-
-Part of LuajitOS - see main project license.
-
----
-
-## Quick Reference Card
-
-### Manifest Setup
-```lua
-permissions = { network = true },
-allowedDomains = { "api.example.com" }
-```
-
-### GET Request
-```lua
-http:get(url, success_cb, error_cb)
-```
-
-### POST Request
-```lua
-http:post(url, {data="json"}, success_cb, error_cb)
-```
-
-### Poll Loop
-```lua
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-### Domain Check
-```lua
-http:isDomainAllowed("example.com")
-```
-
----
-
-**Status**: ✅ Complete and functional
-**Security**: ✅ Sandboxed with domain whitelist
-**Documentation**: ✅ Comprehensive guides available
-**Examples**: ✅ 6 example applications
-**Testing**: ✅ Full test suite included
-
-The HTTP implementation is ready for production use in LuajitOS applications!
diff --git a/HTTP_LIBRARY.md b/HTTP_LIBRARY.md
@@ -1,703 +0,0 @@
-# HTTP Library Documentation
-
-## Overview
-
-The HTTP library provides complete HTTP/1.1 client and server functionality for LuajitOS. It supports request/response parsing, URL handling, JSON encoding, and both client and server implementations built on top of the TCP/IP stack.
-
-## Features
-
-- **HTTP/1.1 Protocol Support**
-- **Client Implementation** - Make HTTP requests (GET, POST, PUT, DELETE, etc.)
-- **Server Implementation** - Create HTTP servers with routing
-- **URL Parsing** - Parse and manipulate URLs
-- **URL Encoding/Decoding** - Proper percent encoding
-- **Header Management** - Parse and build HTTP headers
-- **JSON Support** - Basic JSON encoding for APIs
-- **Query String Parsing** - Parse URL query parameters
-- **Status Codes** - Complete HTTP status code definitions
-
-## Architecture
-
-```
-┌─────────────────────────────────┐
-│ HTTP Applications │
-│ (Server routes, Client apps) │
-├─────────────────────────────────┤
-│ HTTP Library │
-│ (Parser, Builder, Client/Srv) │
-├─────────────────────────────────┤
-│ Socket API │
-│ (TCP/UDP) │
-├─────────────────────────────────┤
-│ Network Stack │
-│ (IP, TCP, UDP, etc.) │
-└─────────────────────────────────┘
-```
-
-## HTTP Library API
-
-### Constants
-
-#### Status Codes
-```lua
-HTTP.STATUS = {
- OK = 200,
- CREATED = 201,
- NOT_FOUND = 404,
- INTERNAL_SERVER_ERROR = 500,
- -- ... (see full list in code)
-}
-```
-
-#### HTTP Methods
-```lua
-HTTP.METHOD = {
- GET = "GET",
- POST = "POST",
- PUT = "PUT",
- DELETE = "DELETE",
- HEAD = "HEAD",
- OPTIONS = "OPTIONS",
- PATCH = "PATCH",
-}
-```
-
-### URL Functions
-
-#### HTTP.parse_url(url)
-Parse a URL into components.
-
-```lua
-local parsed = HTTP.parse_url("http://example.com:8080/path?query=value")
--- Returns:
-{
- scheme = "http",
- host = "example.com",
- port = 8080,
- path = "/path",
- query = "query=value",
- fragment = nil
-}
-```
-
-**Parameters:**
-- `url` (string): URL to parse
-
-**Returns:**
-- `table` or `nil`: Parsed URL components
-
-#### HTTP.parse_query(query)
-Parse a query string into key-value pairs.
-
-```lua
-local params = HTTP.parse_query("name=John&age=30")
--- Returns: {name = "John", age = "30"}
-```
-
-**Parameters:**
-- `query` (string): Query string
-
-**Returns:**
-- `table`: Key-value pairs
-
-#### HTTP.url_encode(str)
-URL encode a string.
-
-```lua
-local encoded = HTTP.url_encode("Hello World!")
--- Returns: "Hello%20World%21"
-```
-
-**Security Note:** Always encode user input before including in URLs to prevent injection attacks.
-
-#### HTTP.url_decode(str)
-URL decode a string.
-
-```lua
-local decoded = HTTP.url_decode("Hello%20World%21")
--- Returns: "Hello World!"
-```
-
-### Header Functions
-
-#### HTTP.parse_headers(header_str)
-Parse HTTP headers from string.
-
-```lua
-local headers = HTTP.parse_headers("Content-Type: text/html\r\nConnection: close")
--- Returns: {["content-type"] = "text/html", connection = "close"}
-```
-
-**Note:** Header names are converted to lowercase.
-
-#### HTTP.build_headers(headers)
-Build HTTP headers string.
-
-```lua
-local header_str = HTTP.build_headers({
- ["Content-Type"] = "text/html",
- Connection = "close"
-})
-```
-
-### Request/Response Functions
-
-#### HTTP.parse_request(request_str)
-Parse HTTP request.
-
-```lua
-local request = HTTP.parse_request("GET /path HTTP/1.1\r\nHost: example.com\r\n\r\n")
--- Returns:
-{
- method = "GET",
- path = "/path",
- version = "HTTP/1.1",
- headers = {host = "example.com"},
- body = "",
- query = {}
-}
-```
-
-#### HTTP.build_request(method, path, headers, body)
-Build HTTP request string.
-
-```lua
-local request = HTTP.build_request("POST", "/api/data", {
- Host = "example.com",
- ["Content-Type"] = "application/json"
-}, '{"key":"value"}')
-```
-
-**Security Note:** Validates and sets Content-Length automatically.
-
-#### HTTP.parse_response(response_str)
-Parse HTTP response.
-
-```lua
-local response = HTTP.parse_response("HTTP/1.1 200 OK\r\n\r\nBody")
--- Returns:
-{
- version = "HTTP/1.1",
- status = 200,
- reason = "OK",
- headers = {},
- body = "Body"
-}
-```
-
-#### HTTP.build_response(status, headers, body)
-Build HTTP response string.
-
-```lua
-local response = HTTP.build_response(200, {
- ["Content-Type"] = "text/html"
-}, "<html><body>Hello</body></html>")
-```
-
-### JSON Functions
-
-#### HTTP.json_encode(data)
-Encode Lua data to JSON.
-
-```lua
-local json = HTTP.json_encode({
- name = "LuajitOS",
- version = 1.0,
- features = {"http", "tcp"}
-})
--- Returns: '{"name":"LuajitOS","version":1.0,"features":["http","tcp"]}'
-```
-
-**Supports:**
-- nil → `null`
-- boolean → `true`/`false`
-- number → number
-- string → escaped string
-- table (array) → JSON array
-- table (object) → JSON object
-
-**Security Note:** Escapes special characters to prevent JSON injection.
-
-## HTTP Client
-
-### Creating a Client
-
-```lua
-local HTTP = require("HTTP")
-local client = HTTP.create_client(NetworkStack)
-```
-
-### Client Methods
-
-#### client.request(method, url, options)
-Make HTTP request.
-
-```lua
-local response, err = client.request("GET", "http://example.com/", {
- headers = {
- ["User-Agent"] = "LuajitOS/1.0"
- },
- body = nil,
- timeout = 30
-})
-```
-
-**Parameters:**
-- `method` (string): HTTP method
-- `url` (string): Full URL
-- `options` (table, optional):
- - `headers` (table): Custom headers
- - `body` (string): Request body
- - `timeout` (number): Timeout in seconds (default: 30)
-
-**Returns:**
-- `response` (table) or `nil`: Response object
-- `error` (string): Error message if failed
-
-**Response Object:**
-```lua
-{
- version = "HTTP/1.1",
- status = 200,
- reason = "OK",
- headers = {...},
- body = "..."
-}
-```
-
-#### client.get(url, options)
-Convenience method for GET requests.
-
-```lua
-local response = client.get("http://example.com/")
-```
-
-#### client.post(url, body, options)
-Convenience method for POST requests.
-
-```lua
-local response = client.post("http://example.com/api", '{"data":"value"}', {
- headers = {["Content-Type"] = "application/json"}
-})
-```
-
-### Client Example
-
-```lua
--- Initialize network
-local RTL8139 = require("RTL8139")
-local NetworkStack = require("NetworkStack")
-RTL8139.init()
-NetworkStack.init(RTL8139)
-
--- Create client
-local HTTP = require("HTTP")
-local client = HTTP.create_client(NetworkStack)
-
--- Make GET request
-local response = client.get("http://10.0.2.2/index.html")
-if response then
- print("Status:", response.status)
- print("Body:", response.body)
-end
-
--- Make POST request
-local response = client.post("http://10.0.2.2/api", '{"key":"value"}', {
- headers = {
- ["Content-Type"] = "application/json",
- ["Authorization"] = "Bearer token123"
- }
-})
-```
-
-### Security Considerations - Client
-
-1. **URL Validation**: Always validate URLs before making requests
-2. **Timeout**: Set appropriate timeouts to prevent hanging
-3. **Header Injection**: Sanitize user input in headers
-4. **SSL/TLS**: Not implemented - all traffic is plaintext
-5. **Redirects**: Not automatically followed - prevents redirect loops
-
-## HTTP Server
-
-### Creating a Server
-
-```lua
-local HTTP = require("HTTP")
-local server = HTTP.create_server(NetworkStack, 8080)
-```
-
-**Parameters:**
-- `NetworkStack` (table): Network stack instance
-- `port` (number, optional): Port to listen on (default: 80)
-
-### Server Methods
-
-#### server.route(method, path, handler)
-Register a route handler.
-
-```lua
-server.route("GET", "/api/users", function(request, response)
- response.json({
- users = {"Alice", "Bob"}
- })
-end)
-```
-
-**Parameters:**
-- `method` (string): HTTP method
-- `path` (string): URL path (supports wildcards with `*`)
-- `handler` (function): Handler function(request, response)
-
-**Request Object:**
-```lua
-{
- method = "GET",
- path = "/api/users",
- version = "HTTP/1.1",
- headers = {...},
- body = "...",
- query = {...} -- Parsed query parameters
-}
-```
-
-**Response Object Methods:**
-- `response.send(body, status)` - Send response
-- `response.json(data)` - Send JSON response
-- `response.html(html)` - Send HTML response
-
-**Response Object Fields:**
-- `response.status` - HTTP status code
-- `response.headers` - Response headers
-- `response.body` - Response body
-
-#### server.start()
-Start the HTTP server.
-
-```lua
-local success, err = server.start()
-if success then
- print("Server started!")
-else
- print("Error:", err)
-end
-```
-
-#### server.stop()
-Stop the HTTP server.
-
-```lua
-server.stop()
-```
-
-### Server Example
-
-```lua
--- Initialize network
-local RTL8139 = require("RTL8139")
-local NetworkStack = require("NetworkStack")
-RTL8139.init()
-NetworkStack.init(RTL8139)
-
--- Create server
-local HTTP = require("HTTP")
-local server = HTTP.create_server(NetworkStack, 8080)
-
--- Define routes
-server.route("GET", "/", function(req, res)
- res.html([[
- <!DOCTYPE html>
- <html>
- <body>
- <h1>Welcome to LuajitOS!</h1>
- </body>
- </html>
- ]])
-end)
-
-server.route("GET", "/api/status", function(req, res)
- res.json({
- status = "ok",
- uptime = os.time()
- })
-end)
-
-server.route("POST", "/api/data", function(req, res)
- -- Echo back the received data
- res.json({
- received = req.body,
- length = #req.body
- })
-end)
-
--- Wildcard route
-server.route("GET", "/files/*", function(req, res)
- local filename = req.path:match("/files/(.+)")
- res.send("File: " .. filename)
-end)
-
--- Start server
-server.start()
-
--- Keep running
-while server.running do
- RTL8139.poll()
-end
-```
-
-### Security Considerations - Server
-
-1. **Input Validation**: Always validate request data
-2. **Path Traversal**: Sanitize file paths to prevent directory traversal
-3. **Request Size Limits**: Not implemented - vulnerable to large requests
-4. **Rate Limiting**: Not implemented - vulnerable to DoS
-5. **Authentication**: Implement custom auth in route handlers
-6. **Error Handling**: Use pcall to prevent crashes from handler errors
-7. **SQL Injection**: No database, but sanitize any data storage
-8. **XSS**: Escape HTML output when displaying user input
-
-**Example Secure Handler:**
-```lua
-server.route("POST", "/api/comment", function(req, res)
- -- Validate input
- if not req.body or #req.body > 1024 then
- res.status = 400
- res.send("Invalid input")
- return
- end
-
- -- Sanitize HTML (basic example)
- local safe_comment = req.body:gsub("<", "<"):gsub(">", ">")
-
- -- Store comment securely
- -- ...
-
- res.json({success = true})
-end)
-```
-
-## Complete Examples
-
-### Simple Web Server
-
-```lua
--- web_server.lua
-local HTTP = require("HTTP")
-local NetworkStack = require("NetworkStack")
-
--- Initialize
--- ... (network init code)
-
-local server = HTTP.create_server(NetworkStack, 80)
-
--- Serve static content
-local pages = {
- ["/"] = "<h1>Home Page</h1>",
- ["/about"] = "<h1>About Us</h1>",
-}
-
-server.route("GET", "*", function(req, res)
- local content = pages[req.path]
- if content then
- res.html(content)
- else
- res.status = 404
- res.html("<h1>404 Not Found</h1>")
- end
-end)
-
-server.start()
-while server.running do
- NetworkStack.RTL8139.poll()
-end
-```
-
-### REST API Server
-
-```lua
--- api_server.lua
-local HTTP = require("HTTP")
-
--- Data store
-local users = {
- {id = 1, name = "Alice"},
- {id = 2, name = "Bob"}
-}
-
-local server = HTTP.create_server(NetworkStack, 8080)
-
--- List users
-server.route("GET", "/api/users", function(req, res)
- res.json({users = users})
-end)
-
--- Get user by ID
-server.route("GET", "/api/users/*", function(req, res)
- local id = tonumber(req.path:match("/api/users/(%d+)"))
- for _, user in ipairs(users) do
- if user.id == id then
- res.json(user)
- return
- end
- end
- res.status = 404
- res.json({error = "User not found"})
-end)
-
--- Create user
-server.route("POST", "/api/users", function(req, res)
- -- Parse JSON body (simplified)
- local new_user = {
- id = #users + 1,
- name = req.body -- Should parse JSON properly
- }
- table.insert(users, new_user)
- res.status = 201
- res.json(new_user)
-end)
-
-server.start()
-```
-
-### HTTP Client Scraper
-
-```lua
--- scraper.lua
-local HTTP = require("HTTP")
-
-local client = HTTP.create_client(NetworkStack)
-
--- Fetch multiple pages
-local urls = {
- "http://10.0.2.2/page1.html",
- "http://10.0.2.2/page2.html",
-}
-
-for _, url in ipairs(urls) do
- print("Fetching:", url)
- local response = client.get(url, {timeout = 10})
-
- if response and response.status == 200 then
- print("Success! Size:", #response.body)
- -- Process response.body
- else
- print("Failed:", url)
- end
-end
-```
-
-## Testing
-
-### Running HTTP Server Demo
-
-```bash
-# From LuajitOS shell
-lpm.run("com.luajitos.httpserver")
-
-# From host, test with curl
-curl http://10.0.2.15:8080/
-curl http://10.0.2.15:8080/api/status
-```
-
-### Running HTTP Client Demo
-
-```bash
-# From LuajitOS shell
-lpm.run("com.luajitos.httpclient")
-```
-
-### QEMU Setup for HTTP
-
-```bash
-# With port forwarding for HTTP server
-qemu-system-x86_64 \
- -netdev user,id=net0,hostfwd=tcp::8080-:8080 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-```
-
-Then access from host: `http://localhost:8080/`
-
-## Limitations
-
-1. **No SSL/TLS** - All traffic is plaintext
-2. **Simplified TCP** - Based on basic TCP implementation
-3. **No Keep-Alive** - Connections close after each request
-4. **No Chunked Encoding** - Only supports Content-Length
-5. **No Compression** - No gzip/deflate support
-6. **Basic JSON** - Limited JSON encoding (no decode)
-7. **No DNS** - Must use IP addresses or localhost
-8. **No HTTP/2** - Only HTTP/1.1
-
-## Performance
-
-- **Throughput**: ~2-4 Mbps (TCP limitation)
-- **Concurrent Connections**: 1 (no multi-threading)
-- **Request Latency**: ~10-50ms (local network)
-- **Max Request Size**: Limited by TCP buffer (1536 bytes)
-
-## Future Enhancements
-
-- [ ] HTTPS/TLS support
-- [ ] HTTP/2 protocol
-- [ ] WebSocket support
-- [ ] Multipart form data
-- [ ] Cookie management
-- [ ] Session handling
-- [ ] Template engine
-- [ ] Static file serving
-- [ ] Middleware support
-- [ ] Request/response streaming
-- [ ] Connection pooling
-- [ ] DNS integration
-- [ ] JSON decoding
-- [ ] XML support
-
-## Troubleshooting
-
-### Server not receiving requests
-- Check firewall rules on host
-- Verify port forwarding in QEMU
-- Ensure NetworkStack is initialized
-- Check server is actually started
-
-### Client timeout
-- Verify target server is reachable
-- Check IP address is correct
-- Increase timeout value
-- Use tcpdump to debug packets
-
-### Invalid response parsing
-- Check HTTP format is correct
-- Ensure \r\n line endings
-- Verify Content-Length matches body
-
-## Security Best Practices
-
-1. **Input Validation**: Always validate and sanitize user input
-2. **Output Encoding**: Escape output to prevent XSS
-3. **Authentication**: Implement proper auth for sensitive endpoints
-4. **Rate Limiting**: Add custom rate limiting for DoS protection
-5. **HTTPS**: Use HTTPS for production (when available)
-6. **Error Messages**: Don't expose internal details in errors
-7. **Path Traversal**: Validate file paths carefully
-8. **SQL Injection**: Use parameterized queries (if database added)
-
-## API Reference Summary
-
-| Function | Description |
-|----------|-------------|
-| `HTTP.parse_url()` | Parse URL string |
-| `HTTP.url_encode()` | URL encode string |
-| `HTTP.url_decode()` | URL decode string |
-| `HTTP.parse_request()` | Parse HTTP request |
-| `HTTP.build_request()` | Build HTTP request |
-| `HTTP.parse_response()` | Parse HTTP response |
-| `HTTP.build_response()` | Build HTTP response |
-| `HTTP.json_encode()` | Encode to JSON |
-| `HTTP.create_client()` | Create HTTP client |
-| `HTTP.create_server()` | Create HTTP server |
-
-## License
-
-Part of LuajitOS - see main project license.
diff --git a/HTTP_QUICKSTART.md b/HTTP_QUICKSTART.md
@@ -1,351 +0,0 @@
-# HTTP Library Quick Start Guide
-
-## Installation
-
-The HTTP library is located at `/os/libs/HTTP.lua` and is ready to use.
-
-## 5-Minute Quick Start
-
-### HTTP Client - Make a GET Request
-
-```lua
--- Load libraries
-local RTL8139 = require("RTL8139")
-local NetworkStack = require("NetworkStack")
-local HTTP = require("HTTP")
-
--- Initialize network
-RTL8139.init()
-NetworkStack.init(RTL8139)
-
--- Create client and make request
-local client = HTTP.create_client(NetworkStack)
-local response = client.get("http://10.0.2.2/index.html")
-
-if response then
- print("Status:", response.status)
- print("Body:", response.body)
-end
-```
-
-### HTTP Server - Simple Web Server
-
-```lua
--- Load libraries
-local RTL8139 = require("RTL8139")
-local NetworkStack = require("NetworkStack")
-local HTTP = require("HTTP")
-
--- Initialize network
-RTL8139.init()
-NetworkStack.init(RTL8139)
-
--- Create server
-local server = HTTP.create_server(NetworkStack, 8080)
-
--- Add routes
-server.route("GET", "/", function(req, res)
- res.html("<h1>Hello from LuajitOS!</h1>")
-end)
-
-server.route("GET", "/api/status", function(req, res)
- res.json({status = "ok", version = "1.0"})
-end)
-
--- Start server
-server.start()
-
--- Keep running
-while server.running do
- RTL8139.poll()
-end
-```
-
-## Common Use Cases
-
-### 1. Fetch JSON API
-
-```lua
-local client = HTTP.create_client(NetworkStack)
-local response = client.get("http://api.example.com/data")
-
-if response and response.status == 200 then
- -- response.body contains JSON string
- print(response.body)
-end
-```
-
-### 2. POST JSON Data
-
-```lua
-local client = HTTP.create_client(NetworkStack)
-local json_data = HTTP.json_encode({name = "John", age = 30})
-
-local response = client.post("http://api.example.com/users", json_data, {
- headers = {
- ["Content-Type"] = "application/json"
- }
-})
-```
-
-### 3. Build REST API
-
-```lua
-local server = HTTP.create_server(NetworkStack, 8080)
-
--- List resources
-server.route("GET", "/api/items", function(req, res)
- res.json({items = {"item1", "item2"}})
-end)
-
--- Get single resource
-server.route("GET", "/api/items/*", function(req, res)
- local id = req.path:match("/api/items/(%d+)")
- res.json({id = id, name = "Item " .. id})
-end)
-
--- Create resource
-server.route("POST", "/api/items", function(req, res)
- -- req.body contains the posted data
- res.status = 201
- res.json({created = true})
-end)
-
-server.start()
-```
-
-### 4. Serve Static HTML
-
-```lua
-local server = HTTP.create_server(NetworkStack, 80)
-
-local pages = {
- ["/"] = [[
- <!DOCTYPE html>
- <html>
- <body>
- <h1>Home</h1>
- <a href="/about">About</a>
- </body>
- </html>
- ]],
- ["/about"] = [[
- <!DOCTYPE html>
- <html>
- <body>
- <h1>About</h1>
- <a href="/">Home</a>
- </body>
- </html>
- ]]
-}
-
-server.route("GET", "*", function(req, res)
- local page = pages[req.path]
- if page then
- res.html(page)
- else
- res.status = 404
- res.html("<h1>404 - Page Not Found</h1>")
- end
-end)
-
-server.start()
-```
-
-### 5. Handle Form Data
-
-```lua
-server.route("POST", "/submit", function(req, res)
- -- Parse query-string encoded form data
- local form_data = HTTP.parse_query(req.body)
-
- -- Access form fields
- local username = form_data.username
- local email = form_data.email
-
- -- Process and respond
- res.html("<h1>Thanks " .. username .. "!</h1>")
-end)
-```
-
-### 6. Custom Headers
-
-```lua
--- Client with custom headers
-local response = client.get("http://example.com/", {
- headers = {
- ["User-Agent"] = "LuajitOS Bot/1.0",
- ["Authorization"] = "Bearer YOUR_TOKEN",
- ["Accept"] = "application/json"
- }
-})
-
--- Server with custom headers
-server.route("GET", "/download", function(req, res)
- res.headers["Content-Disposition"] = "attachment; filename=data.txt"
- res.headers["Content-Type"] = "text/plain"
- res.send("File contents here")
-end)
-```
-
-### 7. Error Handling
-
-```lua
--- Client error handling
-local response, err = client.get("http://example.com/")
-if not response then
- print("Error:", err)
- return
-end
-
-if response.status == 404 then
- print("Page not found")
-elseif response.status >= 500 then
- print("Server error")
-end
-
--- Server error handling
-server.route("GET", "/api/data", function(req, res)
- local success, result = pcall(function()
- -- Your code that might fail
- return get_sensitive_data()
- end)
-
- if not success then
- res.status = 500
- res.json({error = "Internal error"})
- else
- res.json({data = result})
- end
-end)
-```
-
-## Running Demo Applications
-
-### HTTP Server Demo
-```lua
-lpm.run("com.luajitos.httpserver")
-```
-
-Access from host:
-```bash
-curl http://10.0.2.15:8080/
-curl http://10.0.2.15:8080/api/status
-```
-
-### HTTP Client Demo
-```lua
-lpm.run("com.luajitos.httpclient")
-```
-
-## Utility Functions Cheat Sheet
-
-```lua
--- URL parsing
-local parsed = HTTP.parse_url("http://example.com:8080/path?key=value")
--- parsed.scheme, parsed.host, parsed.port, parsed.path, parsed.query
-
--- URL encoding
-local encoded = HTTP.url_encode("Hello World!") -- "Hello%20World%21"
-local decoded = HTTP.url_decode("Hello%20World%21") -- "Hello World!"
-
--- Query parsing
-local params = HTTP.parse_query("name=John&age=30")
--- params.name = "John", params.age = "30"
-
--- JSON encoding
-local json = HTTP.json_encode({key = "value", num = 42})
--- '{"key":"value","num":42}'
-
--- Build request
-local req = HTTP.build_request("GET", "/path", {Host = "example.com"})
-
--- Build response
-local res = HTTP.build_response(200, {["Content-Type"] = "text/html"}, "<h1>Hi</h1>")
-```
-
-## Testing with QEMU
-
-### Basic networking:
-```bash
-qemu-system-x86_64 \
- -netdev user,id=net0 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-```
-
-### With port forwarding (access server from host):
-```bash
-qemu-system-x86_64 \
- -netdev user,id=net0,hostfwd=tcp::8080-:8080 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-```
-
-Then: `curl http://localhost:8080/`
-
-## Common Issues
-
-**Q: Client timeout**
-- Increase timeout: `client.get(url, {timeout = 60})`
-- Check network connectivity
-- Verify target server is running
-
-**Q: Server not receiving requests**
-- Check QEMU port forwarding is configured
-- Verify server started successfully
-- Use correct IP address (10.0.2.15 in QEMU user network)
-
-**Q: Response body empty**
-- Wait for connection close
-- Check Content-Length header
-- Poll network more frequently
-
-**Q: JSON encoding fails**
-- Check for circular references in tables
-- Ensure data types are supported
-- Use proper table structure (array vs object)
-
-## Performance Tips
-
-1. **Reuse client instances** - Don't create new client for each request
-2. **Poll frequently** - Call `RTL8139.poll()` regularly
-3. **Set appropriate timeouts** - Balance responsiveness vs reliability
-4. **Limit response sizes** - Large responses may timeout
-5. **Use Connection: close** - Simplifies connection management
-
-## Security Checklist
-
-- [ ] Validate all user input
-- [ ] Escape HTML output (use `:gsub("<", "<"):gsub(">", ">")`)
-- [ ] Set appropriate timeouts
-- [ ] Limit request sizes
-- [ ] Don't expose error details to users
-- [ ] Validate file paths (prevent `../` traversal)
-- [ ] Use HTTPS for sensitive data (when available)
-- [ ] Implement authentication for protected endpoints
-
-## Next Steps
-
-- Read full documentation: `HTTP_LIBRARY.md`
-- Check network stack docs: `NETWORK_STACK.md`
-- Explore example apps in `/apps/com.luajitos.http*/`
-- Build your own HTTP application!
-
-## Quick Reference Card
-
-| Task | Code |
-|------|------|
-| GET request | `client.get(url)` |
-| POST request | `client.post(url, body)` |
-| Create server | `HTTP.create_server(NetworkStack, port)` |
-| Add route | `server.route(method, path, handler)` |
-| Start server | `server.start()` |
-| Send HTML | `response.html(html)` |
-| Send JSON | `response.json(data)` |
-| Parse URL | `HTTP.parse_url(url)` |
-| Encode JSON | `HTTP.json_encode(data)` |
-| URL encode | `HTTP.url_encode(str)` |
-
-Happy coding! 🚀
diff --git a/IMAGE_DECODER_README.md b/IMAGE_DECODER_README.md
@@ -1,557 +0,0 @@
-# Image Decoder System
-
-LuajitOS now includes a comprehensive image decoding system with support for BMP images and a framework for PNG support.
-
-## Features
-
-### Supported Formats
-
-#### BMP (Fully Supported ✅)
-- **24-bit RGB** and **32-bit RGBA**
-- Uncompressed format
-- Top-down and bottom-up orientations
-- Encoding and decoding
-
-#### PNG (Fully Supported ✅)
-- Structure parsing implemented
-- **Deflate decompression working**
-- RGB, RGBA, Grayscale support
-- 8-bit depth images
-
-### Image Operations
-
-- **Loading**: Decode from memory
-- **Scaling**: Nearest neighbor and bilinear interpolation
-- **Modes**: Fit, Fill, Cover (aspect ratio preservation)
-- **Rotation**: 90°, 180°, 270° clockwise/counter-clockwise
-- **Flipping**: Horizontal and vertical
-- **Drawing**: To both VGA and VESA framebuffers
-
-## API Reference
-
-### Loading Images
-
-```lua
--- Load BMP from memory (data is a string containing the BMP file)
-local img = BMPLoad(bmp_data)
-if img then
- print("Image loaded!")
-else
- print("Failed to load image")
-end
-
--- Load PNG (now working!)
-local img = PNGLoad(png_data)
-if img then
- print("PNG loaded successfully!")
-else
- print("Failed to load PNG")
-end
-```
-
-### Drawing Images
-
-```lua
--- Draw image at position (x, y)
-ImageDraw(img, 100, 100)
-
--- Draw with scaling
--- SCALE_NEAREST = 0 (fast, pixelated)
--- SCALE_BILINEAR = 1 (smooth, slower)
-ImageDrawScaled(img, 50, 50, 200, 150, 0) -- Nearest neighbor
-ImageDrawScaled(img, 50, 50, 200, 150, 1) -- Bilinear
-```
-
-### Image Information
-
-```lua
--- Get image properties
-local info = ImageGetInfo(img)
-print("Width: " .. info.width)
-print("Height: " .. info.height)
-print("BPP: " .. info.bpp)
-print("Has Alpha: " .. tostring(info.hasAlpha))
-```
-
-### Rotation
-
-```lua
--- Rotate image
-local rotated = ImageRotate(img, angle)
-
--- Supported angles:
--- 0 = No rotation (returns copy)
--- 90 = 90 degrees clockwise
--- 180 = 180 degrees (upside down)
--- 270 = 270 degrees clockwise (90 counter-clockwise)
--- -90 = 90 degrees counter-clockwise
-
--- Example: Rotate 90 degrees clockwise
-local img = BMPLoad(data)
-local rotated = ImageRotate(img, 90)
-if rotated then
- ImageDraw(rotated, 0, 0)
- ImageDestroy(rotated)
-end
-ImageDestroy(img)
-```
-
-**Important**: `ImageRotate()` creates a **new image**. You must destroy both the original and rotated images to avoid memory leaks.
-
-### Cleanup
-
-```lua
--- Free image memory when done
-ImageDestroy(img)
-```
-
-## Scaling Modes
-
-### SCALE_NEAREST (0) - Nearest Neighbor
-- **Speed**: Very fast
-- **Quality**: Pixelated, blocky
-- **Use case**: Pixel art, retro games
-
-```lua
-ImageDrawScaled(img, x, y, width, height, 0)
-```
-
-### SCALE_BILINEAR (1) - Bilinear Interpolation
-- **Speed**: Slower
-- **Quality**: Smooth, anti-aliased
-- **Use case**: Photos, modern graphics
-
-```lua
-ImageDrawScaled(img, x, y, width, height, 1)
-```
-
-### SCALE_FIT (2) - Fit to Dimensions
-- Maintains aspect ratio
-- Fits inside dimensions (may have borders)
-
-```lua
-ImageDrawScaled(img, x, y, width, height, 2)
-```
-
-### SCALE_FILL (3) - Fill Dimensions
-- May stretch image
-- Fills entire area
-
-```lua
-ImageDrawScaled(img, x, y, width, height, 3)
-```
-
-### SCALE_COVER (4) - Cover Dimensions
-- Maintains aspect ratio
-- Covers entire area (may crop)
-
-```lua
-ImageDrawScaled(img, x, y, width, height, 4)
-```
-
-## Rotation Examples
-
-### Basic Rotation
-
-```lua
--- Load an image
-local img = BMPLoad(image_data)
-if not img then
- print("Failed to load image")
- return
-end
-
--- Rotate 90 degrees clockwise
-local rotated_90 = ImageRotate(img, 90)
-
--- Rotate 180 degrees (flip upside down)
-local rotated_180 = ImageRotate(img, 180)
-
--- Rotate 270 degrees clockwise (same as -90, or 90 CCW)
-local rotated_270 = ImageRotate(img, 270)
-
--- Draw all rotations
-ImageDraw(img, 0, 0) -- Original
-ImageDraw(rotated_90, 200, 0) -- 90° CW
-ImageDraw(rotated_180, 400, 0) -- 180°
-ImageDraw(rotated_270, 600, 0) -- 270° CW
-
--- Clean up
-ImageDestroy(img)
-ImageDestroy(rotated_90)
-ImageDestroy(rotated_180)
-ImageDestroy(rotated_270)
-```
-
-### Rotate and Scale
-
-```lua
--- Load image
-local img = BMPLoad(logo_data)
-
--- Rotate 45... wait, we only support 90° increments!
--- So rotate 90° and scale to desired size
-local rotated = ImageRotate(img, 90)
-
--- Scale the rotated image
-ImageDrawScaled(rotated, 100, 100, 200, 200, 1) -- Bilinear
-
--- Cleanup
-ImageDestroy(img)
-ImageDestroy(rotated)
-```
-
-### Interactive Rotation
-
-```lua
--- Rotate image based on user input
-local angles = {0, 90, 180, 270}
-local current_angle_index = 1
-
-function rotate_image()
- local img = BMPLoad(data)
- local angle = angles[current_angle_index]
-
- if angle == 0 then
- ImageDraw(img, 0, 0)
- ImageDestroy(img)
- else
- local rotated = ImageRotate(img, angle)
- ImageDraw(rotated, 0, 0)
- ImageDestroy(rotated)
- ImageDestroy(img)
- end
-end
-
--- User presses key to rotate
-function on_key_press()
- current_angle_index = (current_angle_index % 4) + 1
- rotate_image()
-end
-```
-
-### Sprite Sheet Rotation
-
-```lua
--- Rotate all sprites in different directions
-local sprite = BMPLoad(character_sprite)
-
-local sprite_up = ImageRotate(sprite, 0) -- Original
-local sprite_right = ImageRotate(sprite, 90) -- Facing right
-local sprite_down = ImageRotate(sprite, 180) -- Facing down
-local sprite_left = ImageRotate(sprite, 270) -- Facing left
-
--- Draw character facing different directions
-function draw_character(x, y, direction)
- if direction == "up" then
- ImageDraw(sprite_up, x, y)
- elseif direction == "right" then
- ImageDraw(sprite_right, x, y)
- elseif direction == "down" then
- ImageDraw(sprite_down, x, y)
- elseif direction == "left" then
- ImageDraw(sprite_left, x, y)
- end
-end
-
--- Later, cleanup
-ImageDestroy(sprite)
-ImageDestroy(sprite_up)
-ImageDestroy(sprite_right)
-ImageDestroy(sprite_down)
-ImageDestroy(sprite_left)
-```
-
-## Complete Example
-
-```lua
--- Load graphics library
-local gfx = require("os.libs.graphicslib")
-
--- Initialize VESA mode for high resolution
-gfx.initVESA(1024, 768, 32)
-
--- Load a BMP image (assume we have the data)
-local bmp_data = read_file("/images/logo.bmp")
-local img = BMPLoad(bmp_data)
-
-if img then
- -- Get image info
- local info = ImageGetInfo(img)
- print("Loaded: " .. info.width .. "x" .. info.height)
-
- -- Draw original size
- ImageDraw(img, 10, 10)
-
- -- Draw scaled (fit to 200x200, smooth)
- ImageDrawScaled(img, 250, 10, 200, 200, 1)
-
- -- Draw scaled (cover 300x300, nearest neighbor for pixel art)
- ImageDrawScaled(img, 500, 10, 300, 300, 0)
-
- -- Cleanup
- ImageDestroy(img)
-end
-
--- Wait or continue with other rendering
-```
-
-## Creating BMP Images
-
-### Save Screenshots
-
-```lua
--- Create an image from screen capture (would need implementation)
--- local screen_img = capture_screen()
-
--- Save as BMP
--- local bmp_data = BMPSave(screen_img)
--- write_file("/screenshots/capture.bmp", bmp_data)
-```
-
-## BMP File Format Support
-
-### Supported Features ✅
-- 24-bit RGB (8 bits per channel)
-- 32-bit RGBA (with alpha channel)
-- Uncompressed (BI_RGB)
-- Top-down and bottom-up DIBs
-- Proper row padding
-
-### Not Supported ❌
-- RLE compression (BI_RLE8, BI_RLE4)
-- Indexed color (palette-based)
-- 16-bit color (RGB555, RGB565)
-- Bit field encoding (BI_BITFIELDS)
-
-### Recommendations
-- Use 24-bit or 32-bit BMP files
-- Save as **uncompressed** in image editors
-- Most modern BMP exporters create compatible files
-
-## PNG Support ✅
-
-PNG support is now **fully working** using the integrated deflate compression!
-
-### What's Supported
-
-- ✅ **RGB Images** (color_type=2)
-- ✅ **RGBA Images** (color_type=6) with alpha channel
-- ✅ **Grayscale** (color_type=0)
-- ✅ **Grayscale + Alpha** (color_type=4)
-- ✅ **8-bit depth** images
-- ✅ **Deflate decompression** for IDAT chunks
-- ✅ **Standard PNG files** from any source
-
-### Current Limitations
-
-- Filter type 0 (None) only - other filters need implementation
-- 8-bit depth only (no 16-bit or indexed color yet)
-- No interlacing support (Adam7)
-- No palette support (indexed color)
-
-### PNG Examples
-
-```lua
--- Load and display PNG
-local png_data = read_file("/images/logo.png")
-local img = PNGLoad(png_data)
-
-if img then
- local info = ImageGetInfo(img)
- print("PNG: " .. info.width .. "x" .. info.height)
- print("Has alpha: " .. tostring(info.hasAlpha))
-
- -- Draw it
- ImageDraw(img, 100, 100)
-
- ImageDestroy(img)
-else
- print("Failed to load PNG")
-end
-```
-
-## Performance Tips
-
-### 1. Use Nearest Neighbor for Real-Time
-```lua
--- Fast scaling for games
-ImageDrawScaled(sprite, x, y, w, h, 0)
-```
-
-### 2. Pre-scale Images
-```lua
--- Scale once, draw many times
-local scaled = image_scale(img, 64, 64, 0)
--- Draw scaled multiple times (faster)
-```
-
-### 3. Batch Drawing
-```lua
-gfx.buffer.enable = true
-
--- Draw many images
-for i = 1, 100 do
- ImageDraw(img, positions[i].x, positions[i].y)
-end
-
--- Render all at once
-gfx.buffer.drawAll()
-```
-
-### 4. Use Appropriate Formats
-- **BMP**: Simple, fast decode, larger files
-- **PNG** (when integrated): Compressed, smaller files, slower decode
-
-## Common Use Cases
-
-### Game Sprites
-
-```lua
--- Load sprite sheet
-local sheet = BMPLoad(sprite_data)
-
--- Draw individual sprites by region (would need crop function)
--- For now, create separate BMP files for each sprite
-local player = BMPLoad(player_sprite_data)
-ImageDraw(player, player_x, player_y)
-```
-
-### Background Images
-
-```lua
--- Full-screen background
-local bg = BMPLoad(background_data)
-ImageDrawScaled(bg, 0, 0, gfx.WIDTH, gfx.HEIGHT, 1) -- Bilinear for quality
-```
-
-### UI Elements
-
-```lua
--- Load button
-local button = BMPLoad(button_data)
-
--- Draw at various sizes
-ImageDrawScaled(button, 10, 10, 100, 40, 0) -- Small
-ImageDrawScaled(button, 120, 10, 150, 60, 0) -- Medium
-```
-
-### Thumbnails
-
-```lua
--- Generate thumbnail with aspect ratio
-local thumb = BMPLoad(photo_data)
-ImageDrawScaled(thumb, x, y, 128, 128, 2) -- SCALE_FIT preserves aspect
-```
-
-## Memory Management
-
-**Important**: Always destroy images when done!
-
-```lua
-local img = BMPLoad(data)
-if img then
- ImageDraw(img, 0, 0)
- ImageDestroy(img) -- Free memory
-end
-```
-
-### Memory Leaks
-
-```lua
--- BAD: Memory leak
-for i = 1, 100 do
- local img = BMPLoad(data)
- ImageDraw(img, 0, 0)
- -- Missing ImageDestroy!
-end
-
--- GOOD: Proper cleanup
-for i = 1, 100 do
- local img = BMPLoad(data)
- if img then
- ImageDraw(img, 0, 0)
- ImageDestroy(img)
- end
-end
-```
-
-## Limitations
-
-1. **No filesystem yet**: Images must be embedded or loaded from ramdisk
-2. **No cropping**: Cropping not yet implemented
-3. **90° rotation only**: Only 90, 180, 270 degree rotations (no arbitrary angles)
-4. **No JPEG**: Would require libjpeg or stb_image
-5. **Memory intensive**: Large images use significant RAM
-
-## Future Enhancements
-
-Potential additions:
-- [ ] Image cropping
-- [x] Rotation (90°, 180°, 270°) ✅ **Implemented!**
-- [ ] Arbitrary angle rotation (using bilinear sampling)
-- [ ] Alpha blending modes
-- [ ] Color filters
-- [ ] JPEG support (via stb_image)
-- [ ] GIF support (animated)
-- [ ] Sprite sheet utilities
-- [ ] Image composition
-- [ ] Text rendering on images
-
-## Troubleshooting
-
-### "Failed to decode BMP"
-- Ensure file is valid BMP format
-- Check it's 24-bit or 32-bit (not indexed color)
-- Verify it's uncompressed (no RLE)
-
-### Image appears corrupted
-- Check byte order (BMP is little-endian)
-- Verify data size matches file size
-- Ensure complete data was loaded
-
-### Out of memory
-- Destroy images when done
-- Use smaller images
-- Scale down before displaying
-
-### PNG not working
-- Expected! Requires zlib integration
-- Use BMP format instead
-- Or integrate stb_image.h (recommended)
-
-## Technical Details
-
-### Image Structure
-
-```c
-typedef struct {
- uint32_t width; // Width in pixels
- uint32_t height; // Height in pixels
- uint8_t bpp; // Bits per pixel (8, 24, 32)
- uint8_t* data; // RGB(A) pixel data
- uint32_t data_size; // Size in bytes
- int has_alpha; // Alpha channel present
-} image_t;
-```
-
-### Memory Layout
-
-Pixels are stored as:
-- **24-bit**: RGB RGB RGB... (3 bytes per pixel)
-- **32-bit**: RGBA RGBA RGBA... (4 bytes per pixel)
-- Row-major order (left-to-right, top-to-bottom)
-
-### Color Format
-
-Both VGA and VESA modes are supported:
-- **VGA**: Converts RGB to 256-color palette (6-8-5 levels)
-- **VESA**: Uses native RGB framebuffer
-
-## Files
-
-- `decoder.h/c` - Common image operations
-- `decoder_BMP.h/c` - BMP codec
-- `decoder_PNG.h/c` - PNG framework (needs zlib)
-
-Build with: `./build.sh`
diff --git a/IMAGE_LIBRARIES_README.md b/IMAGE_LIBRARIES_README.md
@@ -1,313 +0,0 @@
-# Image Libraries - Usage Guide
-
-## Overview
-
-LuajitOS provides two image manipulation libraries:
-
-- **Image** - Static image creation, loading (PNG/BMP), and manipulation
-- **AnimatedImage** - Animated GIF creation with frame-based editing
-
-## Important: Loading Order
-
-These libraries depend on ramdisk functions (`CRamdiskExists`, `CRamdiskOpen`, etc.) which are only available after the system has fully initialized.
-
-**Do NOT load these libraries at module scope** in system files. Always load them inside functions after the OS has started.
-
-### ❌ Wrong (will cause errors):
-```lua
--- At top of file (module scope)
-local Image = require("Image") -- ERROR: CRamdiskExists not yet defined
-
-function myFunction()
- local img = Image.new(100, 100)
-end
-```
-
-### ✅ Correct:
-```lua
--- Inside function (after OS init)
-function myFunction()
- local Image = require("Image") -- OK: ramdisk functions available
- local img = Image.new(100, 100)
-end
-```
-
-## Libraries
-
-### Image Library (`/os/libs/Image.lua`)
-
-Static image manipulation with PNG and BMP support.
-
-**Features:**
-- Create blank images
-- Load PNG and BMP files
-- Pixel-level manipulation
-- Drawing primitives (fill, rect, line)
-- Alpha blending compositing
-- Save as PNG (with compression) or BMP
-
-**Quick Example:**
-```lua
-local Image = require("Image")
-
-local img = Image.new(200, 200)
-img:fill({r = 255, g = 200, b = 150})
-
-local logo = Image.open("/home/logo.png")
-img:addImage(logo, 50, 50, 100, 100, 0.8)
-
-img:saveAsPNG("/home/output.png", { compression = true })
-```
-
-**Documentation:** See `IMAGE_LIBRARY.md`
-
-### AnimatedImage Library (`/os/libs/AnimatedImage.lua`)
-
-Animated GIF creation with frame-based editing.
-
-**Features:**
-- Create multi-frame animations
-- Each frame is a full `Image` object
-- Direct frame array access
-- Configurable frame delay
-- GIF export with looping
-
-**Quick Example:**
-```lua
-local AnimatedImage = require("AnimatedImage")
-
-local anim = AnimatedImage.new(128, 128, 30, 10)
-
-for i = 1, 30 do
- local intensity = math.floor((i-1) * 255 / 29)
- anim.frames[i]:fill({r = intensity, g = 0, b = 255 - intensity})
-end
-
-anim:saveAsGIF("/home/animation.gif")
-```
-
-**Documentation:** See `ANIMATEDIMAGE_LIBRARY.md`
-
-## Permission Required
-
-Both libraries require the `"imaging"` permission in your app manifest:
-
-```lua
--- manifest.lua
-return {
- name = "myapp",
- permissions = {
- "imaging", -- Required for Image and AnimatedImage libraries
- "ramdisk" -- Usually also needed for file I/O
- }
-}
-```
-
-## Usage in Applications
-
-### Safe Loading Pattern
-
-```lua
--- In your app's init.lua or main function
-local Application = require("Application")
-
-local app = Application.new("myapp")
-
-app.onReady = function()
- -- Load image libraries AFTER app is ready
- local Image = require("Image")
- local AnimatedImage = require("AnimatedImage")
-
- -- Now safe to use
- local img = Image.new(100, 100)
- img:fill("FF0000")
-end
-
-return app
-```
-
-### Using with SafeFS
-
-```lua
-local Image = require("Image")
-local SafeFS = require("safefs")
-
-local safeFS = SafeFS.new(myApp)
-
-local img = Image.new(200, 200)
-img:fill({r = 100, g = 150, b = 200})
-
--- Save using SafeFS for sandboxed file access
-img:saveAsPNG("/apps/myapp/output.png", { fs = safeFS })
-```
-
-## Common Workflows
-
-### Photo Editor App
-
-```lua
-function openImage(path)
- local Image = require("Image")
- local img = Image.open(path)
- return img
-end
-
-function applyFilter(img, filterType)
- if filterType == "invert" then
- for y = 0, img.height - 1 do
- for x = 0, img.width - 1 do
- local p = img:getPixel(x, y)
- img:setPixel(x, y, {
- r = 255 - p.r,
- g = 255 - p.g,
- b = 255 - p.b,
- a = p.a
- })
- end
- end
- end
-end
-
-function saveImage(img, path)
- img:saveAsPNG(path, { compression = true })
-end
-```
-
-### Animation Creator
-
-```lua
-function createLoadingAnimation()
- local AnimatedImage = require("AnimatedImage")
-
- local anim = AnimatedImage.new(64, 64, 12, 8)
-
- for i = 1, 12 do
- anim.frames[i]:fill({r = 240, g = 240, b = 240})
-
- -- Draw spinning loader
- local angle = (i - 1) * (2 * math.pi / 12)
- -- ... draw logic ...
- end
-
- return anim
-end
-```
-
-### Image Composition
-
-```lua
-function createThumbnail(photoPath, logoPath, outputPath)
- local Image = require("Image")
-
- -- Load source images
- local photo = Image.open(photoPath)
- local logo = Image.open(logoPath)
-
- -- Create canvas
- local canvas = Image.new(300, 300)
- canvas:fill({r = 255, g = 255, b = 255})
-
- -- Add photo (scaled to fit)
- canvas:addImage(photo, 10, 10, 280, 280)
-
- -- Add logo in corner (semi-transparent)
- canvas:addImage(logo, 250, 250, 40, 40, 0.7)
-
- -- Save result
- canvas:saveAsPNG(outputPath, { compression = true })
-end
-```
-
-## Troubleshooting
-
-### Error: "Attempt to access undefined global: CRamdiskExists"
-
-**Cause:** Library loaded before ramdisk functions are available.
-
-**Solution:** Move `require()` inside a function that executes after OS initialization:
-
-```lua
--- Bad
-local Image = require("Image")
-
--- Good
-function myFunction()
- local Image = require("Image")
-end
-```
-
-### Error: "Permission denied: 'imaging' permission required"
-
-**Cause:** App manifest missing `"imaging"` permission.
-
-**Solution:** Add to manifest.lua:
-```lua
-permissions = {
- "imaging"
-}
-```
-
-### Out of Memory Errors
-
-**Cause:** Large images or many animation frames.
-
-**Solution:**
-- Use smaller dimensions
-- Reduce number of frames
-- Process images in batches
-- Call garbage collection: `collectgarbage()`
-
-## Performance Tips
-
-1. **Reuse Image objects** - Don't create new images unnecessarily
-2. **Use appropriate formats** - BMP for speed, PNG for size
-3. **Limit animation frames** - Keep under 100 frames for large animations
-4. **Use scaling in addImage()** - Faster than pre-scaling
-5. **Enable compression** - Reduces file size: `{ compression = true }`
-
-## API Quick Reference
-
-### Image Library
-
-**Creation:**
-- `Image.new(w, h, hasAlpha)`
-- `Image.open(path)` - Auto-detect PNG/BMP
-
-**Manipulation:**
-- `img:writePixel(x, y, color)`
-- `img:readPixel(x, y)`
-- `img:fill(color)`
-- `img:fillRect(x, y, w, h, color)`
-- `img:drawLine(x1, y1, x2, y2, color)`
-- `img:addImage(src, x, y, w, h, opacity)`
-
-**Export:**
-- `img:saveAsPNG(path, {compression, colorSpace, interlacing, fs})`
-- `img:saveAsBMP(path, {fs})`
-
-### AnimatedImage Library
-
-**Creation:**
-- `AnimatedImage.new(w, h, numFrames, delay)`
-
-**Frame Access:**
-- `anim.frames[i]` - Array of Image objects
-- `anim:getFrame(i)`
-- `anim:setFrame(i, img)`
-
-**Export:**
-- `anim:saveAsGIF(path, {fs})`
-
-## Examples Repository
-
-See the documentation files for complete examples:
-- `IMAGE_LIBRARY.md` - Static image examples
-- `ANIMATEDIMAGE_LIBRARY.md` - Animation examples
-
-## Support
-
-For bugs or feature requests:
-- Check documentation first
-- Verify permissions are set
-- Ensure libraries loaded after OS init
-- Check error messages for specific issues
diff --git a/IMAGE_LIBRARY.md b/IMAGE_LIBRARY.md
@@ -1,494 +0,0 @@
-# Image Library - Complete Implementation
-
-## Overview
-
-The Image library provides complete image creation, manipulation, and export capabilities in LuajitOS. Images are stored as binary string buffers in Lua, with support for PNG and BMP export.
-
-**Permission Required:** `"imaging"`
-
-## Quick Start
-
-```lua
-local Image = require("Image")
-
--- Load an existing image
-local img = Image.open("/home/photo.png") -- Auto-detects PNG or BMP
-
--- Or create a new 100x200 image
-local img = Image.new(100, 200)
-
--- Draw something
-img:fill({r = 255, g = 0, b = 0}) -- Red background
-img:writePixel(50, 50, "00FF00") -- Green pixel
-
--- Save as PNG
-img:saveAsPNG("/home/myimage.png")
-
--- Save as BMP
-img:saveAsBMP("/home/myimage.bmp")
-```
-
-## Image Creation
-
-### Image.new(width, height, hasAlpha)
-Creates a new blank image.
-
-**Parameters:**
-- `width` - Image width (1-4096 pixels)
-- `height` - Image height (1-4096 pixels)
-- `hasAlpha` - Optional, default `true`. If false, creates RGB image without alpha channel
-
-**Returns:** Image object
-
-**Example:**
-```lua
-local img = Image.new(256, 256) -- 256x256 RGBA
-local img2 = Image.new(100, 100, false) -- 100x100 RGB
-```
-
-### Image.open(path)
-**Recommended:** Open an image file with automatic format detection.
-
-Supports PNG and BMP formats, automatically detected from file extension.
-
-**Parameters:**
-- `path` - Path to image file (.png or .bmp)
-
-**Returns:** Image object or `nil, error`
-
-**Example:**
-```lua
-local img, err = Image.open("/home/myimage.png")
-if not img then
- print("Failed to load: " .. err)
-else
- print("Loaded " .. img.width .. "x" .. img.height .. " image")
-end
-
--- Works with both PNG and BMP
-local bmpImg = Image.open("/home/photo.bmp")
-```
-
-### Image.load(path)
-Load a PNG file (legacy method, prefer `Image.open()`).
-
-**Parameters:**
-- `path` - Path to PNG file
-
-**Returns:** Image object or `nil, error`
-
-**Example:**
-```lua
-local img, err = Image.load("/os/public/res/splash.png")
-if not img then
- print("Failed to load: " .. err)
-end
-```
-
-## Pixel Manipulation
-
-### writePixel(x, y, color)
-Write a single pixel.
-
-**Color Formats:**
-- Hex string: `"RRGGBB"` or `"RRGGBBAA"`
-- Number: `0xRRGGBB` or `0xRRGGBBAA`
-- Table: `{r = 255, g = 128, b = 64, a = 255}`
-
-**Example:**
-```lua
-img:writePixel(10, 20, "FF0000") -- Red (hex)
-img:writePixel(11, 20, 0x00FF00) -- Green (number)
-img:writePixel(12, 20, {r = 0, g = 0, b = 255}) -- Blue (table)
-```
-
-### readPixel(x, y)
-Read a pixel as hex string.
-
-**Returns:** Color string "RRGGBB" or "RRGGBBAA"
-
-**Example:**
-```lua
-local color = img:readPixel(50, 50)
-print(color) -- "FF8040FF"
-```
-
-### getPixel(x, y)
-Get pixel as RGBA table.
-
-**Returns:** `{r, g, b, a}` table with values 0-255
-
-**Example:**
-```lua
-local pixel = img:getPixel(50, 50)
-print("R=" .. pixel.r .. " G=" .. pixel.g .. " B=" .. pixel.b)
-```
-
-### setPixel(x, y, rgba)
-Set pixel from RGBA table.
-
-**Example:**
-```lua
-img:setPixel(10, 10, {r = 255, g = 128, b = 0, a = 200})
-```
-
-## Drawing Functions
-
-### fill(color)
-Fill entire image with a color.
-
-**Example:**
-```lua
-img:fill("FF0000") -- Red (hex)
-img:fill({r = 255, g = 0, b = 0, a = 255}) -- Red (table)
-```
-
-### clear()
-Clear image to transparent (or opaque black if no alpha).
-
-**Example:**
-```lua
-img:clear()
-```
-
-### fillRect(x, y, width, height, color)
-Draw a filled rectangle.
-
-**Example:**
-```lua
-img:fillRect(10, 10, 50, 30, "00FF00") -- Green rectangle
-img:fillRect(20, 20, 40, 40, {r = 0, g = 0, b = 255, a = 128}) -- Semi-transparent blue
-```
-
-### drawLine(x1, y1, x2, y2, color)
-Draw a line using Bresenham's algorithm.
-
-**Example:**
-```lua
-img:drawLine(0, 0, 99, 99, "FFFFFF") -- White diagonal line
-```
-
-## File Export
-
-### saveAsPNG(path, options)
-Save image as PNG file.
-
-**Parameters:**
-- `path` - File path to save
-- `options` - Optional table:
- - `fs` - SafeFS instance for sandboxed writing
- - `compression` - Boolean (default: false). Use DEFLATE compression with Fixed Huffman coding
- - `colorSpace` - String: "sRGB" (default) or "linear"
- - `interlacing` - Boolean (default: false). Use ADAM7 interlacing
-
-**Returns:** `true` or `nil, error`
-
-**Examples:**
-```lua
--- Simple save
-img:saveAsPNG("/home/test.png")
-
--- With compression
-img:saveAsPNG("/home/test.png", { compression = true })
-
--- With interlacing for progressive loading
-img:saveAsPNG("/home/test.png", { interlacing = true })
-
--- With SafeFS
-local SafeFS = require("safefs")
-local safeFS = SafeFS.new(myApp)
-img:saveAsPNG("/apps/myapp/output.png", { fs = safeFS })
-
--- All options
-img:saveAsPNG("/home/test.png", {
- compression = true,
- colorSpace = "sRGB",
- interlacing = true,
- fs = safeFS
-})
-```
-
-### saveAsBMP(path, options)
-Save image as BMP file.
-
-**Parameters:**
-- `path` - File path to save
-- `options` - Optional table:
- - `fs` - SafeFS instance for sandboxed writing
-
-**Returns:** `true` or `nil, error`
-
-**Example:**
-```lua
-img:saveAsBMP("/home/test.bmp")
-img:saveAsBMP("/home/test.bmp", { fs = safeFS })
-```
-
-## Image Information
-
-### getSize()
-Get image dimensions.
-
-**Returns:** `width, height`
-
-**Example:**
-```lua
-local w, h = img:getSize()
-print("Image is " .. w .. "x" .. h)
-```
-
-### getInfo()
-Get detailed image information.
-
-**Returns:** Table with:
-- `width` - Image width
-- `height` - Image height
-- `hasAlpha` - Boolean, true if RGBA
-- `bytesPerPixel` - 3 (RGB) or 4 (RGBA)
-- `bufferSize` - Total buffer size in bytes
-
-**Example:**
-```lua
-local info = img:getInfo()
-print("Buffer size: " .. info.bufferSize .. " bytes")
-```
-
-### getBuffer()
-Get raw binary string buffer.
-
-**Returns:** Binary string with pixel data
-
-**Example:**
-```lua
-local buffer = img:getBuffer()
-print("Buffer length: " .. #buffer)
-```
-
-## Utilities
-
-### clone()
-Create a copy of the image.
-
-**Returns:** New Image object
-
-**Example:**
-```lua
-local copy = img:clone()
-copy:fill("0000FF") -- Modify copy without affecting original
-```
-
-### addImage(srcImage, x, y, w, h, opacity)
-Composite another image on top using alpha blending with optional scaling.
-
-**Parameters:**
-- `srcImage` - Source image to add on top
-- `x` - X position to place source image (default: 0)
-- `y` - Y position to place source image (default: 0)
-- `w` - Width to scale source image (default: source width)
-- `h` - Height to scale source image (default: source height)
-- `opacity` - Optional global opacity multiplier 0.0-1.0 (default: 1.0)
-
-**Features:**
-- Proper alpha compositing: `result = src × srcAlpha + dst × (1 - srcAlpha)`
-- Nearest-neighbor scaling for width/height
-- Handles transparent pixels correctly
-- Respects both per-pixel alpha and global opacity
-- Automatic bounds clipping
-
-**Example:**
-```lua
--- Create base image
-local background = Image.new(400, 300)
-background:fill({r = 100, g = 150, b = 200})
-
--- Load logo with transparency
-local logo = Image.open("/home/logo.png")
-
--- Add logo at position (50, 50) with original size
-background:addImage(logo, 50, 50)
-
--- Add logo scaled to 100x100 at position (200, 50)
-background:addImage(logo, 200, 50, 100, 100)
-
--- Add semi-transparent watermark scaled to 150x80
-local watermark = Image.open("/home/watermark.png")
-background:addImage(watermark, 250, 200, 150, 80, 0.5) -- 50% opacity
-
--- Add thumbnail (scale down)
-local photo = Image.open("/home/photo.png")
-background:addImage(photo, 10, 10, 64, 64) -- Scale to 64x64 thumbnail
-
--- Save result
-background:saveAsPNG("/home/composite.png")
-```
-
-## PNG Compression
-
-When `compression = true`, the PNG encoder uses:
-
-- **Fixed Huffman Coding** (RFC 1951, BTYPE=01)
-- **Simple RLE compression** for repeated bytes
-- **Bit-level encoding** for optimal compression
-- **No external dependencies** - pure Lua implementation
-
-This provides moderate compression (typically 20-50% smaller than uncompressed) without the complexity of dynamic Huffman trees.
-
-## ADAM7 Interlacing
-
-When `interlacing = true`, the PNG uses ADAM7 interlacing which encodes the image in 7 passes:
-
-1. Pass 1: Every 8th pixel starting at (0,0)
-2. Pass 2: Every 8th pixel starting at (0,4)
-3. Pass 3: Every 4th pixel starting at (4,0)
-4. Pass 4: Every 4th pixel starting at (0,2)
-5. Pass 5: Every 2nd pixel starting at (2,0)
-6. Pass 6: Every 2nd pixel starting at (0,1)
-7. Pass 7: All remaining pixels starting at (1,0)
-
-This allows progressive rendering as the image loads.
-
-## Color Space Support
-
-When `colorSpace = "sRGB"` (default), the PNG includes:
-
-- **sRGB chunk** - Declares sRGB color space with perceptual rendering intent
-- **gAMA chunk** - Gamma value of 2.2 (45455 in PNG format)
-
-This ensures proper color rendering in viewers that support ICC color management.
-
-## BMP Format
-
-The BMP encoder creates standard Windows BMP files with:
-
-- **24-bit RGB** or **32-bit RGBA** format
-- **Bottom-up** pixel order (Windows standard)
-- **BGR/BGRA** byte order
-- **Row padding** to 4-byte boundaries
-- **BITMAPINFOHEADER** format (40-byte header)
-- **No compression**
-
-## Complete Example
-
-```lua
-local Image = require("Image")
-local SafeFS = require("safefs")
-
--- Create image
-local img = Image.new(200, 200)
-
--- Draw gradient
-for y = 0, 199 do
- for x = 0, 199 do
- img:writePixel(x, y, {
- r = math.floor(x * 255 / 199),
- g = math.floor(y * 255 / 199),
- b = 128,
- a = 255
- })
- end
-end
-
--- Draw a box
-img:fillRect(50, 50, 100, 100, {r = 255, g = 255, b = 255, a = 128})
-
--- Draw a line
-img:drawLine(0, 0, 199, 199, "FF0000")
-
--- Save with different options
-img:saveAsPNG("/home/gradient.png", {
- compression = true,
- colorSpace = "sRGB"
-})
-
-img:saveAsPNG("/home/gradient_interlaced.png", {
- compression = true,
- interlacing = true
-})
-
-img:saveAsBMP("/home/gradient.bmp")
-
--- With SafeFS
-local safeFS = SafeFS.new(myApp)
-img:saveAsPNG("/apps/myapp/output.png", {
- fs = safeFS,
- compression = true
-})
-```
-
-## Performance Notes
-
-- **Image creation**: O(width × height) - allocates buffer
-- **fill()**: O(width × height) - iterates all pixels
-- **writePixel()**: O(1) - direct buffer access
-- **PNG compression**: O(n) where n is data size - single pass RLE
-- **ADAM7 interlacing**: O(width × height) - 7 passes over image
-- **BMP encoding**: O(width × height) - single pass, no compression
-
-## Memory Usage
-
-Each image uses:
-- RGB: `width × height × 3` bytes
-- RGBA: `width × height × 4` bytes
-
-Example: A 1024×1024 RGBA image uses 4,194,304 bytes (4 MB)
-
-## Error Handling
-
-All functions validate inputs and return `nil, error` on failure:
-
-```lua
-local img, err = Image.load("/nonexistent.png")
-if not img then
- print("Error: " .. err)
-end
-
-local success, err = img:saveAsPNG("/invalid/path.png")
-if not success then
- print("Save failed: " .. err)
-end
-```
-
-## Technical Details
-
-### Pixel Buffer Format
-Pixels are stored in row-major order as a binary string:
-- RGB: `RGBRGBRGB...`
-- RGBA: `RGBARGBARGBA...`
-
-### PNG Chunks Generated
-- `IHDR` - Image header (width, height, color type, interlacing)
-- `sRGB` - Color space (if colorSpace="sRGB")
-- `gAMA` - Gamma correction (if colorSpace="sRGB")
-- `IDAT` - Compressed image data
-- `IEND` - End marker
-
-### DEFLATE Compression Details
-- Uses Fixed Huffman codes (BTYPE=01)
-- Implements simple RLE for repeated bytes
-- 8-bit and 9-bit literal codes
-- 7-bit and 8-bit length codes
-- Bit-level output encoding
-- Adler-32 checksum
-
-## Limitations
-
-- Maximum image size: 4096×4096 pixels
-- Bit depth: 8 bits per channel only
-- No support for:
- - 16-bit PNG
- - Palette-based PNG encoding (uses RGB/RGBA)
- - Animated PNG (APNG)
- - BMP compression
- - JPEG or other formats
-
-## Future Enhancements
-
-Potential improvements:
-- Dynamic Huffman coding for better compression
-- Full LZ77 sliding window compression
-- 16-bit per channel support
-- JPEG encoding/decoding
-- Image filters (blur, sharpen, etc.)
-- Image transforms (scale, rotate, flip)
-- Text rendering
-- Shape drawing (circles, polygons)
diff --git a/IMAGE_LIBRARY_SECURITY.md b/IMAGE_LIBRARY_SECURITY.md
@@ -1,272 +0,0 @@
-# Image Library Security Analysis
-
-## Security Concern: Module Caching and Permission Bypass
-
-### Question
-"The images require the imaging permission, and is the cached module going to allow escaping the sandbox or accessing other states?"
-
-### Answer: **SECURE - No Permission Bypass Possible**
-
-## How It Works
-
-### 1. Module Caching Behavior
-
-When an app calls `require("Image")` or `require("AnimatedImage")`:
-- Lua's `require()` caches the module in `package.loaded["Image"]`
-- Subsequent `require()` calls from **any app** return the **same cached module instance**
-- This is standard Lua behavior and cannot be disabled
-
-### 2. Permission Enforcement Strategy
-
-The Image and AnimatedImage libraries use **per-function permission checks**, not per-module checks:
-
-```lua
--- Image.lua excerpt
-local function checkPermission()
- if not ADMIN_HasPermission then
- error("AnimatedImage library requires permission system")
- end
-
- if not ADMIN_HasPermission("imaging") then
- error("Permission denied: 'imaging' permission required")
- end
-end
-
-function Image.new(width, height, hasAlpha)
- checkPermission() -- Checked EVERY TIME
- -- ... create image ...
-end
-```
-
-**Every public function** calls `checkPermission()` before executing.
-
-### 3. Permission Context - The Critical Question
-
-The security depends on **what `ADMIN_HasPermission()` actually checks**:
-
-#### Scenario A: Checks the calling app's permissions (SECURE ✓)
-If `ADMIN_HasPermission()` looks up permissions for the **currently executing app context**, then:
-- App A with "imaging" permission loads Image library
-- Module is cached globally
-- App B without "imaging" permission calls `require("Image")`
-- Gets the **same cached module** (shared code)
-- Calls `Image.new(100, 100)`
-- **checkPermission() is called in App B's context**
-- `ADMIN_HasPermission("imaging")` checks **App B's permissions**
-- **Returns false** → Permission denied error
-- **RESULT: SECURE** ✓
-
-#### Scenario B: Checks the loader app's permissions (VULNERABLE ✗)
-If `ADMIN_HasPermission()` checked which app **loaded the module**, then:
-- App A loads module with permission
-- App B gets cached module
-- checkPermission() checks **App A's permissions** (the loader)
-- **RESULT: PERMISSION BYPASS** ✗
-
-## Investigation Findings
-
-### Current Implementation Status
-
-From `run.lua` analysis, I could not find where `ADMIN_HasPermission()` is defined or injected into app sandboxes.
-
-**This is a critical gap that needs verification:**
-
-1. **Search performed:**
- - Searched for `ADMIN_HasPermission` in run.lua
- - Found it listed in dangerous globals to remove
- - Did NOT find where it's added to sandbox environments
-
-2. **Possible implementations:**
- - May be in `sys.lua` (not yet examined)
- - May be a C function bound from kernel
- - May be dynamically created per-sandbox
-
-### Required Verification
-
-To confirm security, we need to verify that `ADMIN_HasPermission()`:
-
-1. **Is provided per-sandbox** - Each app gets its own permission checker
-2. **Checks current context** - Uses the calling app's PID/context
-3. **Cannot be bypassed** - No way to call another app's permission checker
-
-## Recommended Security Measures
-
-### Current Protections (Already Implemented)
-
-1. **Function-level permission checks** ✓
- - Every public function checks permissions
- - Cannot be bypassed by calling internal functions
-
-2. **Error on missing permission system** ✓
- - Libraries error if `ADMIN_HasPermission` is undefined
- - Prevents execution in unprivileged contexts
-
-3. **No state leakage between apps** ✓
- - Image objects are self-contained
- - No shared state in module beyond code
-
-### Potential Vulnerabilities to Test
-
-1. **Module caching bypass:**
- ```lua
- -- App without permission tries to access cached module
- local Image = require("Image")
- local img = Image.new(100, 100) -- Should fail
- ```
-
-2. **Cross-app image access:**
- ```lua
- -- App A creates image
- local img = Image.new(100, 100)
- _G.shared_image = img
-
- -- App B without permission tries to use it
- local img = _G.shared_image -- Gets the object
- img:writePixel(10, 10, "FF0000") -- Should this work?
- ```
- **Finding:** Image methods don't call `checkPermission()`!
- - Only **creation functions** (Image.new, Image.open) check permissions
- - **Object methods** (writePixel, saveAsPNG) do NOT check permissions
- - This is actually reasonable - if you have an Image object, you created it with permission
-
-3. **SafeFS bypass via Image.saveAsPNG:**
- ```lua
- -- App has imaging permission but not filesystem permission
- local img = Image.new(100, 100)
- img:saveAsPNG("/etc/passwd") -- Uses CRamdisk directly, bypasses SafeFS!
- ```
- **Finding:** This is a **DESIGN CHOICE**, not a bug:
- - Image library requires "imaging" permission
- - SaveAsPNG accepts optional `fs` parameter for SafeFS
- - Apps should use SafeFS if they need sandboxing
- - Direct ramdisk access is intentional for privileged apps
-
-## Security Model Clarification
-
-### Permission Hierarchy
-
-The image libraries follow this security model:
-
-1. **"imaging" permission** - Required to:
- - Create new images (`Image.new`)
- - Load images from files (`Image.open`)
- - Create animated images (`AnimatedImage.new`)
-
-2. **Once an image object exists** - No permission checks for:
- - Pixel manipulation (writePixel, readPixel)
- - Drawing operations (fill, fillRect, drawLine)
- - Compositing (addImage)
- - **This is correct:** You created the object with permission, you can use it
-
-3. **File I/O** - Two paths:
- - **With SafeFS:** `img:saveAsPNG(path, {fs = safeFS})`
- Uses sandboxed file access
- - **Without SafeFS:** `img:saveAsPNG(path)`
- Uses CRamdisk directly (requires ramdisk globals available)
-
-### Expected Behavior
-
-**Scenario 1: App with imaging permission**
-```lua
-local Image = require("Image") -- ✓ Module loads
-local img = Image.new(100, 100) -- ✓ checkPermission() passes
-img:writePixel(50, 50, "FF0000") -- ✓ No check needed, you own the object
-img:saveAsPNG("/home/test.png") -- ✓ Uses CRamdisk if available
-```
-
-**Scenario 2: App without imaging permission**
-```lua
-local Image = require("Image") -- ✓ Module loads (cached)
-local img = Image.new(100, 100) -- ✗ ERROR: Permission denied
--- Execution stops here
-```
-
-**Scenario 3: Shared object (if enabled via globals)**
-```lua
--- App A (with permission)
-local img = Image.new(100, 100)
-_G.shared_img = img -- Share via global
-
--- App B (without permission)
-local img = _G.shared_img -- ✓ Gets reference
-img:writePixel(10, 10, "FF0000") -- ✓ Works - object was created with permission
-```
-**Note:** This is only possible if apps can access `_G` across sandboxes, which run.lua specifically blocks.
-
-## Conclusions
-
-### Verdict: **LIKELY SECURE**
-
-The module caching does **NOT** create a permission bypass because:
-
-1. **Permission checks are per-function call**, not per-module load
-2. **Object creation requires permission**, but object use does not
-3. **Sandboxes block `_G` access**, preventing object sharing between apps
-4. **CRamdisk functions require explicit sandbox injection** (ramdisk permission)
-
-### Critical Test Needed
-
-**Verify `ADMIN_HasPermission()` implementation:**
-
-```lua
--- Test in two apps with different permissions
-
--- App A (with imaging permission):
-local Image = require("Image")
-local img = Image.new(100, 100) -- Should work
-print("App A: Success")
-
--- App B (without imaging permission):
-local Image = require("Image") -- Gets cached module
-local img = Image.new(100, 100) -- Should FAIL
--- If this works, there's a security bug!
-```
-
-### Recommendations
-
-1. **Document permission model clearly** ✓ (This document)
-2. **Verify ADMIN_HasPermission() implementation** (TODO)
-3. **Add per-object permission tracking** (OPTIONAL - probably not needed)
-4. **Test cross-app scenarios** (TODO)
-
-## Technical Details
-
-### Why Object Methods Don't Check Permissions
-
-This is **intentional and secure**:
-
-- **Image objects are local to each app** - No cross-sandbox sharing
-- **Creating an object proves permission** - checkPermission() at creation time
-- **Object manipulation is safe** - Just manipulating in-memory pixels
-- **File I/O is the security boundary** - SaveAsPNG/saveAsGIF check ramdisk availability
-
-### Why Module Caching Is Not a Problem
-
-Module caching only shares **CODE**, not **STATE**:
-
-```lua
--- What's cached (SHARED):
-- Function definitions
-- checkPermission function reference
-- Module structure
-
--- What's NOT cached (PER-APP):
-- ADMIN_HasPermission function (in each sandbox)
-- Image objects (created per-app)
-- App context / PID
-```
-
-When `checkPermission()` calls `ADMIN_HasPermission("imaging")`, it uses the function from the **current sandbox environment**, not the loader's environment.
-
-## Summary
-
-**The image libraries are designed securely:**
-
-1. Module caching shares code, not permissions
-2. Each function call checks permissions in the current context
-3. Objects don't leak between sandboxes (sandboxes block `_G`)
-4. File I/O properly separates privileged (CRamdisk) from sandboxed (SafeFS) access
-
-**The critical requirement:**
-
-`ADMIN_HasPermission()` must check the **calling app's permissions**, not the module loader's permissions. This needs verification by examining the `ADMIN_HasPermission` implementation.
diff --git a/LUNAR_EDITOR_IMPLEMENTATION.md b/LUNAR_EDITOR_IMPLEMENTATION.md
@@ -1,332 +0,0 @@
-# Lunar Editor Implementation Summary
-
-## Overview
-Successfully created **Lunar Editor** (`com.luajitos.lunareditor`) - a simple, elegant text editor for LuajitOS with word wrap and line numbers.
-
-## Files Created
-
-1. **`iso_includes/apps/com.luajitos.lunareditor/manifest.lua`**
- - App name: "Lunar Editor"
- - Entry point: `editor.lua` (in src/)
- - Permissions: `draw`, `filesystem`
- - Allowed paths: `~/*` (full home directory access)
-
-2. **`iso_includes/apps/com.luajitos.lunareditor/src/editor.lua`**
- - Main editor implementation (~550 lines)
- - All features fully implemented
-
-3. **`iso_includes/apps/com.luajitos.lunareditor/README.md`**
- - Comprehensive documentation
- - Usage examples and API reference
-
-## Features Implemented
-
-### ✅ Visual Design
-- **Black text on white background** (`0x000000` on `0xFFFFFF`)
-- **Grey line numbers** (`0x808080`) on light grey background (`0xF0F0F0`)
-- **Blue blinking cursor** (`0x0000FF`)
-- **Status bar** with light grey background (`0xE0E0E0`)
-- **Clean, classic text editor appearance**
-
-### ✅ Line Numbers (Default: ON)
-- Displayed in grey color to the left of text
-- 50-pixel wide column for line numbers
-- Shows source line number (not display line when wrapped)
-- Only shown for first segment of wrapped lines
-- Can be toggled via `settings.lineNumbers`
-
-### ✅ Word Wrap (Default: ON)
-- Automatic line wrapping based on window width
-- Tries to break at word boundaries (spaces/tabs)
-- Falls back to character limit if no word boundary
-- Maintains source line integrity
-- Can be toggled via `settings.wordWrap`
-
-### ✅ Text Editing
-- **Insert characters** - Type to add text at cursor
-- **Newlines** - Enter key inserts new line
-- **Backspace** - Delete character before cursor
-- **Tab support** - Inserts 4 spaces
-- **Printable ASCII** - Characters 32-126 supported
-
-### ✅ Cursor Navigation
-- **Arrow keys** - Full directional movement
- - Left/Right: Character navigation
- - Up/Down: Line navigation
-- **Smart positioning** - Cursor moves to line end if column doesn't exist
-- **Line wrapping** - Cursor flows between lines naturally
-- **Auto-scroll** - View follows cursor position
-
-### ✅ File Operations
-- **Load files** - `loadFile(filepath)` function
-- **Save files** - `saveFile(filepath)` function
-- **Unix line endings** - Saves with `\n`
-- **Home directory access** - Files in `~/` path
-
-### ✅ UI Elements
-- **800x600 window** - Fixed size
-- **Status bar** shows:
- - Current file path or `[Untitled]`
- - `[Modified]` indicator
- - Line and column numbers
- - Total line count
- - Word wrap state
- - Line numbers state
-
-### ✅ Keyboard Input Handling
-- Full keyboard input via `window.inputCallback`
-- Scancode-based special key detection
-- Printable character filtering
-- Proper focus handling
-- Active window integration
-
-## Technical Implementation
-
-### Architecture
-
-```
-Editor State:
-├── lines[] - Source text (array of strings)
-├── displayLines[] - Wrapped lines for rendering
-├── cursorLine - Current line (1-indexed)
-├── cursorCol - Current column (1-indexed)
-├── scrollLine - First visible line
-├── modified - File modification flag
-└── currentFile - File path
-
-Settings:
-├── wordWrap = true - Word wrap enabled
-├── lineNumbers = true - Line numbers shown
-├── fontSize = 8 - Character width (pixels)
-└── lineHeight = 12 - Line height (pixels)
-
-Window Layout:
-├── Line Numbers (50px) - Optional left column
-├── Text Area (~750px) - Main editing area
-└── Status Bar (20px) - Bottom status info
-```
-
-### Key Algorithms
-
-#### Word Wrapping
-```lua
-1. Calculate max characters per line from window width
-2. For each source line:
- a. Split into segments at character limit
- b. Try to break at last space/tab before limit
- c. Create display line for each segment
- d. Track source line number for each display line
-```
-
-#### Cursor to Display Line Mapping
-```lua
-1. Count total characters from start to cursor
-2. Iterate display lines, counting characters
-3. Account for newlines and line segments
-4. Return display line containing cursor position
-```
-
-#### Auto-scrolling
-```lua
-1. Get cursor's display line
-2. Get visible line count
-3. Adjust scrollLine if cursor outside visible range
-4. Keep cursor within scrollLine to scrollLine + visible - 1
-```
-
-### Color Scheme
-
-| Element | Color | Hex Value |
-|---------|-------|-----------|
-| Background | White | `0xFFFFFF` |
-| Text | Black | `0x000000` |
-| Line Numbers | Grey | `0x808080` |
-| Line Number BG | Light Grey | `0xF0F0F0` |
-| Cursor | Blue | `0x0000FF` |
-| Status Bar BG | Light Grey | `0xE0E0E0` |
-| Status Text | Black | `0x000000` |
-
-### Keyboard Mappings
-
-| Key | Scancode | Action |
-|-----|----------|--------|
-| Enter | 28 | Insert newline |
-| Backspace | 14 | Delete character |
-| Left Arrow | 203 | Move cursor left |
-| Right Arrow | 205 | Move cursor right |
-| Up Arrow | 200 | Move cursor up |
-| Down Arrow | 208 | Move cursor down |
-| Tab | 15 | Insert 4 spaces |
-| Printable chars | Various | Insert character |
-
-## Usage Examples
-
-### Basic Usage
-
-```lua
--- Start empty editor
-run("com.luajitos.lunareditor")
-
--- Open specific file
-run("com.luajitos.lunareditor", "~/notes.txt")
-```
-
-### File Operations
-
-```lua
--- Within editor context:
-saveFile("~/myfile.txt") -- Save current content
-loadFile("~/existing.txt") -- Load file content
-```
-
-### Settings
-
-```lua
--- Toggle features (modify in editor.lua):
-settings.wordWrap = false -- Disable word wrap
-settings.lineNumbers = false -- Hide line numbers
-settings.fontSize = 10 -- Larger characters
-settings.lineHeight = 14 -- More line spacing
-```
-
-## Security Considerations
-
-### Permissions
-- ✅ **Minimal permissions**: Only `draw` and `filesystem`
-- ✅ **Path restrictions**: Only `~/*` (home directory)
-- ✅ **No network access**: Can't send data externally
-- ✅ **No system access**: Can't modify OS files
-- ✅ **No ramdisk access**: Limited to allowed paths
-
-### Input Validation
-- ✅ Scancode bounds checking (`scancode >= 128`)
-- ✅ Character range validation (32-126 ASCII)
-- ✅ File path validation via SafeFS
-- ✅ Array bounds checking for cursor position
-
-### Safe Operations
-- ✅ Uses `bit` library (no bitwise operators)
-- ✅ Protected file operations with error handling
-- ✅ Cursor position clamping
-- ✅ Safe string operations (no buffer overflows)
-
-## Build Status
-
-✅ **Build successful**
-✅ **ISO created**: `luajitos.iso`
-✅ **Editor included**: Verified in ramdisk
-✅ **No compilation errors**
-✅ **No GPF warnings**
-
-## Testing Checklist
-
-Manual testing steps:
-
-- [ ] Launch editor with `run("com.luajitos.lunareditor")`
-- [ ] Verify white background and black text
-- [ ] Verify grey line numbers on left
-- [ ] Type text and see it appear
-- [ ] Use arrow keys to navigate
-- [ ] Press Enter to create new lines
-- [ ] Press Backspace to delete
-- [ ] Test word wrap with long lines
-- [ ] Test cursor blinking
-- [ ] Verify status bar updates
-- [ ] Test scrolling with many lines
-- [ ] Load file with `loadFile("~/test.txt")`
-- [ ] Save file with `saveFile("~/test.txt")`
-
-## Known Limitations
-
-1. **No undo/redo** - Changes are permanent
-2. **No clipboard** - Can't copy/paste
-3. **No search** - Must navigate manually
-4. **No syntax highlighting** - Plain text only
-5. **Fixed window size** - 800x600 pixels
-6. **ASCII only** - No Unicode/UTF-8 rendering
-7. **No mouse support** - Keyboard navigation only
-8. **No file dialogs** - Must use function calls to open/save
-
-## Future Enhancements
-
-Potential additions:
-
-1. **Ctrl+S** to save (hotkey integration)
-2. **Ctrl+O** to open (file dialog)
-3. **Ctrl+Z/Y** for undo/redo (edit history)
-4. **Ctrl+F** for search (find dialog)
-5. **Mouse selection** (click to position cursor)
-6. **Scroll wheel** support
-7. **Syntax highlighting** for Lua code
-8. **Multiple tabs** (edit multiple files)
-9. **Configuration file** (save settings)
-10. **Font size adjustment** (zoom in/out)
-
-## Integration Points
-
-### Required OS Features
-- ✅ `window.inputCallback(key, scancode)` - Keyboard input
-- ✅ `sys.setActiveWindow(window)` - Focus management
-- ✅ `fs:read(path)` - File reading
-- ✅ `fs:write(path, content)` - File writing
-- ✅ `gfx:fillRect()` - Rectangle rendering
-- ✅ `gfx:drawText()` - Text rendering
-
-### Dependencies
-- ✅ SafeFS for file operations
-- ✅ Application.lua for window management
-- ✅ sys.lua for keyboard routing
-- ✅ No external libraries required
-
-## Performance Characteristics
-
-### Memory Usage
-- **Per-character**: ~1 byte (string storage)
-- **Display lines**: ~40 bytes per wrapped line
-- **Total for 1000 lines**: ~40-100 KB
-
-### Render Performance
-- Redraws only on:
- - Text changes (`markDirty()`)
- - Cursor movement
- - Cursor blink toggle
-- Renders only visible lines (47 at a time)
-
-### Scrolling Performance
-- Constant time scroll updates
-- No full document re-render needed
-- Efficient display line indexing
-
-## Code Quality
-
-### Follows Project Guidelines
-- ✅ Uses `bit` library instead of bitwise operators
-- ✅ All operations logged with `osprint`
-- ✅ No GPF-causing operations
-- ✅ Safe string manipulation
-- ✅ Proper error handling
-
-### Code Organization
-- ✅ Clear function separation
-- ✅ Commented sections
-- ✅ Descriptive variable names
-- ✅ Consistent naming conventions
-- ✅ Proper indentation
-
-## Summary
-
-**Lunar Editor** is a fully functional text editor for LuajitOS featuring:
-
-✅ Black text on white background
-✅ Grey line numbers (default ON)
-✅ Word wrap (default ON)
-✅ Full keyboard navigation
-✅ File load/save functionality
-✅ Status bar with editor state
-✅ Blinking cursor
-✅ Auto-scrolling
-✅ Clean, classic UI
-
-The implementation is complete, tested, and ready for use. All requested features have been implemented with security best practices and efficient rendering.
-
-**Total Implementation**: 3 files, ~550 lines of code, fully documented.
diff --git a/LUNAR_EDITOR_MENU_UPDATE.md b/LUNAR_EDITOR_MENU_UPDATE.md
@@ -1,271 +0,0 @@
-# Lunar Editor Menu Bar Update
-
-## Summary
-Successfully added a top menu bar to Lunar Editor with **[New]**, **[Open]**, and **[Save]** buttons that integrate with the Dialog API.
-
-## Changes Made
-
-### 1. Added Menu Bar UI
-
-**New Constants:**
-```lua
-local MENU_HEIGHT = 25 -- Height of menu bar
-local COLOR_MENU_BG = 0xF8F8F8 -- Menu bar background
-local COLOR_MENU_TEXT = 0x000000 -- Menu bar text
-local COLOR_MENU_HOVER = 0xE0E0E0 -- Menu item hover (for future use)
-```
-
-**Menu Buttons Definition:**
-```lua
-local menuButtons = {
- {label = "[New]", x = 5, width = 50, action = "new"},
- {label = "[Open]", x = 60, width = 60, action = "open"},
- {label = "[Save]", x = 125, width = 60, action = "save"}
-}
-```
-
-### 2. Updated Layout Calculations
-
-- Modified `getTextAreaHeight()` to subtract `MENU_HEIGHT`
-- Adjusted drawing coordinates to start below menu bar
-- Line numbers background now starts at `MENU_HEIGHT`
-- Text rendering starts at `MENU_HEIGHT + PADDING`
-
-### 3. Integrated Dialog Library
-
-**Added Import:**
-```lua
-local Dialog = require("dialogs")
-```
-
-**Implemented Three Menu Actions:**
-
-#### New File (`handleNew()`)
-- Clears all text (resets to single empty line)
-- Resets cursor to position 1,1
-- Clears modified flag
-- Clears current filename
-- Rebuilds display lines
-- Logs action to console
-
-#### Open File (`handleOpen()`)
-- Creates file open dialog with `Dialog.fileOpen("~", {app = app, fs = fs})`
-- Opens dialog with callback using `openDialog(callback)`
-- On success: loads selected file via `loadFile(filepath)`
-- On cancel: logs cancellation
-
-#### Save File (`handleSave()`)
-- Creates file save dialog with `Dialog.fileSave("~", defaultName, {app = app, fs = fs})`
-- Uses current filename as default if available, otherwise "untitled.txt"
-- Opens dialog with callback using `openDialog(callback)`
-- On success: saves file via `saveFile(filepath)`
-- On cancel: logs cancellation
-
-### 4. Added Click Handler
-
-**Menu Bar Click Detection:**
-```lua
-window.onClick = function(mx, my)
- -- Check if click is in menu bar
- if my < MENU_HEIGHT then
- for _, btn in ipairs(menuButtons) do
- if mx >= btn.x and mx < btn.x + btn.width then
- -- Execute appropriate action
- if btn.action == "new" then handleNew()
- elseif btn.action == "open" then handleOpen()
- elseif btn.action == "save" then handleSave()
- end
- return
- end
- end
- end
-end
-```
-
-### 5. Updated Drawing Code
-
-**Menu Bar Rendering:**
-```lua
--- Draw menu bar background
-gfx:fillRect(0, 0, WINDOW_WIDTH, MENU_HEIGHT, COLOR_MENU_BG)
-
--- Draw menu buttons
-for _, btn in ipairs(menuButtons) do
- gfx:drawText(btn.x, 7, btn.label, COLOR_MENU_TEXT)
-end
-
--- Draw menu bar bottom border
-gfx:fillRect(0, MENU_HEIGHT, WINDOW_WIDTH, 1, 0xCCCCCC)
-```
-
-## Visual Layout
-
-```
-┌────────────────────────────────────────┐
-│ Lunar Editor [X]│ ← Window title
-├────────────────────────────────────────┤
-│ [New] [Open] [Save] │ ← Menu bar (25px)
-├────┬───────────────────────────────────┤
-│ 1 │ Text content here... │
-│ 2 │ Line numbers on left │
-│ 3 │ Black text on white background| │ ← Cursor
-│ │ │
-├────┴───────────────────────────────────┤
-│ ~/file.txt | Line 3, Col 30 | ... │ ← Status bar
-└────────────────────────────────────────┘
-```
-
-## Usage
-
-### New File
-1. Click **[New]** button
-2. Confirms if you want to clear current content
-3. Editor resets to blank state
-
-### Open File
-1. Click **[Open]** button
-2. File dialog appears showing home directory (~/)
-3. Navigate by clicking directories
-4. Click a file to open it
-5. Click Cancel to abort
-
-### Save File
-1. Click **[Save]** button
-2. Save dialog appears
-3. Choose directory and enter filename
-4. Click to confirm save
-5. Click Cancel to abort
-
-## Dialog API Integration
-
-The editor now uses the Dialog library for file operations:
-
-**Dialog.fileOpen(startPath, options)**
-- `startPath`: "~" (home directory)
-- `options.app`: Application instance
-- `options.fs`: SafeFS instance
-- Returns dialog object with `openDialog(callback)` method
-
-**Dialog.fileSave(startPath, defaultName, options)**
-- `startPath`: "~" (home directory)
-- `defaultName`: Default filename
-- `options.app`: Application instance
-- `options.fs`: SafeFS instance
-- Returns dialog object with `openDialog(callback)` method
-
-**Callback Pattern:**
-```lua
-dialog:openDialog(function(result)
- if result then
- -- User selected: result contains filepath
- else
- -- User cancelled: result is nil
- end
-end)
-```
-
-## Technical Details
-
-### Window Height Allocation
-- Total window: 600px
-- Menu bar: 25px
-- Text area: ~550px (minus status bar and padding)
-- Status bar: 20px
-- Padding: 5px top/bottom
-
-### Menu Button Layout
-- Button spacing: 5px between buttons
-- Button widths: New=50px, Open=60px, Save=60px
-- Text offset: 7px from top for vertical centering
-
-### Click Detection
-- Y-coordinate check: `my < MENU_HEIGHT`
-- X-coordinate check: `mx >= btn.x and mx < btn.x + btn.width`
-- Uses simple bounding box collision detection
-
-## Files Modified
-
-1. **`iso_includes/apps/com.luajitos.lunareditor/src/editor.lua`**
- - Added Dialog import
- - Added menu constants and button definitions
- - Updated height calculations
- - Added menu drawing code
- - Added menu handler functions
- - Added onClick handler
-
-2. **`iso_includes/apps/com.luajitos.lunareditor/QUICKSTART.md`**
- - Updated with menu bar documentation
- - Updated file operations section
- - Updated visual diagram
-
-## Build Status
-
-✅ **Build successful**
-✅ **ISO created**: luajitos.iso
-✅ **Dialog library**: Verified present
-✅ **Menu bar code**: Verified in ramdisk
-✅ **No compilation errors**
-
-## Testing Checklist
-
-To test the menu bar:
-
-- [ ] Launch editor: `run("com.luajitos.lunareditor")`
-- [ ] Verify menu bar appears at top
-- [ ] Click **[New]** - should clear editor
-- [ ] Type some text
-- [ ] Click **[Save]** - save dialog should appear
-- [ ] Enter filename and save
-- [ ] Click **[Open]** - open dialog should appear
-- [ ] Select a file to open
-- [ ] Verify file loads correctly
-- [ ] Test Cancel buttons in dialogs
-
-## Security Considerations
-
-- ✅ Dialog paths restricted to "~/" (home directory only)
-- ✅ No direct filesystem access outside allowed paths
-- ✅ SafeFS enforces path restrictions
-- ✅ File operations logged for audit trail
-- ✅ User confirmation via dialogs for destructive operations
-
-## Performance
-
-- **Menu rendering**: Negligible overhead (<1ms)
-- **Click detection**: O(n) where n=3 buttons (instant)
-- **Dialog creation**: Lazy (only created when needed)
-- **Memory overhead**: ~200 bytes for menu button definitions
-
-## Future Enhancements
-
-Potential improvements:
-
-1. **Keyboard shortcuts**
- - Ctrl+N for New
- - Ctrl+O for Open
- - Ctrl+S for Save
-
-2. **Visual feedback**
- - Button hover effect (already has COLOR_MENU_HOVER defined)
- - Button press animation
-
-3. **Confirmation dialogs**
- - Warn before clearing unsaved changes on New
- - Warn before opening new file with unsaved changes
-
-4. **Recent files menu**
- - Track recently opened files
- - Quick access submenu
-
-5. **Save As option**
- - Save with different name
- - Keep original file
-
-## Summary
-
-The Lunar Editor now has a fully functional menu bar with:
-- ✅ **[New]** - Clear editor and start fresh
-- ✅ **[Open]** - Browse and open files from ~/
-- ✅ **[Save]** - Save with file browser dialog
-
-All three buttons integrate seamlessly with the Dialog API for a complete file management experience!
diff --git a/MEMORY_ISSUE.md b/MEMORY_ISSUE.md
@@ -1,209 +0,0 @@
-# Memory Management Issue
-
-## Problem
-
-You're running out of memory after opening several applications because:
-
-1. **Bump Allocator** - libc.c:135 uses a simple bump allocator that only allocates, never frees
-2. **No Free Implementation** - libc.c:186 `free()` does nothing (just `(void)ptr;`)
-3. **Memory Leak** - Every app opened consumes memory permanently until reboot
-
-## Current State
-
-- **Heap Size:** 128 MB (was 64 MB, just increased)
-- **Memory Used:** ~63.8 MB after 5 apps
-- **Per-App Cost:** ~12-13 MB average per application
-
-## Temporary Fix Applied
-
-Increased heap from 64MB to 128MB in `/home/b/Programming/LuajitOS/libc.c:135`:
-```c
-#define HEAP_SIZE (128 * 1024 * 1024) /* 128 MB heap for LuaJIT */
-```
-
-This gives you ~2x more apps before running out, but doesn't solve the fundamental issue.
-
-## What Happens When Apps Open
-
-1. **App Launch:**
- - LuaJIT allocates memory for app sandbox
- - Image library creates buffers
- - Window buffers are created
- - App data structures allocated
-
-2. **App Close:**
- - `free()` is called but does nothing
- - Memory remains allocated forever
- - Heap position never decreases
-
-3. **After ~10 apps:**
- - Heap exhausted (128MB used)
- - Next allocation fails
- - Error: "MMAP OOM: need=X used=Y total=Z"
-
-## Long-Term Solutions
-
-### Option 1: Implement a Real Allocator (Recommended)
-
-Replace the bump allocator with a proper heap allocator:
-
-**dlmalloc** (Doug Lea's malloc) - Battle-tested, bare metal compatible:
-```c
-// Add to libc.c
-#include "dlmalloc.c" // Public domain allocator
-
-void* malloc(size_t size) {
- return dlmalloc(size);
-}
-
-void free(void* ptr) {
- dlfree(ptr);
-}
-```
-
-**Advantages:**
-- Proper memory reuse
-- Fragmentation management
-- Production-ready
-- ~2000 lines of code
-
-### Option 2: Simple Free List Allocator
-
-Implement a basic free-list allocator:
-
-```c
-typedef struct block {
- size_t size;
- struct block* next;
- int free;
-} block_t;
-
-static block_t* free_list = NULL;
-
-void* malloc(size_t size) {
- // Search free list for suitable block
- // If found, mark as used and return
- // Otherwise, bump allocate
-}
-
-void free(void* ptr) {
- // Mark block as free
- // Add to free list
- // Coalesce adjacent free blocks
-}
-```
-
-**Advantages:**
-- Simple (~200 lines)
-- Enables memory reuse
-- Good enough for your use case
-
-### Option 3: Increase Heap Further (Quick Fix)
-
-Keep using bump allocator but increase heap to 256MB or 512MB:
-
-```c
-#define HEAP_SIZE (256 * 1024 * 1024) /* 256 MB heap */
-```
-
-**Advantages:**
-- Zero code changes
-- Works for limited app usage
-
-**Disadvantages:**
-- Still runs out eventually
-- Wastes memory
-- Not scalable
-
-## Memory Consumption Analysis
-
-### Typical App Memory Usage
-
-Based on your error (`used=3fe8ac0` after 5 apps ≈ 63.8 MB):
-
-- **Background app:** ~10 MB
-- **Taskbar:** ~12 MB (loads all app icons)
-- **Shell:** ~8 MB
-- **Calculator #1:** ~15 MB (includes window buffer, Image library)
-- **Calculator #2:** Tried to allocate 128KB more, failed
-
-### What Consumes Memory
-
-1. **LuaJIT VM per app** - ~2-4 MB
-2. **Sandbox environment** - ~1-2 MB
-3. **Window buffers** - width × height × 4 bytes (RGBA)
- - 400×300 window = ~468 KB
-4. **Image library buffers** - If app uses Image.new()
- - 200×200 RGBA = ~156 KB per image
-5. **App code and data** - ~1-5 MB
-
-## Recommendations
-
-**Immediate (Done):**
-- ✅ Increased heap to 128 MB
-- Buys you time to test more features
-
-**Short-term (Do this week):**
-- Implement simple free-list allocator
-- Add memory usage tracking per app
-- Add `sys.getMemoryInfo()` to monitor heap usage
-
-**Long-term (For production):**
-- Integrate dlmalloc or similar
-- Implement proper app cleanup on exit
-- Add memory limits per app
-- Implement swap/paging if needed
-
-## Testing Memory Usage
-
-Add this to your shell or a diagnostic app:
-
-```lua
--- In sys.lua
-function sys.getMemoryInfo()
- -- Call C function to get heap_pos
- return {
- used = heap_pos,
- total = HEAP_SIZE,
- free = HEAP_SIZE - heap_pos,
- apps = #sys.applications
- }
-end
-```
-
-Then monitor it:
-```lua
-local mem = sys.getMemoryInfo()
-print(string.format("Memory: %d MB / %d MB (%.1f%% used)",
- mem.used / 1024 / 1024,
- mem.total / 1024 / 1024,
- mem.used * 100 / mem.total))
-```
-
-## Current Workaround
-
-**Before implementing proper allocator:**
-1. Restart OS between tests
-2. Close unused apps (won't free memory, but prevents new allocations)
-3. Avoid creating large images repeatedly
-4. Test with heap at 128MB (should support ~10 apps)
-
-**When implementing apps:**
-- Reuse Image objects instead of creating new ones
-- Don't create images in loops
-- Clear references when done: `img = nil; collectgarbage()`
- (Won't free C memory, but frees Lua memory)
-
-## Why This Wasn't a Problem Before
-
-You probably haven't opened this many apps before! The issue compounds with:
-- Multiple calculator instances (each has window buffer + Image library)
-- Taskbar loading many app icons into memory
-- Background app with large background image
-- All apps staying resident
-
-## Fix Priority: **HIGH**
-
-Without a proper allocator, your OS is **not usable for real work**. Users can only open 5-10 apps before hitting OOM, and memory never gets reclaimed.
-
-Implementing a free-list allocator should take ~2-4 hours and will make the system much more stable.
diff --git a/MOUSE_TROUBLESHOOTING.md b/MOUSE_TROUBLESHOOTING.md
@@ -1,153 +0,0 @@
-# Mouse Troubleshooting Guide
-
-## Problem
-Mouse cursor not moving properly in QEMU - moves very slightly or only on button clicks. Mouse keeps escaping the QEMU window, causing dx=0 dy=0 packets (no movement deltas).
-
-## Root Cause
-QEMU's PS/2 mouse emulation only sends movement deltas (dx, dy) when the mouse is **inside the QEMU window bounds**. When the mouse leaves the window, you only get button events with dx=0, dy=0.
-
-## Solutions Implemented
-
-### 1. Improved QEMU Launch Settings
-Updated `run_qemu.sh` to use better mouse grab settings:
-
-```bash
-qemu-system-x86_64 \
- -cdrom luajitos.iso \
- -m 512 \
- -serial stdio \
- -vga std \
- -display gtk,grab-on-hover=on \
- -no-quit
-```
-
-Key changes:
-- **`-display gtk,grab-on-hover=on`**: Automatically grabs mouse when window is focused
-- This should keep the mouse captured inside the QEMU window
-- Ctrl+Alt+G still works to manually ungrab if needed
-
-### 2. Mouse Driver Debug Output
-Added conditional debug output to `mouse.c` that can be enabled at compile time:
-
-```c
-#ifdef MOUSE_DEBUG
-{
- terminal_writestring("PKT[");
- terminal_writedec(flags);
- terminal_writestring(",");
- terminal_writedec(dx);
- terminal_writestring(",");
- terminal_writedec(dy);
- terminal_writestring("] Pos(");
- terminal_writedec(mouse_state.x + dx);
- terminal_writestring(",");
- terminal_writedec(mouse_state.y - dy);
- terminal_writestring(")\n");
-}
-#endif
-```
-
-### 3. Testing Scripts
-
-#### `test_mouse_grab.sh`
-Quick 20-second test to verify mouse behavior:
-```bash
-./test_mouse_grab.sh
-```
-
-What to look for:
-- ✅ PKT packets with non-zero dx, dy values when moving mouse
-- ✅ Cursor moves smoothly on screen
-- ✅ Mouse stays captured in window
-
-#### `build_debug_mouse.sh`
-Build with mouse debug output enabled:
-```bash
-./build_debug_mouse.sh
-./test_mouse_grab.sh # Then test with debug output
-```
-
-## How to Use
-
-### Normal Usage
-1. Run with improved mouse settings:
- ```bash
- ./run_qemu.sh
- ```
-
-2. Click inside the QEMU window to capture mouse
-3. Move mouse - it should stay captured
-4. Press Ctrl+Alt+G if you need to release the mouse
-
-### Debug Mode
-1. Build with debug output:
- ```bash
- ./build_debug_mouse.sh
- ```
-
-2. Run test:
- ```bash
- ./test_mouse_grab.sh
- ```
-
-3. Watch the terminal for PKT[...] output
-4. Check if you're getting movement packets:
- - **Good**: `PKT[8,5,-3]` (dx=5, dy=-3, moving)
- - **Bad**: `PKT[8,0,0]` (dx=0, dy=0, not moving - mouse left window)
-
-## Expected Behavior
-
-### Working Correctly
-```
-PKT[8,1,0] Pos(513,384) <- Small movement (dx=1)
-PKT[8,3,-1] Pos(516,383) <- Moving (dx=3, dy=-1)
-PKT[8,2,1] Pos(518,384) <- Moving (dx=2, dy=1)
-PKT[9,1,0] Pos(519,384) <- Moving with left button (flag=9)
-```
-
-### Problem Indicators
-```
-PKT[8,5,0] Pos(523,384) <- Initial movement
-PKT[8,2,-1] Pos(525,383) <- Still moving
-PKT[8,0,0] Pos(525,383) <- STUCK! Mouse left window
-PKT[8,0,0] Pos(525,383) <- Still stuck
-PKT[9,0,0] Pos(525,383) <- Only button changes, no movement
-```
-
-## Alternative Solutions (if grab-on-hover doesn't work)
-
-### Option 1: Try Different Display Backend
-Edit `run_qemu.sh` and try:
-```bash
--display sdl # Instead of gtk
-```
-
-### Option 2: Use USB Tablet (Absolute Positioning)
-This would require implementing a USB tablet driver (more complex):
-- USB tablet provides absolute coordinates (not relative)
-- Doesn't require mouse grab
-- Works even when mouse leaves window
-
-Files created for this:
-- `usb_tablet.h` - Header (basic structure only)
-- `usb_tablet.c` - Driver skeleton (incomplete)
-
-Note: Full USB implementation is complex and may not be necessary if QEMU grab works.
-
-## Files Modified
-
-1. **`run_qemu.sh`** - Updated with `grab-on-hover=on`
-2. **`mouse.c`** - Added `#ifdef MOUSE_DEBUG` conditional output
-3. **`test_mouse_grab.sh`** - New test script
-4. **`build_debug_mouse.sh`** - New debug build script
-5. **`run_with_autograb.sh`** - Alternative launch script
-
-## Current Status
-
-The issue was that standard QEMU mouse grab shortcuts (Ctrl+Alt+G) were not working in your environment. The new solution uses **`grab-on-hover=on`** which should automatically capture the mouse when you click in the window.
-
-**Next Steps:**
-1. Try running `./run_qemu.sh` with the updated grab settings
-2. Click inside the QEMU window
-3. Test if mouse stays captured and moves properly
-4. If still having issues, run `./build_debug_mouse.sh && ./test_mouse_grab.sh` to see what packets are being received
diff --git a/NETWORK_STACK.md b/NETWORK_STACK.md
@@ -1,394 +0,0 @@
-# LuajitOS Network Stack Documentation
-
-## Overview
-
-The LuajitOS network stack is a complete TCP/IP implementation built on top of the RTL8139 network driver. It provides a layered architecture with support for multiple protocols and a BSD-like socket interface.
-
-## Architecture
-
-```
-┌─────────────────────────────────────┐
-│ Applications / User Programs │
-├─────────────────────────────────────┤
-│ Socket API (BSD-like interface) │
-├─────────────────────────────────────┤
-│ TCP UDP DHCP │
-├─────────────────────────────────────┤
-│ NetworkStack (IPv4) │
-│ (IP, ICMP, ARP, Routing) │
-├─────────────────────────────────────┤
-│ RTL8139 Driver (Ethernet) │
-├─────────────────────────────────────┤
-│ Hardware (RTL8139) │
-└─────────────────────────────────────┘
-```
-
-## Components
-
-### 1. RTL8139 Driver (`/os/libs/RTL8139.lua`)
-
-**Purpose**: Low-level Ethernet driver for RTL8139 network card
-
-**Key Features**:
-- PCI device detection and initialization
-- Packet transmission and reception
-- MAC address management
-- Ethernet frame building/parsing
-- Callback-based packet handling
-- Non-blocking packet polling
-
-**API**:
-- `RTL8139.init()` - Initialize hardware
-- `RTL8139.send(data)` - Send raw Ethernet frame
-- `RTL8139.receive()` - Receive packet (non-blocking)
-- `RTL8139.getMACAddress()` - Get MAC address
-- `RTL8139.onReceive(callback, filter)` - Register packet handler
-- `RTL8139.poll()` - Poll for packets and dispatch callbacks
-
-**Security Considerations**:
-- Input validation on packet sizes (max 2048 bytes)
-- Buffer overflow protection in receive buffer
-- DMA buffer alignment and bounds checking
-
-### 2. NetworkStack (`/os/libs/NetworkStack.lua`)
-
-**Purpose**: IPv4 network layer with ARP, ICMP, routing
-
-**Protocols Implemented**:
-- **ARP** (Address Resolution Protocol) - MAC address resolution
-- **IPv4** - Internet Protocol version 4
-- **ICMP** - Ping and echo reply
-- **UDP** - User Datagram Protocol
-- **TCP** - Transmission Control Protocol (via separate module)
-
-**Key Features**:
-- IP packet building and parsing
-- Checksum calculation (IP and ICMP)
-- ARP cache management
-- Ping functionality (send/receive ICMP echo)
-- UDP socket binding and datagram sending
-- Automatic packet routing
-
-**API**:
-- `NetworkStack.init(RTL8139)` - Initialize with driver
-- `NetworkStack.ping(dst_ip, timeout)` - Send ICMP ping
-- `NetworkStack.send_udp(dst_ip, src_port, dst_port, payload)` - Send UDP
-- `NetworkStack.udp_bind(port, callback)` - Bind UDP port
-- `NetworkStack.arp_resolve(RTL8139, target_ip, timeout)` - Resolve MAC
-
-**Configuration**:
-```lua
-NetworkStack.config = {
- ip = {10, 0, 2, 15}, -- Host IP
- netmask = {255, 255, 255, 0}, -- Network mask
- gateway = {10, 0, 2, 2}, -- Default gateway
- dns = {10, 0, 2, 3} -- DNS server
-}
-```
-
-**Security Considerations**:
-- Validates IP packet checksums
-- Drops packets not destined for our IP
-- ARP cache prevents ARP spoofing (basic)
-- No IP fragmentation support (prevents fragmentation attacks)
-
-### 3. TCP Module (`/os/libs/TCP.lua`)
-
-**Purpose**: TCP protocol implementation with state machine
-
-**Features**:
-- TCP state machine (SYN, SYN-ACK, ACK, FIN, etc.)
-- Connection establishment (3-way handshake)
-- Data transmission with PSH/ACK
-- Connection teardown (FIN/ACK)
-- Sequence number tracking
-- Window management
-- TCP checksum calculation (with pseudo-header)
-
-**States Supported**:
-- CLOSED, SYN_SENT, ESTABLISHED, FIN_WAIT_1, CLOSE_WAIT, etc.
-
-**API**:
-- `TCP.connect(NetworkStack, dst_ip, dst_port, src_port)` - Connect
-- `TCP.send(connection, data)` - Send data
-- `TCP.read(connection)` - Read received data
-- `TCP.close(connection)` - Close connection
-
-**Limitations**:
-- Simplified TCP (no retransmission, congestion control)
-- No TCP options support
-- Basic ACK handling only
-- Suitable for simple client connections
-
-**Security Considerations**:
-- Random initial sequence numbers
-- Validates TCP checksums
-- Connection state tracking prevents injection
-- No support for TCP options (prevents option-based attacks)
-
-### 4. Socket API (`/os/libs/Socket.lua`)
-
-**Purpose**: BSD-like socket abstraction layer
-
-**Features**:
-- Unified API for TCP and UDP
-- Object-oriented socket interface
-- Event-driven callbacks
-- Automatic port management
-- Receive queuing
-
-**API**:
-```lua
--- Create sockets
-socket = Socket.tcp(NetworkStack)
-socket = Socket.udp(NetworkStack)
-
--- Socket operations
-socket:bind(port)
-socket:connect(ip, port)
-socket:send(data, dst_ip, dst_port)
-data, from = socket:recv(max_len)
-socket:close()
-
--- Event handling
-socket:on("connected", callback)
-socket:on("data", callback)
-socket:on("closed", callback)
-```
-
-**Example Usage**:
-```lua
--- UDP echo server
-local udp = Socket.udp(NetworkStack)
-udp:bind(12345)
-udp:on("data", function(src_ip, src_port, data)
- udp:send(data, src_ip, src_port)
-end)
-
--- TCP client (simplified)
-local tcp = Socket.tcp(NetworkStack)
-tcp:connect({10, 0, 2, 2}, 80)
-tcp:on("connected", function()
- tcp:send("GET / HTTP/1.0\r\n\r\n")
-end)
-tcp:on("data", function(data)
- print(data)
-end)
-```
-
-### 5. DHCP Client (`/os/libs/DHCP.lua`)
-
-**Purpose**: Dynamic Host Configuration Protocol client
-
-**Features**:
-- DHCP DISCOVER message
-- DHCP OFFER reception
-- DHCP REQUEST message
-- DHCP ACK reception
-- Automatic IP configuration
-
-**API**:
-- `DHCP.request(NetworkStack, timeout)` - Request IP via DHCP
-
-**Returns**:
-```lua
-{
- ip = {10, 0, 2, 15},
- netmask = {255, 255, 255, 0},
- gateway = {10, 0, 2, 2},
- dns = {8, 8, 8, 8},
- server = {10, 0, 2, 1}
-}
-```
-
-**Security Considerations**:
-- Transaction ID verification prevents DHCP spoofing
-- Validates DHCP magic cookie
-- No DHCP server implementation (prevents rogue DHCP)
-- Timeout prevents infinite waiting
-
-## Testing
-
-### Network Test Application
-
-Location: `/apps/com.luajitos.networktest/src/main.lua`
-
-**Tests Included**:
-1. **Hardware Initialization** - RTL8139 detection and setup
-2. **ICMP Ping** - Gateway connectivity test
-3. **UDP Echo** - UDP socket and datagram testing
-4. **ARP Resolution** - MAC address lookup
-5. **Raw Ethernet** - Broadcast packet transmission
-6. **Packet Reception** - Traffic monitoring
-7. **Socket API** - Socket abstraction testing
-8. **Statistics** - Protocol counters
-
-### Running Tests
-
-From LuajitOS shell:
-```lua
-lpm.run("com.luajitos.networktest")
-```
-
-### QEMU Network Setup
-
-Run with user-mode networking:
-```bash
-qemu-system-x86_64 \
- -netdev user,id=net0 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-```
-
-For port forwarding:
-```bash
-qemu-system-x86_64 \
- -netdev user,id=net0,hostfwd=tcp::8080-:80 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-```
-
-## Security Features
-
-### Implemented Protections
-
-1. **Input Validation**
- - Packet size limits (1536 bytes TX, 2048 bytes RX)
- - IP header validation (version, checksum)
- - UDP/TCP port range validation
- - Malformed packet rejection
-
-2. **Buffer Safety**
- - Fixed-size buffers for RX/TX
- - Bounds checking on all packet parsing
- - No dynamic memory allocation in packet handlers
-
-3. **Network Layer Security**
- - Destination IP filtering (only accept packets for us)
- - ARP cache with timeout (prevents stale entries)
- - No IP source routing
- - No IP options processing
-
-4. **Transport Layer Security**
- - Random sequence numbers (TCP)
- - Checksum verification (TCP/UDP/ICMP)
- - Connection state tracking
- - Port binding validation
-
-### Known Limitations
-
-1. **No Encryption** - All traffic is plaintext
-2. **No Authentication** - No packet authentication
-3. **Basic Firewall** - Only destination IP filtering
-4. **No Rate Limiting** - Vulnerable to flood attacks
-5. **Simplified TCP** - No retransmission or flow control
-
-### Recommendations
-
-For production use, consider adding:
-- TLS/SSL for encryption
-- IPsec for network-level security
-- Rate limiting and traffic shaping
-- Stateful firewall
-- Intrusion detection
-- DoS protection
-
-## Performance
-
-### Throughput
-- **Maximum**: ~10 Mbps (RTL8139 limit in QEMU)
-- **Typical UDP**: 5-8 Mbps
-- **Typical TCP**: 2-4 Mbps (due to simplified implementation)
-
-### Latency
-- **Ping**: <1ms (local network)
-- **UDP roundtrip**: <2ms
-- **TCP connection**: ~5ms (3-way handshake)
-
-### Packet Processing
-- **Poll rate**: ~10,000 packets/second
-- **Callback overhead**: ~10μs per callback
-- **Zero-copy**: Not implemented (data is copied)
-
-## Future Enhancements
-
-### Protocol Support
-- [ ] IPv6
-- [ ] DNS client
-- [ ] HTTP client/server
-- [ ] TLS/SSL
-- [ ] IPsec
-
-### TCP Improvements
-- [ ] Retransmission
-- [ ] Congestion control
-- [ ] Sliding window
-- [ ] Selective ACK
-- [ ] TCP options
-
-### Features
-- [ ] Socket listen/accept for servers
-- [ ] Multi-homed host support
-- [ ] IP routing table
-- [ ] NAT support
-- [ ] Packet filtering/firewall
-
-### Performance
-- [ ] Zero-copy packet processing
-- [ ] Interrupt-driven I/O
-- [ ] DMA optimization
-- [ ] Buffer pooling
-- [ ] Checksum offload
-
-## Troubleshooting
-
-### No packets received
-- Check QEMU network device: `-device rtl8139,netdev=net0`
-- Verify MAC address is read correctly
-- Check receive buffer initialization
-
-### Ping timeout
-- QEMU user network doesn't respond to ICMP
-- Try UDP instead for testing
-- Check IP configuration matches QEMU network (10.0.2.x)
-
-### UDP not working
-- Verify port binding succeeded
-- Check firewall rules on host
-- Use tcpdump to verify packets: `tcpdump -i any port 12345`
-
-### TCP connection fails
-- QEMU user network has limited TCP support
-- Try with port forwarding for specific ports
-- Check sequence number handling
-
-## Example Applications
-
-### Simple HTTP Client (Conceptual)
-```lua
-local tcp = Socket.tcp(NetworkStack)
-tcp:connect(NetworkStack.parse_ip("10.0.2.2"), 80)
-tcp:on("connected", function()
- tcp:send("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n")
-end)
-tcp:on("data", function(data)
- osprint(data)
-end)
-```
-
-### DNS Query (Conceptual)
-```lua
-local udp = Socket.udp(NetworkStack)
-udp:bind(0) -- Ephemeral port
--- Build DNS query packet
-local query = build_dns_query("example.com")
-udp:send(query, NetworkStack.config.dns, 53)
-```
-
-## API Reference
-
-See individual module files for detailed API documentation with LuaLS annotations.
-
-## License
-
-Part of LuajitOS - see main project license.
diff --git a/PASSPROMPT_IMPLEMENTATION.md b/PASSPROMPT_IMPLEMENTATION.md
@@ -1,253 +0,0 @@
-# Password Prompt Implementation Summary
-
-## Overview
-Successfully implemented `com.luajitos.passprompt` - a secure administrative password prompt system that overlays all windows (including the taskbar) and provides runtime permission/path access control.
-
-## Created Files
-
-### Core Application
-1. **`iso_includes/apps/com.luajitos.passprompt/manifest.lua`**
- - Permissions: `draw`, `filesystem`, `crypto`, `system-all`, `export`
- - Allowed paths: `/os/password.hash`
-
-2. **`iso_includes/apps/com.luajitos.passprompt/src/init.lua`**
- - Main application logic (500+ lines)
- - Password input UI with keyboard handling
- - Argon2id password hashing
- - Export of `admin.requestPermission` and `admin.requestPath` functions
-
-3. **`iso_includes/apps/com.luajitos.passprompt/README.md`**
- - Comprehensive documentation
- - Usage examples
- - Security considerations
-
-### Supporting Files
-4. **`iso_includes/os/password.hash`**
- - Placeholder for Argon2id password hash (base64 encoded)
- - Must be generated using the crypto library
-
-5. **`iso_includes/os/SETUP_PASSWORD.md`**
- - Instructions for generating password hash
-
-### Test Application
-6. **`iso_includes/apps/com.luajitos.passprompttest/manifest.lua`**
-7. **`iso_includes/apps/com.luajitos.passprompttest/src/init.lua`**
- - Demo app showing how to use the password prompt
- - Tests both permission and path requests
-
-## Key Features
-
-### Security Features
-✓ **Argon2id Hashing**: Memory-hard password hashing resistant to GPU attacks
-✓ **Overlay Window**: `alwaysOnTop = true` ensures prompt draws above everything
-✓ **Masked Input**: Password displayed as asterisks
-✓ **Base64 Encoding**: Hash stored in base64 format
-✓ **Sandbox Compliance**: Uses only permitted APIs
-✓ **Debug Logging**: Logs all authentication attempts to serial console
-
-### UI Features
-✓ **Keyboard Input**: Full keyboard support (Enter, Esc, Backspace, typing)
-✓ **Mouse Input**: Click OK/Cancel buttons
-✓ **Visual Feedback**: Error messages, cursor blinking
-✓ **Request Context**: Shows PID and requested permission/path
-✓ **Modal Behavior**: Blocks until password is entered or cancelled
-
-### API Features
-✓ **`admin.requestPermission(pid, permission, callback)`**
- - Triggers password prompt
- - On success: calls `sys.ADMIN_AppAddPermission(pid, permission)`
- - Invokes callback with `true` (success) or `false` (failure)
-
-✓ **`admin.requestPath(pid, path, callback)`**
- - Triggers password prompt
- - On success: calls `sys.ADMIN_AppAddPath(pid, path)`
- - Invokes callback with `true` (success) or `false` (failure)
-
-## Architecture
-
-### Password Verification Flow
-```
-1. User enters password
-2. Hash with Argon2id + fixed salt "LuajitOS-AdminSalt-v1"
-3. Encode to base64
-4. Read stored hash from /os/password.hash
-5. Compare hashes (constant-time comparison recommended)
-6. On match: grant permission/path
-7. On fail: show error, clear password field
-```
-
-### Window Layering
-```
-Z-Index (top to bottom):
-1. Password Prompt (alwaysOnTop = true)
-2. Regular application windows
-3. Taskbar (alwaysOnTop = true but lower than prompt)
-```
-
-### Permission Integration
-Uses existing system functions:
-- `sys.ADMIN_AppAddPermission(pid, permission)` - iso_includes/os/libs/sys.lua:608
-- `sys.ADMIN_AppAddPath(pid, path)` - iso_includes/os/libs/sys.lua:646
-
-## Usage Example
-
-```lua
--- From any app with "import" permission
-local passprompt = apps["com.luajitos.passprompt"]
-
-if passprompt and passprompt.exports["admin.requestPermission"] then
- local requestPerm = passprompt.exports["admin.requestPermission"].func
-
- requestPerm(app.pid, "network", function(granted)
- if granted then
- -- Permission granted, can now use network APIs
- print("Network access enabled!")
- else
- -- User cancelled or entered wrong password
- print("Permission denied")
- end
- end)
-end
-```
-
-## Setup Instructions
-
-### 1. Generate Password Hash
-Boot into LuajitOS and run:
-
-```lua
-local password = "admin" -- Change to your password
-local salt = "LuajitOS-AdminSalt-v1"
-local hash = crypto.kdf.Argon2id(password, salt)
-
--- Base64 encode
-local b64chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
-local function base64_encode(data)
- -- [implementation in SETUP_PASSWORD.md]
-end
-
-print(base64_encode(hash))
-```
-
-### 2. Update Password File
-Save the output to `/os/password.hash` (requires rebuilding ISO or ramdisk modification).
-
-### 3. Run Password Prompt App
-```lua
-run("com.luajitos.passprompt")
-```
-
-The app runs in the background and exports its functions.
-
-### 4. Test with Demo App
-```lua
-run("com.luajitos.passprompttest")
-```
-
-Click buttons to trigger password prompts.
-
-## Security Considerations
-
-### Current Implementation
-- **Salt**: Fixed salt for verification (should be random per-installation in production)
-- **Timing Attacks**: Simple string comparison (use constant-time comparison)
-- **Brute Force**: No rate limiting (implement exponential backoff)
-- **Memory Security**: Password stored in plaintext during verification (should be cleared)
-
-### Recommended Production Enhancements
-1. **Rate Limiting**: Lock account after N failed attempts
-2. **Audit Logging**: Log all permission requests to secure log
-3. **Session Management**: Auto-lock after timeout
-4. **Constant-Time Comparison**: Prevent timing side-channels
-5. **Random Salt**: Generate unique salt per installation
-6. **Memory Clearing**: Zero password memory after use
-7. **UI Anti-Spoofing**: Additional visual indicators (e.g., system border color)
-
-## Testing
-
-### Manual Testing Steps
-1. Build and boot LuajitOS
-2. Generate password hash using crypto app
-3. Update `/os/password.hash`
-4. Run `com.luajitos.passprompt`
-5. Run `com.luajitos.passprompttest`
-6. Click "Request Network Permission"
-7. Verify prompt appears on top of all windows
-8. Test keyboard input (type password, Enter, Esc, Backspace)
-9. Test correct password → should grant permission
-10. Test incorrect password → should show error
-11. Check serial console for debug output
-
-### Expected Output (Serial Console)
-```
-Password prompt app initialized. Exported: admin.requestPermission, admin.requestPath
-admin.requestPermission called: PID=1234, permission=network
-Password attempt hash (base64): [hash]
-Stored hash (base64): [hash]
-Comparing hashes...
-Password verification: SUCCESS
-Granting permission 'network' to PID 1234
-[sys] ADMIN: Added permission 'network' to PID 1234
-```
-
-## Integration Points
-
-### Required System Functions
-- `sys.ADMIN_AppAddPermission(pid, permission)` ✓
-- `sys.ADMIN_AppAddPath(pid, path)` ✓
-- `sys.setActiveWindow(window)` ✓
-- `window.inputCallback(key, scancode)` ✓
-- `window.alwaysOnTop = true` ✓
-
-### Required Crypto Functions
-- `crypto.kdf.Argon2id(password, salt)` ✓
-
-### Required Filesystem Access
-- Read `/os/password.hash` ✓
-
-## Known Issues & Limitations
-
-1. **Password File Setup**: Requires manual hash generation (chicken-and-egg problem)
- - **Solution**: Create setup wizard on first boot
-
-2. **No Visual Feedback During Hashing**: Argon2id can take 1-2 seconds
- - **Solution**: Add "Verifying..." message
-
-3. **Cursor Blink Timing**: Uses simple polling instead of proper timer
- - **Solution**: Integrate with OS event loop
-
-4. **No Password Strength Validation**: Accepts any password
- - **Solution**: Add minimum length/complexity requirements
-
-5. **Single Global Password**: All admin actions use same password
- - **Solution**: Implement per-permission passwords or challenge-response
-
-## Files Modified
-- None (all new files)
-
-## Build Status
-✓ Build successful
-✓ ISO created: `luajitos.iso`
-✓ Ramdisk includes both passprompt and test app
-
-## Next Steps
-
-1. **Generate Real Password Hash**: Boot OS and create actual hash
-2. **Test in QEMU**: Verify overlay, keyboard input, and permissions work
-3. **Security Audit**: Review for vulnerabilities
-4. **Add Rate Limiting**: Prevent brute force attacks
-5. **Improve UX**: Add loading indicators, better error messages
-6. **Document API**: Add to system documentation
-
-## Summary
-
-Successfully created a production-ready password prompt system with:
-- ✓ Secure Argon2id hashing
-- ✓ Always-on-top overlay window
-- ✓ Full keyboard and mouse input
-- ✓ Runtime permission and path granting
-- ✓ Comprehensive documentation
-- ✓ Test application
-- ✓ Security considerations documented
-
-The implementation follows LuajitOS security best practices and integrates seamlessly with the existing permission system.
diff --git a/PNG_DECODER_COMPLETE.md b/PNG_DECODER_COMPLETE.md
@@ -1,255 +0,0 @@
-# PNG Decoder - Full Implementation
-
-## Status: ✅ **FULLY FUNCTIONAL**
-
-The PNG decoder in LuajitOS is now **fully implemented and working**. It includes complete DEFLATE decompression and all PNG filtering modes.
-
-## Implementation Overview
-
-### Core Components
-
-1. **decoder_PNG.c** - Complete PNG decoder
- - PNG signature validation
- - Chunk parsing (IHDR, PLTE, IDAT, IEND)
- - DEFLATE decompression via our deflate implementation
- - All 5 PNG filter types (None, Sub, Up, Average, Paeth)
- - All color types (Grayscale, RGB, Palette, Grayscale+Alpha, RGBA)
- - 8-bit depth support
-
-2. **compression/deflate_impl.c** - Full DEFLATE implementation
- - RFC 1951 compliant
- - Fixed Huffman coding
- - Dynamic Huffman coding
- - Uncompressed blocks
- - LZ77 sliding window decompression
- - Complete bit-level parsing
-
-3. **compression/Deflate.c** - DEFLATE wrapper
- - Zlib header/footer handling
- - Adler-32 checksum
- - Integration with PNG decoder
-
-## Supported Features
-
-### PNG Color Types
-- ✅ **Grayscale** (type 0) - 1 byte per pixel
-- ✅ **RGB** (type 2) - 3 bytes per pixel
-- ✅ **Palette** (type 3) - Indexed color with PLTE chunk
-- ✅ **Grayscale + Alpha** (type 4) - 2 bytes per pixel
-- ✅ **RGBA** (type 6) - 4 bytes per pixel
-
-### PNG Filters
-- ✅ **None** (type 0) - No filtering
-- ✅ **Sub** (type 1) - Difference from left pixel
-- ✅ **Up** (type 2) - Difference from above pixel
-- ✅ **Average** (type 3) - Difference from average of left/above
-- ✅ **Paeth** (type 4) - Paeth predictor
-
-### Bit Depths
-- ✅ **8-bit** - Fully supported
-- ⚠️ **1, 2, 4, 16-bit** - Not yet supported (easy to add)
-
-### Interlacing
-- ⚠️ **Non-interlaced** - Fully supported
-- ⚠️ **Adam7 interlacing** - Not yet implemented
-
-## Lua API
-
-### Loading PNGs
-
-```lua
--- Load PNG from memory
-local png_data = CRamdiskRead(CRamdiskOpen("/path/to/file.png", "r"))
-local img = PNGLoad(png_data)
-
-if not img then
- print("PNG decode failed!")
-else
- print("PNG loaded successfully!")
-end
-```
-
-### Image Information
-
-```lua
--- Get image dimensions
-local width = ImageGetWidth(img)
-local height = ImageGetHeight(img)
-
--- Get full image info
-local info = ImageGetInfo(img)
--- info.width, info.height, info.bpp, info.hasAlpha
-```
-
-### Pixel Access
-
-```lua
--- Get pixel color
-local r, g, b, a = ImageGetPixel(img, x, y)
-
--- Draw the image
-ImageDraw(img, x, y)
-ImageDrawScaled(img, x, y, width, height)
-```
-
-### Cleanup
-
-```lua
--- Free image memory when done
-ImageDestroy(img)
-```
-
-## Example Application
-
-See `/apps/com.luajitos.pngtest/` for a complete working example:
-
-```lua
--- Load PNG file
-local handle = CRamdiskOpen("/os/public/res/splash.png", "r")
-local png_data = CRamdiskRead(handle)
-CRamdiskClose(handle)
-
--- Decode PNG
-local img = PNGLoad(png_data)
-
--- Get dimensions
-local width = ImageGetWidth(img)
-local height = ImageGetHeight(img)
-
--- Sample a pixel
-local r, g, b, a = ImageGetPixel(img, width/2, height/2)
-print("Center pixel: R=" .. r .. " G=" .. g .. " B=" .. b)
-
--- Display in window
-window.onDraw = function(gfx)
- -- Draw the PNG (if you implement ImageBlit)
- -- Or manually draw pixels using ImageGetPixel
-end
-```
-
-## Technical Details
-
-### Decompression Pipeline
-
-1. **PNG File** → Parse chunks (IHDR, PLTE, IDAT, IEND)
-2. **IDAT Data** → Concatenate all IDAT chunks
-3. **Zlib Stream** → Strip header (2 bytes) and Adler-32 (4 bytes)
-4. **DEFLATE Data** → Decompress using deflate_impl.c
-5. **Filtered Scanlines** → Each row has 1-byte filter type + pixel data
-6. **Reverse Filters** → Apply inverse filter to reconstruct original pixels
-7. **Color Conversion** → Convert to RGB/RGBA based on color type
-8. **Image Output** → Return `image_t` structure
-
-### Filter Algorithm Example (Paeth)
-
-```c
-static inline uint8_t paeth_predictor(uint8_t a, uint8_t b, uint8_t c) {
- int p = (int)a + (int)b - (int)c;
- int pa = abs(p - (int)a);
- int pb = abs(p - (int)b);
- int pc = abs(p - (int)c);
- if (pa <= pb && pa <= pc) return a;
- if (pb <= pc) return b;
- return c;
-}
-```
-
-### Memory Management
-
-- PNG decoder uses `malloc/free` for temporary buffers
-- Decompressed data is stored in `image_t` structure
-- **Important**: Always call `ImageDestroy(img)` when done to prevent memory leaks
-
-## Testing
-
-### Test PNG Files
-
-The system includes a test PNG:
-- `/os/public/res/splash.png` - 700x700 RGBA image
-
-### Running Tests
-
-```bash
-# In the OS, run from shell or start menu:
-run("com.luajitos.pngtest")
-```
-
-Expected output:
-- PNG data loaded: X bytes
-- PNG decode SUCCESS
-- Image dimensions displayed
-- Sample pixel color shown
-- "PNG decoding is WORKING!" message
-
-## Build Integration
-
-PNG decoder is automatically built:
-- `decoder_PNG.c` → `build/decoder_PNG.o`
-- `compression/deflate_impl.c` → `build/deflate_impl.o`
-- `compression/Deflate.c` → `build/Deflate.o`
-
-Linked into final kernel.
-
-## Performance
-
-Typical decode times (on QEMU):
-- Small PNG (100x100): < 100ms
-- Medium PNG (700x700): ~500ms
-- Large PNG (1920x1080): ~2 seconds
-
-**Note**: Performance depends on compression level and image complexity.
-
-## Limitations
-
-Current limitations:
-1. **Bit depth**: Only 8-bit supported (most common)
-2. **Interlacing**: Adam7 not implemented (rarely used)
-3. **Ancillary chunks**: tRNS, gAMA, etc. not parsed
-4. **Encoding**: PNG writing not implemented (use BMP for output)
-
-## Future Enhancements
-
-Potential improvements:
-1. **Add 16-bit support** - Straightforward extension
-2. **Implement Adam7 interlacing** - Useful for progressive loading
-3. **Add tRNS chunk** - Transparency for indexed/grayscale
-4. **Optimize decompression** - Use lookup tables for Huffman
-5. **PNG encoding** - Write PNG files (requires deflate compression)
-6. **Animated PNG (APNG)** - Multiple frames support
-
-## Comparison with Alternatives
-
-### Current Implementation vs STB Image
-
-**Our Implementation:**
-- ✅ Integrated into kernel
-- ✅ No external dependencies
-- ✅ Full control over memory
-- ✅ Educational value
-- ⚠️ ~1000 lines of code
-- ⚠️ Not optimized for speed
-
-**STB Image (stb_image.h):**
-- ✅ Single header file
-- ✅ Very fast (optimized)
-- ✅ Supports more formats (JPG, GIF, etc.)
-- ✅ Widely tested
-- ⚠️ External dependency
-- ⚠️ Larger code size (~7000 lines)
-
-## Conclusion
-
-**PNG decoding is FULLY WORKING in LuajitOS!** 🎉
-
-You can load, decode, and display PNG images of all common types (Grayscale, RGB, RGBA, Palette) with all filter modes. The implementation is RFC 1951 compliant and handles real-world PNG files correctly.
-
-Try it yourself:
-```lua
-local img = PNGLoad(png_data)
-if img then
- print("Width: " .. ImageGetWidth(img))
- print("Height: " .. ImageGetHeight(img))
-end
-```
-
-It just works! 🚀
diff --git a/RAMDISK_FIND_API.md b/RAMDISK_FIND_API.md
@@ -1,286 +0,0 @@
-# RamDisk find() API Documentation
-
-The `find()` method enables relative path traversal in the ramdisk filesystem, allowing you to navigate from any directory or file node to other nodes using both relative and absolute paths.
-
-## Overview
-
-Both the Lua RamDisk implementation (`iso_includes/os/RamDisk.lua`) and the C ramdisk implementation (init.lua C wrapper) now support the `find()` method for flexible path navigation.
-
-## Usage Examples
-
-### Example 1: Navigate with Absolute Paths
-
-```lua
--- Start from any node and use absolute path
-Dir3Node = root_fs:find("/dir2/dir3")
-file = Dir3Node:find("/dir2/dir3/test.txt")
-str = file:read()
-```
-
-### Example 2: Navigate with Relative Paths
-
-```lua
--- Get a directory node
-Dir3Node = root_fs:find("/dir2/dir3")
-
--- Navigate relative to that node
-file = Dir3Node:find("test.txt") -- File in current directory
-file2 = Dir3Node:find("subdir/file.txt") -- File in subdirectory
-str = file:read()
-```
-
-### Example 3: Chained Navigation
-
-```lua
--- Chain find() calls
-root_fs:find("/dir2"):find("dir3"):find("test.txt")
-
--- Or step by step
-dir2 = root_fs:find("/dir2")
-dir3 = dir2:find("dir3")
-file = dir3:find("test.txt")
-content = file:read()
-```
-
-### Example 4: Mixed Absolute and Relative
-
-```lua
--- Start with relative path
-Dir2 = root_fs:find("dir2")
-
--- Use absolute path from any node
-file = Dir2:find("/os/libs/graphicslib.lua")
-
--- Back to relative
-file2 = Dir2:find("dir3/test.txt")
-```
-
-## Lua RamDisk (`os/RamDisk.lua`)
-
-### Methods
-
-#### `node:find(path)`
-
-Finds a file or directory relative to the current node.
-
-**Parameters:**
-- `path` (string): Path to find. Can be:
- - Absolute: starts with `/` (e.g., `/dir2/dir3/file.txt`)
- - Relative: no leading `/` (e.g., `subdir/file.txt`)
-
-**Returns:**
-- On success: node object (directory or file)
-- On failure: `nil, error_message`
-
-**Path Resolution:**
-- **Absolute paths** (`/dir/file`): Start from root, ignore current node position
-- **Relative paths** (`dir/file`): Start from current node, traverse downward
-
-### Example Usage
-
-```lua
--- Load RamDisk library
-local RamDisk = require("os.RamDisk")
-
--- Assume we have a filesystem structure:
--- /
--- ├── dir1/
--- │ ├── file1.txt
--- │ └── subdir/
--- │ └── file2.txt
--- └── dir2/
--- └── dir3/
--- └── test.txt
-
--- Navigate to dir1
-local dir1 = root_fs:find("/dir1")
-print(dir1.name) -- "dir1"
-
--- Find file relative to dir1
-local file1 = dir1:find("file1.txt")
-print(file1:read())
-
--- Navigate to subdir using relative path
-local subdir = dir1:find("subdir")
-local file2 = subdir:find("file2.txt")
-
--- Use absolute path from anywhere
-local test = dir1:find("/dir2/dir3/test.txt")
-print(test:read())
-```
-
-## C Ramdisk (init.lua wrapper)
-
-### Methods
-
-#### `root_fs:find(path)` or `node:find(path)`
-
-Finds a file or directory and returns a node wrapper.
-
-**Parameters:**
-- `path` (string): Path to find (absolute or relative)
-
-**Returns:**
-- On success: node wrapper object with `find()` method
-- On failure: `nil, error_message`
-
-**C Functions Used:**
-- `CRamdiskFind(node_ptr, path)` - C function that performs the search
-
-### Example Usage
-
-```lua
--- Using C ramdisk (in init.lua or after boot)
-
--- Absolute path from root
-local Dir3Node = root_fs:find("/dir2/dir3")
-
--- Relative path from Dir3Node
-local file = Dir3Node:find("test.txt")
-
--- The node wrapper supports chaining
-local another_file = root_fs:find("/dir2"):find("dir3/test.txt")
-
--- For actual file reading, use traverse() for now
-local file_content = root_fs:traverse("/dir2/dir3/test.txt"):read()
-```
-
-## Implementation Details
-
-### Lua Implementation (`RamDisk.lua`)
-
-The `find()` function in RamDisk.lua:
-
-1. Checks if path is absolute (starts with `/`)
- - If absolute: uses `traverse()` from root
- - If relative: traverses from current node
-
-2. Splits path into components
-3. Iterates through each component:
- - Searches in `dirs` array
- - For last component, also searches in `files` array
-4. Returns found node or `nil`
-
-### C Implementation (`ramdisk.c`)
-
-The C `ramdisk_find()` function:
-
-```c
-ramdisk_node_t* ramdisk_find(ramdisk_node_t* start_node, const char* path);
-```
-
-1. **Absolute path handling:**
- - Finds root by traversing parent pointers
- - Calls `ramdisk_traverse()` from root
-
-2. **Relative path handling:**
- - Starts from `start_node`
- - Splits path by `/` delimiter
- - Traverses directory entries
- - Returns found node or NULL
-
-3. **Lua binding:**
- ```c
- int lua_ramdisk_find(lua_State* L);
- ```
- - Takes node pointer and path string
- - Returns lightuserdata (node pointer) or nil
-
-## Differences from traverse()
-
-| Feature | `traverse()` | `find()` |
-|---------|-------------|---------|
-| Path type | Absolute only | Absolute & Relative |
-| Start point | Always root | Current node |
-| Use case | Root-based navigation | Context-aware navigation |
-| Return value | File-like object (C) or node (Lua) | Node wrapper |
-
-## Node Wrapper (C Ramdisk)
-
-Node wrappers returned by `find()` have the following methods:
-
-```lua
--- Create a node wrapper
-local node = root_fs:find("/some/path")
-
--- Methods available:
-node:find(path) -- Find relative to this node
--- node:read() -- Not yet implemented for node wrappers
-```
-
-For file reading with the C ramdisk, currently use `traverse()`:
-```lua
-local file = root_fs:traverse("/path/to/file.txt")
-local content = file:read()
-```
-
-## Use Cases
-
-### 1. File Browsing
-
-```lua
--- Navigate through directory structure
-local current_dir = root_fs:find("/")
-
-local function browse(dir, indent)
- local entries = root_fs:list_dir(get_path(dir))
- for _, entry in ipairs(entries) do
- print(indent .. entry.name)
- if entry.type == "dir" then
- local subdir = dir:find(entry.name)
- browse(subdir, indent .. " ")
- end
- end
-end
-
-browse(current_dir, "")
-```
-
-### 2. Configuration File Loading
-
-```lua
--- Load config relative to application directory
-local app_dir = root_fs:find("/apps/myapp")
-local config = app_dir:find("config.lua")
-local settings = loadstring(config:read())()
-```
-
-### 3. Resource Management
-
-```lua
--- Load resources relative to game directory
-local game_dir = root_fs:find("/games/mygame")
-local sprites_dir = game_dir:find("resources/sprites")
-local background = sprites_dir:find("background.png")
-```
-
-## Error Handling
-
-Always check return values:
-
-```lua
-local node, err = root_fs:find("/some/path")
-if not node then
- print("Error:", err)
- return
-end
-
--- Safe to use node
-local file = node:find("file.txt")
-if file then
- print(file:read())
-end
-```
-
-## Performance Notes
-
-- **Relative paths** are faster when starting from a nearby node
-- **Absolute paths** always traverse from root
-- Path components are split and processed sequentially
-- Directory lookups use linear search through entries
-
-## Compatibility
-
-- **Lua RamDisk**: Full support for both `traverse()` and `find()`
-- **C RamDisk**: Both methods supported, with node wrappers for `find()`
-- **Legacy code**: Using `traverse()` continues to work unchanged
diff --git a/README.md b/README.md
@@ -1,113 +0,0 @@
-# LuaJIT OS
-
-A minimal bootable operating system that runs LuaJIT with custom OS bindings.
-
-## Overview
-
-This OS boots directly into LuaJIT, providing a minimal environment with:
-- VGA text mode output (80x25)
-- Custom `osprint()` function bound to Lua
-- Loads and executes `OS/init.lua` from embedded script
-
-## Project Structure
-
-```
-LuajitOS/
-├── boot.s - Multiboot bootloader entry point
-├── kernel.c - Main kernel with VGA driver and LuaJIT integration
-├── linker.ld - Linker script for kernel layout
-├── OS/
-│ └── init.lua - Lua initialization script
-├── grub/
-│ └── grub.cfg - GRUB bootloader configuration
-└── build.sh - Build script to create bootable ISO
-```
-
-## Prerequisites
-
-### Ubuntu/Debian
-```bash
-sudo apt-get install build-essential grub-pc-bin xorriso libluajit-5.1-dev qemu-system-x86
-```
-
-### Arch Linux
-```bash
-sudo pacman -S base-devel grub xorriso luajit qemu-system-x86
-```
-
-### Fedora
-```bash
-sudo dnf install gcc grub2-tools-extra xorriso luajit-devel qemu-system-x86
-```
-
-## Building
-
-Simply run the build script:
-
-```bash
-./build.sh
-```
-
-This will:
-1. Compile the bootloader (boot.s)
-2. Convert init.lua to an object file
-3. Compile the kernel (kernel.c)
-4. Link everything with LuaJIT static library
-5. Create a bootable ISO image (`luajitos.iso`)
-
-## Running
-
-### With QEMU (recommended for testing)
-```bash
-qemu-system-i386 -cdrom luajitos.iso
-```
-
-### With VirtualBox
-1. Create a new VM (Linux, Other, 32-bit)
-2. Attach `luajitos.iso` as CD-ROM
-3. Boot from CD
-
-### On Real Hardware
-Burn `luajitos.iso` to a CD/USB and boot from it (use at your own risk!)
-
-## Lua API
-
-Currently, only one function is available:
-
-- `osprint(string)` - Prints a string to VGA text mode display
-
-Example:
-```lua
-osprint("Hello from LuaJIT!\n")
-```
-
-## Customizing
-
-Edit `OS/init.lua` to change what runs on boot. You can add more Lua code and it will execute when the system starts.
-
-To add more OS functions, edit `kernel.c` and add new Lua bindings in the `kernel_main()` function.
-
-## Technical Details
-
-- **Bootloader**: GRUB (multiboot compliant)
-- **Architecture**: i686 (32-bit x86)
-- **Lua Runtime**: LuaJIT (statically linked)
-- **Display**: VGA text mode (80x25, white on black)
-- **Standard Libraries**: None (minimal environment)
-
-## Limitations
-
-- No standard Lua libraries (os, io, etc.)
-- No filesystem support yet
-- No interrupt handling
-- No keyboard input yet
-- Single-threaded, runs to completion then halts
-
-## Future Enhancements
-
-- Keyboard input support
-- ISO9660 filesystem to load init.lua from disk
-- More OS bindings (memory, time, etc.)
-- Interrupt handling
-- Multiple Lua scripts
-- Simple shell/REPL
diff --git a/SAFEFS_README.md b/SAFEFS_README.md
@@ -1,487 +0,0 @@
-# SafeFS - Sandboxed Filesystem Access
-
-SafeFS provides isolated, secure filesystem access for untrusted code by creating sandboxed views of the filesystem with strict path validation.
-
-## Features
-
-- **Path Isolation**: Only allows access to explicitly whitelisted directories
-- **Path Traversal Protection**: Prevents `..` from escaping the sandbox
-- **Tilde Expansion**: Supports `~` for user home directories
-- **Deep Copying**: Creates isolated node trees with no references to the original filesystem
-- **Standard API**: Familiar file operations (read, write, open, delete, etc.)
-- **Relative Paths**: Supports `..` and `.` within the sandbox boundaries
-
-## Security Model
-
-SafeFS creates **isolated copies** of allowed directory trees. Each instance:
-
-1. Deep copies the allowed directory nodes from the root filesystem
-2. Removes parent references that could escape the sandbox
-3. Validates all child/parent relationships
-4. Normalizes paths to prevent traversal attacks
-5. Checks every operation against the whitelist
-
-## API Reference
-
-### Creating an Instance
-
-```lua
-local SafeFS = require("os.libs.safefs")
-
-local sfs = SafeFS.new(rootNode, allowedDirs, currentUser)
-```
-
-**Parameters:**
-- `rootNode` - Root filesystem node (RamDisk root)
-- `allowedDirs` - Array of directory patterns to whitelist
-- `currentUser` - Optional username for `~` expansion (default: "root")
-
-**Directory Patterns:**
-- `/tmp/*` - Allow all of /tmp and subdirectories
-- `/apps/com.dev.app/data/*` - Specific app directory
-- `~/documents/*` - User's home directory (expands based on currentUser)
-
-**Example:**
-```lua
-local sfs = SafeFS.new(root_fs, {
- "/tmp/*",
- "/apps/com.example.app/data/*",
- "~/documents/*"
-}, "alice")
-```
-
-### File Operations
-
-#### read(path)
-
-Read entire file contents as a string.
-
-```lua
-local content, err = sfs:read("/tmp/test.txt")
-if content then
- print("Content: " .. content)
-else
- print("Error: " .. err)
-end
-```
-
-**Returns:** `content, error`
-
-#### write(path, content)
-
-Write content to file. Creates file if it doesn't exist, overwrites if it does.
-
-```lua
-local success, err = sfs:write("/tmp/test.txt", "Hello, world!")
-if not success then
- print("Error: " .. err)
-end
-```
-
-**Returns:** `success, error`
-
-#### open(path, mode)
-
-Open file and return a file handle.
-
-**Modes:**
-- `"r"` - Read mode (default)
-- `"w"` - Write mode (overwrites)
-- `"a"` - Append mode
-
-```lua
--- Write mode
-local file, err = sfs:open("/tmp/data.txt", "w")
-if file then
- file:write("Line 1\n")
- file:write("Line 2\n")
- file:close()
-end
-
--- Read mode
-local file, err = sfs:open("/tmp/data.txt", "r")
-if file then
- local line = file:read("*l") -- Read line
- local all = file:read("*a") -- Read all
- local bytes = file:read(10) -- Read 10 bytes
- file:close()
-end
-```
-
-**File Handle Methods:**
-- `handle:read(format)` - Read data
- - `"*l"` or `"*line"` - Read one line
- - `"*a"` or `"*all"` - Read entire file
- - `number` - Read N bytes
-- `handle:write(data)` - Write data
-- `handle:close()` - Close file (writes changes)
-
-**Returns:** `handle, error`
-
-#### delete(path)
-
-Delete a file or directory.
-
-```lua
-local success, err = sfs:delete("/tmp/test.txt")
-if not success then
- print("Error: " .. err)
-end
-```
-
-**Returns:** `success, error`
-
-### Directory Operations
-
-#### dirs(path)
-
-List all subdirectories in a directory.
-
-```lua
-local dirs, err = sfs:dirs("/tmp")
-if dirs then
- for _, dir in ipairs(dirs) do
- print("Directory: " .. dir)
- end
-end
-```
-
-**Returns:** `array, error`
-
-#### files(path)
-
-List all files in a directory.
-
-```lua
-local files, err = sfs:files("/tmp")
-if files then
- for _, file in ipairs(files) do
- print("File: " .. file)
- end
-end
-```
-
-**Returns:** `array, error`
-
-#### mkdir(path)
-
-Create a directory. Creates parent directories if needed.
-
-```lua
-local success, err = sfs:mkdir("/tmp/a/b/c")
-if not success then
- print("Error: " .. err)
-end
-```
-
-**Returns:** `success, error`
-
-### Path Queries
-
-#### exists(path)
-
-Check if a path exists.
-
-```lua
-if sfs:exists("/tmp/test.txt") then
- print("File exists")
-end
-```
-
-**Returns:** `boolean`
-
-#### getType(path)
-
-Get the type of a path.
-
-```lua
-local type = sfs:getType("/tmp/test.txt")
--- Returns: "file", "directory", or nil
-```
-
-**Returns:** `"file"`, `"directory"`, or `nil`
-
-#### fileName(path)
-
-Get the filename (last component) from a path.
-
-```lua
-local name = sfs:fileName("/tmp/subdir/file.txt")
--- Returns: "file.txt"
-
-local name = sfs:fileName("/tmp")
--- Returns: "tmp"
-
-local name = sfs:fileName("/")
--- Returns: "/"
-```
-
-**Returns:** `filename, error`
-
-#### parentDir(path)
-
-Get the parent directory path.
-
-```lua
-local parent = sfs:parentDir("/tmp/subdir/file.txt")
--- Returns: "/tmp/subdir"
-
-local parent = sfs:parentDir("/tmp")
--- Returns: "/"
-
-local parent, err = sfs:parentDir("/")
--- Returns: nil, "Root has no parent"
-```
-
-**Returns:** `path, error`
-
-## Path Resolution
-
-### Absolute Paths
-
-All paths must start with `/`:
-
-```lua
-sfs:read("/tmp/test.txt") -- Valid
-sfs:read("tmp/test.txt") -- Invalid
-```
-
-### Relative Paths (. and ..)
-
-`.` and `..` work **only within** the sandbox:
-
-```lua
--- Allowed: stays within /tmp
-sfs:read("/tmp/subdir/../test.txt") -- Resolves to /tmp/test.txt
-
--- Blocked: tries to escape /tmp
-sfs:read("/tmp/../etc/passwd") -- Error: "Path outside allowed directories"
-```
-
-### Tilde Expansion
-
-`~` expands to the current user's home directory:
-
-```lua
-local sfs = SafeFS.new(root_fs, {"~/documents/*"}, "alice")
-
--- These are equivalent:
-sfs:write("~/documents/note.txt", "data")
-sfs:write("/home/alice/documents/note.txt", "data")
-```
-
-## Security Examples
-
-### Example 1: Path Traversal Attack
-
-```lua
-local sfs = SafeFS.new(root_fs, {"/tmp/*"})
-
--- Attacker tries to escape using ..
-local content, err = sfs:read("/tmp/../../../../etc/passwd")
--- Error: "Path outside allowed directories"
-
--- Path normalizes to /etc/passwd which is not in /tmp/*
-```
-
-### Example 2: Isolated App Data
-
-```lua
--- App 1 SafeFS
-local app1_fs = SafeFS.new(root_fs, {
- "/apps/com.app1/data/*"
-})
-
--- App 2 SafeFS
-local app2_fs = SafeFS.new(root_fs, {
- "/apps/com.app2/data/*"
-})
-
--- App 1 writes secret
-app1_fs:write("/apps/com.app1/data/secret.txt", "App 1 secret")
-
--- App 2 cannot access App 1's data
-local content = app2_fs:read("/apps/com.app1/data/secret.txt")
--- Error: "Path not in SafeFS"
-```
-
-### Example 3: Relative Paths Within Bounds
-
-```lua
-local sfs = SafeFS.new(root_fs, {"/tmp/*"})
-
-sfs:mkdir("/tmp/a/b/c")
-sfs:write("/tmp/a/b/c/file.txt", "test")
-
--- This works: stays in /tmp
-local content = sfs:read("/tmp/a/b/c/../../test.txt")
--- Resolves to /tmp/a/test.txt
-
--- This fails: escapes /tmp
-local content = sfs:read("/tmp/../etc/passwd")
--- Error: "Path outside allowed directories"
-```
-
-## Integration with LPM
-
-SafeFS is designed to work with the LPM (Lua Package Manager) for app sandboxing:
-
-```lua
-function LPM:run(app_name)
- local app_dir = "/apps/com.example.myapp"
-
- -- Create SafeFS with app-specific directories
- local safeFS = SafeFS.new(root_fs, {
- app_dir .. "/data/*",
- app_dir .. "/tmp/*",
- app_dir .. "/settings/*",
- "/tmp/*" -- Optional: shared temp directory
- })
-
- -- Create sandbox environment
- local sandbox = {
- -- Wrap SafeFS to support $ prefix
- io = {
- open = function(path, mode)
- path = path:gsub("^%$/", app_dir .. "/")
- return safeFS:open(path, mode)
- end
- },
- fs = safeFS,
- -- ... other sandbox globals
- }
-
- setfenv(app_code, sandbox)
- app_code()
-end
-```
-
-## Implementation Details
-
-### Deep Copy Isolation
-
-SafeFS creates **completely isolated** copies of directory trees:
-
-1. **Copy Node Structure**: Recursively copies all directories and files
-2. **Isolate References**: Sets parent pointers to the new tree, not the original
-3. **Validate Relationships**: Ensures no pointers escape the sandbox
-4. **Share Content**: File content is referenced (not copied) to save memory
-
-### Path Normalization Algorithm
-
-1. Remove leading/trailing whitespace
-2. Expand `~` to `/home/{user}`
-3. Ensure path starts with `/`
-4. Split path into components
-5. Process each component:
- - `.` - Skip (current directory)
- - `..` - Go up one level (if possible)
- - Other - Add to path
-6. Validate result is within allowed directories
-
-### Memory Efficiency
-
-- **Structure Copied**: Directory/file nodes are copied
-- **Content Shared**: File content strings are referenced, not duplicated
-- **Lazy Creation**: Directories are created on-demand for writes
-
-## Common Patterns
-
-### Pattern 1: App Data Storage
-
-```lua
-local sfs = SafeFS.new(root_fs, {
- "/apps/com.myapp/data/*",
- "/apps/com.myapp/settings/*"
-})
-
--- Save game state
-sfs:write("/apps/com.myapp/data/savegame.dat", gameState)
-
--- Load settings
-local settings = sfs:read("/apps/com.myapp/settings/config.txt")
-```
-
-### Pattern 2: Log Files
-
-```lua
-local sfs = SafeFS.new(root_fs, {"/tmp/*"})
-
-local log = sfs:open("/tmp/app.log", "a")
-log:write(os.date() .. ": Application started\n")
-log:write("Processing...\n")
-log:close()
-```
-
-### Pattern 3: User Documents
-
-```lua
-local sfs = SafeFS.new(root_fs, {"~/documents/*"}, "alice")
-
--- List user's documents
-local files = sfs:files("~/documents")
-for _, file in ipairs(files) do
- print(file)
-end
-```
-
-### Pattern 4: Temporary Working Directory
-
-```lua
-local sfs = SafeFS.new(root_fs, {"/tmp/work/*"})
-
--- Create working files
-sfs:write("/tmp/work/input.txt", inputData)
--- Process...
-local result = sfs:read("/tmp/work/output.txt")
--- Cleanup
-sfs:delete("/tmp/work/input.txt")
-sfs:delete("/tmp/work/output.txt")
-```
-
-## Error Handling
-
-All methods return `(result, error)`. Always check for errors:
-
-```lua
-local content, err = sfs:read("/tmp/test.txt")
-if not content then
- print("Failed to read: " .. (err or "unknown error"))
- return
-end
-
--- Use content safely
-process(content)
-```
-
-## Limitations
-
-1. **No Symlinks**: Symbolic links are not supported
-2. **No Permissions**: No file permission/ownership model (yet)
-3. **Memory-Only**: Changes exist only in the SafeFS instance
-4. **No File Metadata**: No modification times, sizes, etc.
-
-## Best Practices
-
-1. **Minimal Whitelist**: Only grant access to necessary directories
-2. **One Instance Per App**: Create separate SafeFS for each sandboxed app
-3. **Check Errors**: Always check return values for errors
-4. **Close Handles**: Always close file handles when done
-5. **Validate Input**: Validate paths from untrusted sources before use
-
-## Performance
-
-- **Creation**: O(n) where n = number of files in allowed directories
-- **Read/Write**: O(d) where d = path depth
-- **Directory Listing**: O(1) - just returns existing array
-- **Path Resolution**: O(p) where p = number of path components
-
-## Testing
-
-See `SAFEFS_EXAMPLE.lua` for comprehensive usage examples.
-
-## See Also
-
-- `LPM_README.md` - LPM package manager documentation
-- `os/libs/safefs.lua` - Implementation source code
-- `os/RamDisk.lua` - Underlying filesystem implementation
diff --git a/SAFEHTTP.md b/SAFEHTTP.md
@@ -1,777 +0,0 @@
-# SafeHTTP Documentation
-
-## Overview
-
-SafeHTTP is a sandboxed HTTP client library that provides secure, restricted HTTP access with domain whitelisting and callback-based asynchronous requests. Similar to SafeFS and SafeGFX, it enforces security boundaries to prevent applications from accessing unauthorized network resources.
-
-## Key Features
-
-- **Domain Whitelisting**: Only allow HTTP requests to approved domains
-- **Wildcard Patterns**: Support for `*.example.com` and `example.*` patterns
-- **Async Callbacks**: Non-blocking requests with success/error callbacks
-- **JSON Support**: Automatic JSON encoding for POST data
-- **Size Limits**: Prevent large response attacks
-- **Request Timeout**: Automatic timeout handling
-- **Concurrent Requests**: Handle multiple requests simultaneously
-- **Request Cancellation**: Cancel pending requests
-- **Security First**: Built with security as primary concern
-
-## Security Model
-
-SafeHTTP implements a strict whitelist security model:
-
-1. **Explicit Domain Approval**: Applications must declare allowed domains upfront
-2. **No Dynamic Domain Addition**: Cannot modify allowed domains after creation
-3. **Protocol Validation**: URLs are normalized and validated
-4. **Size Limits**: Responses limited to prevent memory exhaustion
-5. **Timeout Protection**: Prevents infinite waiting
-6. **Error Isolation**: Callback errors don't crash the application
-
-## Basic Usage
-
-### Creating a SafeHTTP Instance
-
-```lua
-local SafeHTTP = require("SafeHTTP")
-local NetworkStack = require("NetworkStack")
-
--- Single domain
-local http = SafeHTTP.new(NetworkStack, "example.com")
-
--- Multiple domains
-local http = SafeHTTP.new(NetworkStack, {
- "example.com",
- "api.example.com",
- "cdn.example.com"
-})
-
--- With options
-local http = SafeHTTP.new(NetworkStack, "example.com", {
- timeout = 30, -- Request timeout in seconds
- max_size = 1048576, -- Max response size (1MB)
- user_agent = "MyApp/1.0"
-})
-```
-
-### GET Request
-
-```lua
-http:get("http://example.com/api/data",
- function(response)
- -- Success callback
- print("Status:", response.status)
- print("Body:", response.body)
- end,
- function(error_msg)
- -- Error callback (optional)
- print("Error:", error_msg)
- end
-)
-
--- Must poll to process requests
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-### POST Request
-
-```lua
--- POST with JSON data (table)
-http:post("http://example.com/api/submit",
- {
- name = "John Doe",
- email = "john@example.com",
- age = 30
- },
- function(response)
- print("Posted successfully:", response.status)
- end,
- function(error_msg)
- print("Post failed:", error_msg)
- end
-)
-
--- POST with string data
-http:post("http://example.com/api/text",
- "plain text data",
- function(response)
- print("Response:", response.body)
- end
-)
-```
-
-## Domain Patterns
-
-### Exact Match
-
-```lua
-local http = SafeHTTP.new(NetworkStack, "example.com")
-
--- Allowed:
-http:get("http://example.com/")
-http:get("https://example.com/api")
-
--- Blocked:
-http:get("http://api.example.com/") -- Subdomain not allowed
-http:get("http://evil.com/")
-```
-
-### Wildcard Subdomain
-
-```lua
-local http = SafeHTTP.new(NetworkStack, "*.example.com")
-
--- Allowed:
-http:get("http://www.example.com/")
-http:get("http://api.example.com/")
-http:get("http://cdn.example.com/")
-
--- Blocked:
-http:get("http://example.com/") -- Base domain needs subdomain
-```
-
-### Wildcard TLD
-
-```lua
-local http = SafeHTTP.new(NetworkStack, "example.*")
-
--- Allowed:
-http:get("http://example.com/")
-http:get("http://example.org/")
-http:get("http://example.net/")
-```
-
-### IP Addresses
-
-```lua
-local http = SafeHTTP.new(NetworkStack, {
- "10.0.2.2",
- "192.168.1.*"
-})
-
--- Allowed:
-http:get("http://10.0.2.2/")
-http:get("http://192.168.1.100/")
-```
-
-## API Reference
-
-### Constructor
-
-#### SafeHTTP.new(NetworkStack, allowedDomains, options)
-
-Create a new SafeHTTP instance.
-
-**Parameters:**
-- `NetworkStack` (table): Network stack instance
-- `allowedDomains` (string|table): Domain(s) to whitelist
-- `options` (table, optional):
- - `timeout` (number): Request timeout in seconds (default: 30)
- - `max_size` (number): Max response size in bytes (default: 1048576)
- - `user_agent` (string): User-Agent header (default: "LuajitOS-SafeHTTP/1.0")
-
-**Returns:**
-- SafeHTTP instance
-
-**Example:**
-```lua
-local http = SafeHTTP.new(NetworkStack, "example.com", {
- timeout = 60,
- max_size = 5242880 -- 5MB
-})
-```
-
-### Methods
-
-#### http:get(url, success_callback, error_callback)
-
-Perform HTTP GET request.
-
-**Parameters:**
-- `url` (string): URL to request
-- `success_callback` (function): Called on success with `response` parameter
-- `error_callback` (function, optional): Called on error with `error_msg` parameter
-
-**Returns:**
-- `boolean`: True if request started, false if validation failed
-
-**Response Object:**
-```lua
-{
- version = "HTTP/1.1",
- status = 200,
- reason = "OK",
- headers = {["content-type"] = "text/html", ...},
- body = "response body..."
-}
-```
-
-**Example:**
-```lua
-local started = http:get("http://example.com/api",
- function(response)
- if response.status == 200 then
- print("Success:", response.body)
- end
- end,
- function(error_msg)
- print("Failed:", error_msg)
- end
-)
-
-if started then
- while http:getActiveRequestCount() > 0 do
- http:poll()
- end
-end
-```
-
-#### http:post(url, data, success_callback, error_callback)
-
-Perform HTTP POST request.
-
-**Parameters:**
-- `url` (string): URL to request
-- `data` (table|string): Data to post (table = JSON, string = raw)
-- `success_callback` (function): Called on success
-- `error_callback` (function, optional): Called on error
-
-**Returns:**
-- `boolean`: True if request started
-
-**Example:**
-```lua
-http:post("http://example.com/api/users",
- {username = "john", email = "john@example.com"},
- function(response)
- print("Created:", response.status)
- end,
- function(error_msg)
- print("Error:", error_msg)
- end
-)
-```
-
-#### http:poll()
-
-Process pending requests. **Must be called regularly** in your main loop.
-
-**Example:**
-```lua
--- In main loop
-while running do
- http:poll()
- -- Other processing...
-end
-```
-
-#### http:isDomainAllowed(domain)
-
-Check if a domain is allowed.
-
-**Parameters:**
-- `domain` (string): Domain to check
-
-**Returns:**
-- `boolean`: True if domain is allowed
-
-**Example:**
-```lua
-if http:isDomainAllowed("example.com") then
- print("Domain is allowed")
-end
-```
-
-#### http:validateURL(url)
-
-Validate and normalize a URL.
-
-**Parameters:**
-- `url` (string): URL to validate
-
-**Returns:**
-- `string|nil`: Normalized URL or nil if invalid
-- `string|nil`: Error message if invalid
-
-**Example:**
-```lua
-local normalized, err = http:validateURL("www.example.com/path")
-if normalized then
- print("Valid:", normalized)
-else
- print("Invalid:", err)
-end
-```
-
-#### http:cancelRequest(request_id)
-
-Cancel a specific request.
-
-**Parameters:**
-- `request_id` (number): Request ID to cancel
-
-#### http:cancelAll()
-
-Cancel all active requests.
-
-**Example:**
-```lua
--- Start requests
-http:get("http://example.com/page1", on_success, on_error)
-http:get("http://example.com/page2", on_success, on_error)
-
--- Cancel all
-http:cancelAll()
-```
-
-#### http:getActiveRequestCount()
-
-Get number of active requests.
-
-**Returns:**
-- `number`: Number of active requests
-
-**Example:**
-```lua
-print("Active requests:", http:getActiveRequestCount())
-```
-
-#### http:getAllowedDomains()
-
-Get list of allowed domain patterns.
-
-**Returns:**
-- `table`: Array of domain patterns
-
-**Example:**
-```lua
-local domains = http:getAllowedDomains()
-for _, domain in ipairs(domains) do
- print("Allowed:", domain)
-end
-```
-
-## Complete Examples
-
-### Simple GET Request
-
-```lua
-local SafeHTTP = require("SafeHTTP")
-local NetworkStack = require("NetworkStack")
-
--- Initialize network
--- ... (network initialization)
-
--- Create SafeHTTP
-local http = SafeHTTP.new(NetworkStack, "api.example.com")
-
--- Make request
-http:get("http://api.example.com/status",
- function(response)
- print("API Status:", response.body)
- end,
- function(error_msg)
- print("API Error:", error_msg)
- end
-)
-
--- Process request
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-### POST JSON Data
-
-```lua
-local http = SafeHTTP.new(NetworkStack, "api.example.com")
-
-local user_data = {
- username = "alice",
- email = "alice@example.com",
- age = 25
-}
-
-http:post("http://api.example.com/users", user_data,
- function(response)
- if response.status == 201 then
- print("User created successfully!")
- end
- end,
- function(error_msg)
- print("Failed to create user:", error_msg)
- end
-)
-
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-### Multiple Concurrent Requests
-
-```lua
-local http = SafeHTTP.new(NetworkStack, {"api.example.com", "cdn.example.com"})
-
-local completed = 0
-local results = {}
-
-local function on_complete(url)
- return function(response)
- completed = completed + 1
- results[url] = response.body
- print("Completed:", url)
- end
-end
-
-local function on_error(url)
- return function(error_msg)
- completed = completed + 1
- results[url] = "ERROR: " .. error_msg
- print("Failed:", url)
- end
-end
-
--- Start multiple requests
-local urls = {
- "http://api.example.com/users",
- "http://api.example.com/posts",
- "http://cdn.example.com/images"
-}
-
-for _, url in ipairs(urls) do
- http:get(url, on_complete(url), on_error(url))
-end
-
--- Wait for all to complete
-while completed < #urls do
- http:poll()
-end
-
--- Process results
-for url, result in pairs(results) do
- print(url, ":", result:sub(1, 50))
-end
-```
-
-### Application-Specific HTTP Client
-
-```lua
--- weather_app.lua
-local WeatherAPI = {}
-
-function WeatherAPI.new(NetworkStack)
- local instance = {
- http = SafeHTTP.new(NetworkStack, "api.weather.example.com", {
- timeout = 10,
- user_agent = "WeatherApp/1.0"
- })
- }
-
- function instance.getCurrentWeather(city, callback)
- local url = "http://api.weather.example.com/current?city=" ..
- HTTP.url_encode(city)
-
- instance.http:get(url,
- function(response)
- if response.status == 200 then
- -- Parse weather data
- callback(true, response.body)
- else
- callback(false, "HTTP " .. response.status)
- end
- end,
- function(error_msg)
- callback(false, error_msg)
- end
- )
- end
-
- function instance.poll()
- instance.http:poll()
- end
-
- return instance
-end
-
--- Usage
-local weather = WeatherAPI.new(NetworkStack)
-weather.getCurrentWeather("London", function(success, data)
- if success then
- print("Weather:", data)
- else
- print("Error:", data)
- end
-end)
-
-while weather.http:getActiveRequestCount() > 0 do
- weather.poll()
-end
-```
-
-### Integration with Scheduler
-
-```lua
--- If you have a scheduler/event loop
-local http = SafeHTTP.new(NetworkStack, "example.com")
-
--- Make request
-http:get("http://example.com/api/data",
- function(response)
- print("Got response:", response.status)
- end
-)
-
--- Add polling task to scheduler
-scheduler.addTask(function()
- while true do
- http:poll()
- coroutine.yield()
- end
-end, "http-poller")
-```
-
-## Security Best Practices
-
-### 1. Principle of Least Privilege
-
-Only whitelist domains that are absolutely necessary:
-
-```lua
--- Good: Specific domains
-local http = SafeHTTP.new(NetworkStack, {
- "api.myapp.com",
- "cdn.myapp.com"
-})
-
--- Bad: Overly permissive
-local http = SafeHTTP.new(NetworkStack, "*") -- Don't do this!
-```
-
-### 2. Validate Callback Data
-
-Always validate data in success callbacks:
-
-```lua
-http:get(url, function(response)
- -- Validate status
- if response.status ~= 200 then
- print("Unexpected status:", response.status)
- return
- end
-
- -- Validate content
- if not response.body or #response.body == 0 then
- print("Empty response")
- return
- end
-
- -- Validate content type
- local content_type = response.headers["content-type"] or ""
- if not content_type:match("application/json") then
- print("Unexpected content type")
- return
- end
-
- -- Process safely
- process_data(response.body)
-end)
-```
-
-### 3. Set Appropriate Limits
-
-Configure timeout and size limits based on your needs:
-
-```lua
--- For JSON API (small responses)
-local api_http = SafeHTTP.new(NetworkStack, "api.example.com", {
- timeout = 10,
- max_size = 102400 -- 100KB
-})
-
--- For downloading files (larger responses)
-local cdn_http = SafeHTTP.new(NetworkStack, "cdn.example.com", {
- timeout = 60,
- max_size = 10485760 -- 10MB
-})
-```
-
-### 4. Handle Errors Gracefully
-
-Always provide error callbacks:
-
-```lua
-http:get(url,
- function(response)
- -- Success handling
- end,
- function(error_msg)
- -- Log error
- print("HTTP Error:", error_msg)
-
- -- Take appropriate action
- if error_msg:match("timeout") then
- retry_request()
- elseif error_msg:match("Domain not allowed") then
- show_permission_error()
- else
- show_generic_error()
- end
- end
-)
-```
-
-### 5. Avoid Sensitive Data in URLs
-
-Don't put secrets in query parameters:
-
-```lua
--- Bad: Secret in URL
-http:get("http://api.example.com/data?api_key=SECRET123", ...)
-
--- Good: Use POST with body, or custom headers
-http:post("http://api.example.com/data",
- {api_key = "SECRET123"},
- ...
-)
-```
-
-### 6. Clean Up Resources
-
-Cancel requests when no longer needed:
-
-```lua
-local http = SafeHTTP.new(NetworkStack, "example.com")
-
--- Start long request
-http:get("http://example.com/large-file", on_success, on_error)
-
--- User navigates away
-function on_page_exit()
- http:cancelAll()
-end
-```
-
-## Error Handling
-
-SafeHTTP provides detailed error messages:
-
-| Error | Meaning |
-|-------|---------|
-| `Domain not allowed: example.com` | URL domain not in whitelist |
-| `Invalid URL` | Malformed URL |
-| `Could not resolve host` | DNS/IP resolution failed |
-| `Connection failed` | TCP connection failed |
-| `Request timeout` | Request exceeded timeout |
-| `Response too large` | Response exceeded max_size |
-| `Socket library not available` | Socket library not loaded |
-| `HTTP library not available` | HTTP library not loaded |
-| `Empty response` | Server returned no data |
-| `Failed to parse response` | Invalid HTTP response |
-| `Request cancelled` | Request was cancelled |
-
-## Comparison with HTTP Library
-
-| Feature | HTTP Library | SafeHTTP |
-|---------|-------------|----------|
-| Domain restriction | ❌ No | ✅ Yes |
-| Async callbacks | ❌ No | ✅ Yes |
-| Blocking requests | ✅ Yes | ❌ No |
-| Size limits | ❌ No | ✅ Yes |
-| Timeout handling | ✅ Manual | ✅ Automatic |
-| Request cancellation | ❌ No | ✅ Yes |
-| Concurrent requests | ⚠️ Limited | ✅ Yes |
-| Security focus | ⚠️ Basic | ✅ High |
-
-**When to use HTTP Library:**
-- System-level code
-- Administrative tools
-- When you need access to all domains
-
-**When to use SafeHTTP:**
-- User applications
-- Third-party apps
-- Sandboxed environments
-- When security is critical
-
-## Performance Considerations
-
-1. **Polling Frequency**: Call `poll()` frequently (every frame/tick) for best responsiveness
-2. **Concurrent Requests**: Limited by TCP stack (typically 1-4 concurrent)
-3. **Memory Usage**: ~10KB per active request + response size
-4. **Throughput**: ~2-4 Mbps (limited by underlying TCP implementation)
-
-## Limitations
-
-1. **No HTTPS**: SSL/TLS not yet implemented (plaintext only)
-2. **No DNS**: Must use IP addresses or known hosts
-3. **No Redirects**: Redirect handling not implemented
-4. **No Cookies**: Cookie management not implemented
-5. **No Streaming**: Entire response buffered in memory
-6. **No Proxy**: Proxy support not implemented
-
-## Testing
-
-### Running SafeHTTP Test App
-
-```lua
-lpm.run("com.luajitos.safehttptest")
-```
-
-### Unit Testing Example
-
-```lua
--- test_safehttp.lua
-local function test_domain_validation()
- local http = SafeHTTP.new(NetworkStack, "example.com")
-
- -- Test allowed domain
- assert(http:isDomainAllowed("example.com"))
-
- -- Test blocked domain
- assert(not http:isDomainAllowed("evil.com"))
-
- print("Domain validation tests passed!")
-end
-
-test_domain_validation()
-```
-
-## Troubleshooting
-
-**Q: Callbacks not being called**
-- Make sure you're calling `http:poll()` regularly
-- Check network is initialized
-- Verify domain is in whitelist
-
-**Q: Request timeout**
-- Increase timeout in options
-- Check network connectivity
-- Verify target server is reachable
-
-**Q: "Domain not allowed" error**
-- Check domain spelling in whitelist
-- Verify URL includes correct protocol
-- Remember wildcards must match exactly
-
-**Q: Memory issues with large responses**
-- Reduce `max_size` option
-- Request smaller chunks
-- Stream data if possible (future feature)
-
-## Future Enhancements
-
-- [ ] HTTPS/TLS support
-- [ ] DNS resolution
-- [ ] HTTP redirect following (with max limit)
-- [ ] Cookie jar support
-- [ ] Response streaming
-- [ ] Request queuing
-- [ ] Connection pooling
-- [ ] Proxy support
-- [ ] HTTP/2 support
-
-## License
-
-Part of LuajitOS - see main project license.
diff --git a/SANDBOXED_HTTP.md b/SANDBOXED_HTTP.md
@@ -1,591 +0,0 @@
-# Sandboxed HTTP Access for Applications
-
-## Overview
-
-LuajitOS provides automatic sandboxed HTTP access to applications through the `http` global variable. When an app declares `network` permission and specifies `allowedDomains` in its manifest, it automatically receives a SafeHTTP instance.
-
-## Quick Start
-
-### 1. Declare Permissions in Manifest
-
-```lua
--- manifest.lua
-return {
- name = "My App",
- identifier = "com.developer.myapp",
- version = "1.0.0",
- author = "Developer Name",
- developer = "Developer Name",
- description = "My application description",
- executable = "/apps/com.developer.myapp/src/main.lua",
-
- -- Request network permission
- permissions = {
- network = true,
- },
-
- -- Specify allowed domains
- allowedDomains = {
- "api.example.com",
- "*.myservice.com", -- Wildcard for subdomains
- "10.0.2.2" -- Local IP for testing
- }
-}
-```
-
-### 2. Use HTTP in Your App
-
-```lua
--- main.lua
-
--- http global is automatically available!
--- No need to require() or load anything
-
--- Make GET request
-http:get("http://api.example.com/data",
- function(response)
- -- Success callback
- osprint("Status: " .. response.status)
- osprint("Body: " .. response.body)
- end,
- function(error_msg)
- -- Error callback (optional)
- osprint("Error: " .. error_msg)
- end
-)
-
--- Poll to process requests
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-## Complete Example
-
-```lua
--- manifest.lua
-return {
- name = "Weather App",
- identifier = "com.mycompany.weather",
- version = "1.0.0",
- author = "My Company",
- developer = "My Company",
- description = "Shows current weather",
- executable = "/apps/com.mycompany.weather/src/main.lua",
- permissions = { network = true },
- allowedDomains = { "api.weather.com", "wttr.in" }
-}
-```
-
-```lua
--- main.lua
-osprint("Fetching weather data...\n")
-
-http:get("http://api.weather.com/current",
- function(response)
- if response.status == 200 then
- osprint("Weather: " .. response.body .. "\n")
- else
- osprint("HTTP " .. response.status .. "\n")
- end
- end,
- function(error_msg)
- osprint("Failed: " .. error_msg .. "\n")
- end
-)
-
--- Process request
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-
-osprint("Done!\n")
-```
-
-## API Reference
-
-The `http` global variable is a SafeHTTP instance with these methods:
-
-### http:get(url, success_callback, error_callback)
-
-Make HTTP GET request.
-
-```lua
-http:get("http://api.example.com/users",
- function(response)
- -- response.status = 200
- -- response.headers = {...}
- -- response.body = "..."
- end,
- function(error_msg)
- -- Handle error
- end
-)
-```
-
-### http:post(url, data, success_callback, error_callback)
-
-Make HTTP POST request with automatic JSON encoding.
-
-```lua
--- Post table (auto-encoded as JSON)
-http:post("http://api.example.com/users",
- {
- name = "John Doe",
- email = "john@example.com"
- },
- function(response)
- osprint("Created: " .. response.status)
- end
-)
-
--- Post string (sent as-is)
-http:post("http://api.example.com/text",
- "plain text data",
- function(response)
- -- Handle response
- end
-)
-```
-
-### http:poll()
-
-Process pending HTTP requests. **Must be called regularly** in your main loop.
-
-```lua
--- Simple polling loop
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-
--- Or in scheduler
-scheduler.addTask(function()
- while true do
- http:poll()
- coroutine.yield()
- end
-end, "http-poller")
-```
-
-### http:getActiveRequestCount()
-
-Get number of active HTTP requests.
-
-```lua
-local count = http:getActiveRequestCount()
-osprint("Active requests: " .. count)
-```
-
-### http:getAllowedDomains()
-
-Get list of allowed domains.
-
-```lua
-local domains = http:getAllowedDomains()
-for _, domain in ipairs(domains) do
- osprint("Allowed: " .. domain)
-end
-```
-
-### http:isDomainAllowed(domain)
-
-Check if domain is allowed.
-
-```lua
-if http:isDomainAllowed("api.example.com") then
- osprint("Domain is allowed")
-end
-```
-
-### http:validateURL(url)
-
-Validate URL against allowed domains.
-
-```lua
-local valid, err = http:validateURL("http://example.com/path")
-if valid then
- osprint("URL is valid: " .. valid)
-else
- osprint("URL blocked: " .. err)
-end
-```
-
-### http:cancelAll()
-
-Cancel all pending requests.
-
-```lua
--- Start requests
-http:get("http://api.example.com/page1", ...)
-http:get("http://api.example.com/page2", ...)
-
--- Cancel all
-http:cancelAll()
-```
-
-## Domain Patterns
-
-### Exact Match
-```lua
-allowedDomains = { "api.example.com" }
--- Allows: api.example.com
--- Blocks: www.example.com, example.com
-```
-
-### Wildcard Subdomain
-```lua
-allowedDomains = { "*.example.com" }
--- Allows: www.example.com, api.example.com, cdn.example.com
--- Blocks: example.com (base domain needs subdomain)
-```
-
-### Wildcard TLD
-```lua
-allowedDomains = { "example.*" }
--- Allows: example.com, example.org, example.net
-```
-
-### IP Addresses
-```lua
-allowedDomains = { "10.0.2.2", "192.168.1.*" }
--- Allows specific IPs or ranges
-```
-
-### Multiple Domains
-```lua
-allowedDomains = {
- "api.myapp.com",
- "cdn.myapp.com",
- "*.thirdparty.com",
- "10.0.2.2"
-}
-```
-
-## Security Model
-
-### Automatic Sandboxing
-
-1. **Declaration Required**: Apps must declare `network` permission in manifest
-2. **Domain Whitelist**: Apps must list `allowedDomains` in manifest
-3. **Automatic Provision**: Sandbox automatically provides `http` instance
-4. **Enforcement**: HTTP requests blocked if domain not in whitelist
-5. **Isolation**: Each app gets isolated HTTP instance
-
-### What's Protected
-
-- ✅ **Domain Restriction**: Apps can only access declared domains
-- ✅ **No Escape**: Apps cannot modify allowed domains list
-- ✅ **Size Limits**: Responses limited to prevent memory attacks (default: 10MB)
-- ✅ **Timeouts**: Requests automatically timeout (default: 30 seconds)
-- ✅ **Error Isolation**: Callback errors don't crash the system
-
-### What's Not Protected (Yet)
-
-- ❌ **No HTTPS**: All traffic is plaintext (SSL/TLS not implemented)
-- ❌ **No Rate Limiting**: Apps can make unlimited requests
-- ❌ **No Bandwidth Control**: No per-app bandwidth limits
-- ❌ **No DNS Security**: DNS resolution not secured
-
-## Best Practices
-
-### 1. Minimal Domain List
-
-Only whitelist domains you actually need:
-
-```lua
--- Good: Specific domains
-allowedDomains = { "api.myapp.com", "cdn.myapp.com" }
-
--- Bad: Overly permissive
-allowedDomains = { "*" } -- Don't do this!
-```
-
-### 2. Always Handle Errors
-
-Provide error callbacks for all requests:
-
-```lua
-http:get(url,
- function(response)
- -- Handle success
- end,
- function(error_msg)
- -- IMPORTANT: Handle errors
- osprint("Error: " .. error_msg)
- end
-)
-```
-
-### 3. Validate Responses
-
-Don't trust response data:
-
-```lua
-http:get(url, function(response)
- -- Check status
- if response.status ~= 200 then
- osprint("Bad status: " .. response.status)
- return
- end
-
- -- Check content type
- local content_type = response.headers["content-type"] or ""
- if not content_type:match("application/json") then
- osprint("Unexpected content type")
- return
- end
-
- -- Validate data before use
- if not response.body or #response.body == 0 then
- osprint("Empty response")
- return
- end
-
- -- Now process safely
- process_data(response.body)
-end)
-```
-
-### 4. Poll Regularly
-
-Call `http:poll()` frequently:
-
-```lua
--- In main loop
-while running do
- http:poll()
- -- Other processing
-end
-
--- Or with scheduler
-scheduler.addTask(function()
- while true do
- http:poll()
- coroutine.yield()
- end
-end, "http-poll")
-```
-
-### 5. Clean Up Resources
-
-Cancel requests when done:
-
-```lua
--- User closes window
-function onClose()
- http:cancelAll()
-end
-```
-
-## Common Patterns
-
-### Loading Indicator
-
-```lua
-local loading = true
-
-osprint("Loading...")
-
-http:get(url,
- function(response)
- loading = false
- osprint("Done! " .. response.body)
- end,
- function(error_msg)
- loading = false
- osprint("Error: " .. error_msg)
- end
-)
-
-while loading do
- http:poll()
- -- Update UI
-end
-```
-
-### API Wrapper
-
-```lua
-local API = {}
-
-function API.getCurrentWeather(city, callback)
- http:get("http://api.weather.com/current?city=" .. city,
- function(response)
- if response.status == 200 then
- callback(true, response.body)
- else
- callback(false, "HTTP " .. response.status)
- end
- end,
- function(error_msg)
- callback(false, error_msg)
- end
- )
-end
-
--- Usage
-API.getCurrentWeather("London", function(success, data)
- if success then
- osprint("Weather: " .. data)
- else
- osprint("Error: " .. data)
- end
-end)
-```
-
-### Multiple Requests
-
-```lua
-local completed = 0
-local total = 3
-local results = {}
-
-local function on_complete(id)
- return function(response)
- completed = completed + 1
- results[id] = response.body
- end
-end
-
--- Start all requests
-for i = 1, total do
- http:get("http://api.example.com/item" .. i, on_complete(i))
-end
-
--- Wait for all
-while completed < total do
- http:poll()
-end
-
--- Process results
-for id, data in pairs(results) do
- osprint("Item " .. id .. ": " .. data)
-end
-```
-
-## Error Messages
-
-| Error | Meaning | Solution |
-|-------|---------|----------|
-| `Domain not allowed: example.com` | URL domain not whitelisted | Add domain to manifest `allowedDomains` |
-| `Invalid URL` | Malformed URL | Check URL format |
-| `Connection failed` | Cannot connect to server | Check network, server availability |
-| `Request timeout` | Request took too long | Increase timeout, check server response time |
-| `Response too large` | Response exceeded size limit | Request smaller data, increase `max_size` |
-| `NetworkStack not available` | Network not initialized | Initialize network before running app |
-
-## Troubleshooting
-
-### http global not available
-
-**Problem**: `http` is nil in your app
-
-**Solutions**:
-1. Check manifest has `permissions = { network = true }`
-2. Check manifest has `allowedDomains = {...}`
-3. Ensure NetworkStack is initialized in system
-
-### Requests always fail
-
-**Problem**: All requests return errors
-
-**Solutions**:
-1. Check domain is in `allowedDomains` list
-2. Verify network is initialized
-3. Check QEMU network configuration
-4. Test with local IP (10.0.2.2) first
-
-### Callbacks not called
-
-**Problem**: Success/error callbacks never execute
-
-**Solutions**:
-1. Ensure you're calling `http:poll()` regularly
-2. Check for infinite loops blocking poll
-3. Verify request actually started (check return value)
-
-## Testing
-
-### Running Example App
-
-```bash
-# From LuajitOS shell
-lpm.run("com.luajitos.weatherapp")
-```
-
-### Testing with Local Server
-
-1. Start simple HTTP server on host:
-```bash
-python3 -m http.server 8080
-```
-
-2. Run QEMU with port forwarding:
-```bash
-qemu-system-x86_64 \
- -netdev user,id=net0,hostfwd=tcp::8080-:8080 \
- -device rtl8139,netdev=net0 \
- -cdrom luajitos.iso
-```
-
-3. Add to manifest:
-```lua
-allowedDomains = { "10.0.2.2" }
-```
-
-## Migration Guide
-
-### From HTTP Library
-
-Before (HTTP library):
-```lua
-local HTTP = require("HTTP")
-local client = HTTP.create_client(NetworkStack)
-local response = client.get("http://example.com/")
-```
-
-After (Sandboxed):
-```lua
--- In manifest.lua:
--- allowedDomains = { "example.com" }
-
--- In main.lua:
-http:get("http://example.com/",
- function(response)
- -- Use response
- end
-)
-
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-### From SafeHTTP Direct
-
-Before (manual SafeHTTP):
-```lua
-local SafeHTTP = require("SafeHTTP")
-local http = SafeHTTP.new(NetworkStack, {"example.com"})
-```
-
-After (automatic):
-```lua
--- Just use http global - it's automatic!
--- Declare in manifest:
--- permissions = { network = true }
--- allowedDomains = { "example.com" }
-```
-
-## See Also
-
-- **SafeHTTP.md** - Full SafeHTTP API reference
-- **HTTP_LIBRARY.md** - Low-level HTTP library docs
-- **NETWORK_STACK.md** - Network stack overview
-- **Example Apps**:
- - `/apps/com.luajitos.weatherapp/` - Sandboxed HTTP example
- - `/apps/com.luajitos.safehttptest/` - SafeHTTP test suite
-
-## License
-
-Part of LuajitOS - see main project license.
diff --git a/SANDBOXED_HTTP_SUMMARY.md b/SANDBOXED_HTTP_SUMMARY.md
@@ -1,334 +0,0 @@
-# Sandboxed HTTP - Implementation Summary
-
-## What Was Implemented
-
-Apps that request `network` permission now automatically receive a sandboxed SafeHTTP instance in their global environment as `http`.
-
-## How It Works
-
-### 1. App Declares Permissions
-
-```lua
--- manifest.lua
-return {
- name = "My App",
- -- ... other fields ...
- permissions = {
- network = true, -- Request network access
- },
- allowedDomains = {
- "api.example.com", -- Whitelist allowed domains
- "*.myservice.com",
- "10.0.2.2"
- }
-}
-```
-
-### 2. Sandbox Automatically Provides HTTP
-
-When run.lua loads the app, it:
-1. Checks if app has `network` permission
-2. Loads SafeHTTP library
-3. Creates SafeHTTP instance with `allowedDomains` from manifest
-4. Injects as `http` global in app's sandbox environment
-
-### 3. App Uses HTTP
-
-```lua
--- main.lua
--- http is automatically available!
-
-http:get("http://api.example.com/data",
- function(response)
- osprint("Got: " .. response.body)
- end,
- function(error_msg)
- osprint("Error: " .. error_msg)
- end
-)
-
--- Poll to process
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-## Code Changes
-
-### run.lua (lines 758-822)
-
-Added network permission check and SafeHTTP integration:
-
-```lua
--- Check for network permission and setup SafeHTTP
-local has_network = false
-for _, perm in ipairs(permissions) do
- if perm == "network" then
- has_network = true
- break
- end
-end
-
-if has_network and fsRoot then
- -- Load SafeHTTP module
- local safehttp_path = "/os/libs/SafeHTTP.lua"
- local safehttp_code = read_from_ramdisk(fsRoot, safehttp_path)
-
- if safehttp_code then
- local safehttp_func, err = load(safehttp_code, safehttp_path, "t")
-
- if safehttp_func then
- local success, SafeHTTP = pcall(safehttp_func)
-
- if success and SafeHTTP then
- -- Get allowed domains from manifest
- local allowed_domains = manifest.allowedDomains or {}
-
- if #allowed_domains == 0 then
- -- Warn if no domains specified
- osprint("Warning: Network permission granted but no allowedDomains specified\n")
- else
- -- Check NetworkStack available
- if _G.NetworkStack then
- -- Create SafeHTTP instance
- local http_instance = SafeHTTP.new(_G.NetworkStack, allowed_domains, {
- timeout = 30,
- max_size = 10485760, -- 10MB
- user_agent = manifest.name .. "/" .. (manifest.version or "1.0")
- })
-
- -- Add to sandbox environment
- sandbox_env.http = http_instance
-
- osprint("Network access granted to domains:\n")
- for _, domain in ipairs(allowed_domains) do
- osprint(" " .. domain .. "\n")
- end
- else
- osprint("Warning: NetworkStack not available\n")
- end
- end
- end
- end
- end
-end
-```
-
-## Files Created/Modified
-
-### Modified
-- `/os/libs/run.lua` - Added SafeHTTP integration (lines 758-822)
-
-### Created
-- `/os/libs/SafeHTTP.lua` - Sandboxed HTTP library
-- `/apps/com.luajitos.weatherapp/` - Example app using sandboxed HTTP
-- `/apps/com.luajitos.safehttptest/` - SafeHTTP test suite
-- `SAFEHTTP.md` - Full SafeHTTP documentation
-- `SANDBOXED_HTTP.md` - App developer guide
-- `SANDBOXED_HTTP_SUMMARY.md` - This file
-
-## Security Model
-
-### Enforced by Sandbox
-
-1. **Domain Whitelist**: Apps declare allowed domains in manifest
-2. **Automatic Injection**: `http` provided only if permission granted
-3. **Domain Validation**: All URLs validated before sending
-4. **No Escape**: Apps cannot modify allowed domains
-5. **Isolated Instances**: Each app gets separate SafeHTTP instance
-
-### Similar to Existing Sandboxes
-
-Just like SafeFS and SafeGFX:
-- ✅ Permissions declared in manifest
-- ✅ Automatically provided to sandbox
-- ✅ Isolated per-app instances
-- ✅ Whitelist-based access control
-- ✅ No way to escape restrictions
-
-## Usage Example
-
-### Simple Weather App
-
-```lua
--- manifest.lua
-return {
- name = "Weather",
- identifier = "com.example.weather",
- version = "1.0",
- author = "Dev",
- developer = "Dev",
- description = "Weather app",
- executable = "/apps/com.example.weather/src/main.lua",
- permissions = { network = true },
- allowedDomains = { "api.weather.com" }
-}
-```
-
-```lua
--- main.lua
-osprint("Fetching weather...\n")
-
-http:get("http://api.weather.com/current?city=London",
- function(response)
- osprint("Weather: " .. response.body .. "\n")
- end,
- function(error_msg)
- osprint("Error: " .. error_msg .. "\n")
- end
-)
-
-while http:getActiveRequestCount() > 0 do
- http:poll()
-end
-```
-
-### Run It
-
-```bash
-lpm.run("com.example.weather")
-```
-
-## Benefits
-
-### For App Developers
-
-1. **Automatic Setup**: No need to manually create SafeHTTP
-2. **Declarative**: Permissions in manifest.lua
-3. **Simple API**: Just use `http` global
-4. **Secure by Default**: Domain restrictions enforced automatically
-
-### For System Security
-
-1. **Explicit Declaration**: Apps must declare network permission
-2. **Domain Whitelisting**: Apps can only access declared domains
-3. **Sandboxed**: Each app isolated from others
-4. **Auditable**: Manifest shows exactly what domains app can access
-
-### For Users
-
-1. **Transparency**: Can see allowed domains in manifest
-2. **Security**: Apps can't access unauthorized sites
-3. **Trust**: System enforces restrictions, not apps
-
-## Testing
-
-### Run Example App
-
-```bash
-# From LuajitOS
-lpm.run("com.luajitos.weatherapp")
-```
-
-### Expected Output
-
-```
-=== Weather App ===
-
-SafeHTTP instance available!
-
-Allowed domains:
- - api.weather.com
- - wttr.in
- - api.openweathermap.org
- - 10.0.2.2
-
-=== Test 1: Accessing Allowed Domain ===
-Making request to 10.0.2.2 (allowed)...
-SUCCESS! Status: 200
-Response received from allowed domain
-
-=== Test 2: Accessing Blocked Domain ===
-Attempting to access evil-site.com (blocked)...
-CORRECT: Request blocked
-Error: Domain not allowed: evil-site.com
-
-... (more tests) ...
-
-=== Weather App Complete ===
-```
-
-## Future Enhancements
-
-### Short Term
-- [ ] Add rate limiting per app
-- [ ] Add bandwidth tracking
-- [ ] Add request logging
-- [ ] Add DNS caching
-
-### Long Term
-- [ ] HTTPS/TLS support
-- [ ] Per-domain permissions (read-only, POST-only, etc.)
-- [ ] Request quotas
-- [ ] User-controlled permission prompts
-- [ ] Network activity monitor
-
-## Migration Path
-
-### Existing Apps
-
-Apps using direct HTTP/NetworkStack access should:
-
-1. **Add to manifest**:
-```lua
-permissions = { network = true },
-allowedDomains = { "..." }
-```
-
-2. **Replace HTTP.create_client() with http global**:
-```lua
--- Before
-local HTTP = require("HTTP")
-local client = HTTP.create_client(NetworkStack)
-
--- After
--- Just use http global
-```
-
-3. **Convert to callback style**:
-```lua
--- Before (blocking)
-local response = client.get(url)
-
--- After (async)
-http:get(url, function(response) ... end)
-```
-
-### System-Level Code
-
-System utilities can still use HTTP library directly:
-- Network test apps
-- System tools
-- Administrative utilities
-
-User apps should use sandboxed `http` global.
-
-## Comparison Matrix
-
-| Feature | Direct HTTP | SafeHTTP Manual | Sandboxed HTTP |
-|---------|-------------|-----------------|----------------|
-| Setup | Manual | Manual | Automatic |
-| Domain restriction | ❌ No | ✅ Yes | ✅ Yes |
-| Manifest declaration | ❌ No | ❌ No | ✅ Yes |
-| Security isolation | ❌ No | ⚠️ Manual | ✅ Auto |
-| User visibility | ❌ No | ❌ No | ✅ Yes |
-| Recommended for | System code | N/A | User apps |
-
-## Documentation
-
-- **For App Developers**: Read `SANDBOXED_HTTP.md`
-- **For SafeHTTP Details**: Read `SAFEHTTP.md`
-- **For HTTP Protocol**: Read `HTTP_LIBRARY.md`
-- **For Examples**: See `/apps/com.luajitos.weatherapp/`
-
-## Conclusion
-
-Sandboxed HTTP provides secure, easy-to-use network access for LuajitOS applications:
-
-✅ **Automatic** - No manual setup required
-✅ **Secure** - Domain whitelisting enforced
-✅ **Simple** - Just use `http` global
-✅ **Declarative** - Permissions in manifest
-✅ **Isolated** - Per-app sandboxing
-
-Apps get powerful network capabilities while users maintain security and control.
diff --git a/SECURITY_AUDIT.md b/SECURITY_AUDIT.md
@@ -1,506 +0,0 @@
-# LuajitOS Security Audit
-## SafeFS, SafeGfx, and SafeHTTP Analysis
-
-**Audit Date:** 2025-11-19
-**Auditor:** Claude (Anthropic)
-**Scope:** Application sandboxing security mechanisms
-
----
-
-## Executive Summary
-
-LuajitOS implements three primary sandboxing mechanisms to isolate applications:
-
-1. **SafeFS** - Filesystem access sandboxing
-2. **SafeGfx** - Graphics rendering sandboxing (via LPM - currently removed)
-3. **SafeHTTP** - Network access sandboxing
-
-**Overall Risk Assessment: MEDIUM-HIGH**
-
-While the sandboxing architecture demonstrates security awareness, several critical vulnerabilities and design weaknesses exist that could allow malicious applications to escape isolation, access unauthorized resources, or perform denial-of-service attacks.
-
----
-
-## 1. SafeFS Security Analysis
-
-**Location:** `/os/libs/safefs.lua`
-
-### 1.1 Path Traversal Protection
-
-#### ✅ STRENGTHS:
-- **Path normalization** properly handles `.` and `..` components
-- **Whitelist-based access** requiring explicit allowed roots
-- **Prefix matching** validates normalized paths against allowed roots
-
-#### ❌ VULNERABILITIES:
-
-**CRITICAL - Directory Traversal via Symlink-like Behavior:**
-```lua
--- Line 42-52: Path normalization
-elseif part == ".." then
- -- Go up one level, but only if we have somewhere to go
- if #normalized > 0 then
- table.remove(normalized)
- end
-```
-**Issue:** After normalization, the code checks if the result is within allowed bounds, but it doesn't prevent an attacker from using `..` to escape if the allowed root is set incorrectly.
-
-**Example Attack:**
-```lua
--- If allowedRoots = {"/apps/com.evil.app/*"}
--- Attack: "/apps/com.evil.app/../com.other.app/secret.txt"
--- Normalizes to: "/apps/com.other.app/secret.txt"
--- Validation at line 66-70 WILL REJECT this (GOOD)
-```
-**Status:** ✅ Protected by validation check
-
-**MEDIUM - Wildcard Pattern Bypass:**
-```lua
--- Line 62-64: Wildcard suffix handling
-if root:sub(-2) == "/*" then
- root_prefix = root:sub(1, -3)
-end
-```
-**Issue:** Only handles suffix wildcards `/*`, not prefix or middle wildcards.
-
-**Example Attack:**
-```lua
--- If allowedRoots = {"/tmp/*"}
--- These work correctly (GOOD):
--- "/tmp/test.txt" → allowed
--- "/tmp/subdir/file.txt" → allowed
-
--- But the pattern doesn't support:
--- "*.example.com" style patterns in paths
-```
-**Status:** ✅ Acceptable - filesystem paths don't need prefix wildcards
-
-### 1.2 Race Conditions
-
-#### ❌ TIME-OF-CHECK-TIME-OF-USE (TOCTOU):
-```lua
--- Line 417-438: SafeFS:read()
-function SafeFS:read(path)
- local fullPath, err = self:resolvePath(path)
- -- ... validation happens here ...
-
- -- VULNERABILITY: Gap between validation and actual read
- return CRamdiskRead(fullPath)
-end
-```
-
-**Attack Scenario:**
-1. Malicious app calls `fs:read("/apps/evil/data.txt")`
-2. Path is validated and resolved
-3. **Between validation and read, another process could:**
- - Replace the file contents
- - Create a symbolic link (if supported)
- - Modify permissions
-
-**Impact:** LOW (LuajitOS doesn't currently support concurrent modification, but this is a design flaw for future)
-
-### 1.3 Resource Exhaustion
-
-#### ❌ NO SIZE LIMITS ON FILE OPERATIONS:
-```lua
--- Line 440-485: SafeFS:write()
-function SafeFS:write(path, content)
- -- No check on content size!
- success = CRamdiskWrite(fullPath, content)
-end
-```
-
-**Attack Vector:**
-```lua
--- Malicious app could write infinite data:
-local huge_string = string.rep("A", 10^9) -- 1GB string
-fs:write("/apps/evil/bomb.txt", huge_string)
-```
-
-**Impact:** HIGH - Denial of Service via memory exhaustion
-
-**Recommendation:** Add configurable size limits per-app or per-operation.
-
-### 1.4 Directory Traversal in List Operations
-
-#### ✅ PROTECTED:
-```lua
--- Line 618-642: SafeFS:dirs()
-function SafeFS:dirs(path)
- local fullPath, err = self:resolvePath(path)
- if not fullPath then
- return nil, err -- Validation failure
- end
- -- ... safe to proceed
-end
-```
-
-All directory listing operations (`dirs`, `files`) properly validate paths before accessing.
-
----
-
-## 2. SafeGfx Security Analysis
-
-**Location:** `/os/libs/lpm.lua` (lines 664-763)
-**Status:** Currently removed from LPM, but code still exists
-
-### 2.1 Coordinate Transformation
-
-#### ✅ STRENGTHS:
-```lua
--- Line 677-684: Coordinate transformation
-local function transformX(localX)
- return window.x + contentOffsetX + localX
-end
-```
-Apps use local coordinates (0,0) starting at their content area, which are transformed to screen coordinates. This prevents apps from knowing or accessing absolute screen positions.
-
-### 2.2 Bounds Checking
-
-#### ✅ COMPREHENSIVE PROTECTION:
-```lua
--- Line 687-690: Bounds checking
-local function inBounds(localX, localY)
- return localX >= 0 and localX < contentWidth and
- localY >= 0 and localY < contentHeight
-end
-```
-
-#### ❌ INTEGER OVERFLOW POTENTIAL:
-```lua
--- Line 705-738: fillRect clamping
-function safeGfx:fillRect(localX, localY, width, height, color)
- if localX < 0 then
- width = width + localX -- POTENTIAL OVERFLOW
- localX = 0
- end
-```
-
-**Attack Vector:**
-```lua
--- If localX = -2^31 (negative max int)
--- width = 100
--- Then: width = 100 + (-2^31) = huge negative number wrapped to positive
-gfx:fillRect(-2147483648, 0, 100, 100, 0xFF0000)
-```
-
-**Impact:** MEDIUM - Could bypass bounds checking, crash system, or write to arbitrary memory
-
-**Recommendation:** Validate that width/height remain positive after clamping.
-
-### 2.3 Information Disclosure
-
-#### ❌ WINDOW SIZE DISCLOSURE:
-```lua
--- Line 754-760: Getters expose internal state
-function safeGfx:getWidth()
- return contentWidth
-end
-
-function safeGfx:getHeight()
- return contentHeight
-end
-```
-
-**Issue:** Apps can query window dimensions, which might leak information about:
-- Screen resolution
-- Other application window sizes
-- Desktop layout
-
-**Impact:** LOW - Information disclosure, potential for UI spoofing attacks
-
----
-
-## 3. SafeHTTP Security Analysis
-
-**Location:** `/os/libs/SafeHTTP.lua`
-
-### 3.1 Domain Whitelisting
-
-#### ✅ STRENGTHS:
-- **Mandatory whitelist** - Apps must declare allowed domains in manifest
-- **Wildcard support** - Supports `*.example.com` and `example.*` patterns
-- **Case-insensitive matching** - Prevents case-based bypasses
-
-```lua
--- Line 8-36: Domain matching logic
-local function matchesDomain(domain, pattern)
- domain = domain:lower()
- pattern = pattern:lower()
- -- ... matching logic
-end
-```
-
-#### ❌ URL PARSING VULNERABILITIES:
-
-**CRITICAL - Regex Bypass:**
-```lua
--- Line 39-50: Domain extraction
-local function extractDomain(url)
- local domain = url:gsub("^%w+://", "") -- Remove protocol
- domain = domain:gsub(":%d+", "") -- Remove port
- domain = domain:gsub("/.*$", "") -- Remove path
- return domain:lower()
-end
-```
-
-**Attack Vectors:**
-
-1. **Username/Password in URL:**
-```lua
--- Attack: http://evil.com@allowed.com/
--- Pattern matches: "://", removes to: "evil.com@allowed.com/"
--- Port removal: unchanged
--- Path removal: "evil.com@allowed.com"
--- Result: "evil.com@allowed.com" treated as domain
--- This doesn't match "allowed.com" ✓ (SAFE - will be rejected)
-```
-
-2. **Multiple @ symbols:**
-```lua
--- Attack: http://user:pass@evil.com@allowed.com/
--- After protocol removal: "user:pass@evil.com@allowed.com/"
--- After path removal: "user:pass@evil.com@allowed.com"
--- Domain comparison: Won't match whitelist ✓ (SAFE)
-```
-
-**Status:** ✅ Current implementation is safe, but fragile
-
-3. **URL Encoding Bypass:**
-```lua
--- Attack: http://allowed.com%2f@evil.com/
--- After protocol removal: "allowed.com%2f@evil.com/"
--- After port removal: "allowed.com%2f@evil.com/"
--- After path removal: "allowed.com%2f@evil.com"
--- Domain extracted: "allowed.com%2f@evil.com"
--- Won't match "allowed.com" ✓ (SAFE)
-```
-
-**Recommendation:** Use a proper URL parser instead of regex. Consider validating against RFC 3986.
-
-### 3.2 Request Size Limits
-
-#### ✅ IMPLEMENTED:
-```lua
--- Line 86-87: Size limits
-max_size = options.max_size or 1048576, -- 1MB default
-```
-
-Response size is limited to prevent memory exhaustion attacks.
-
-#### ❌ NO REQUEST SIZE LIMIT:
-```lua
--- POST requests have no body size limit
-function SafeHTTP:post(url, data, success_callback, error_callback)
- -- data can be arbitrarily large!
-end
-```
-
-**Attack Vector:**
-```lua
--- Send huge POST body
-local huge_data = {payload = string.rep("A", 10^9)}
-http:post("http://allowed.com/api", huge_data, ...)
-```
-
-**Impact:** MEDIUM - Memory exhaustion, network abuse
-
-### 3.3 Timeout Handling
-
-#### ✅ IMPLEMENTED:
-```lua
--- Line 86: Default 30-second timeout
-timeout = options.timeout or 30,
-```
-
-Prevents infinite hangs on unresponsive servers.
-
-#### ❌ NO CONCURRENT REQUEST LIMIT:
-```lua
--- Line 91: Active requests tracked but not limited
-active_requests = {},
-```
-
-**Attack Vector:**
-```lua
--- Spawn 10000 concurrent requests
-for i = 1, 10000 do
- http:get("http://allowed.com/slow", function() end)
-end
-```
-
-**Impact:** HIGH - Resource exhaustion, system DoS
-
-**Recommendation:** Limit concurrent requests per app (e.g., max 5).
-
-### 3.4 HTTPS/TLS Support
-
-#### ❌ NOT IMPLEMENTED:
-```lua
--- Line 54-59: Protocol handling
-local function normalizeURL(url)
- if not url:match("^%w+://") then
- url = "http://" .. url -- Defaults to HTTP!
- end
- return url
-end
-```
-
-**Impact:** CRITICAL - All network traffic is plaintext:
-- Credentials sent in clear text
-- Session tokens exposed
-- Man-in-the-middle attacks trivial
-- No certificate validation
-
-**Recommendation:** Implement TLS/SSL or clearly document this limitation and warn users.
-
-### 3.5 DNS Rebinding
-
-#### ❌ NO PROTECTION:
-The domain whitelist is checked once when the request is made, but there's no protection against DNS rebinding attacks:
-
-1. Attacker sets up `evil.allowed.com` (whitelisted)
-2. App makes request to `http://evil.allowed.com/`
-3. Initial DNS lookup returns attacker's server
-4. Attacker's DNS changes to point to `127.0.0.1` or internal IP
-5. Subsequent requests bypass firewall
-
-**Impact:** HIGH - Access to internal network resources
-
-**Recommendation:** Re-validate domain after DNS lookup, or pin IP addresses.
-
----
-
-## 4. Cross-Cutting Concerns
-
-### 4.1 Manifest Security
-
-**Location:** `/os/libs/run.lua` (permission parsing)
-
-#### ❌ NO SIGNATURE VERIFICATION:
-Manifests are Lua code executed without verification. A malicious manifest could:
-```lua
--- Evil manifest.lua
-os.execute("rm -rf /") -- If os.execute available
-_G.evil_code = function() ... end
-return {name = "Innocent App", ...}
-```
-
-**Impact:** CRITICAL if os/io libraries are accessible
-
-**Recommendation:** Parse manifests as data (JSON/YAML), not code.
-
-### 4.2 Sandbox Escape via Globals
-
-#### ❌ GLOBAL NAMESPACE POLLUTION:
-```lua
--- Apps can potentially access:
-_G.sys
-_G.lpm -- (removed now, but pattern still exists)
-_G.run
-_G.cursor_state
-```
-
-**Attack Vector:**
-```lua
--- Malicious app modifies global state
-_G.sys.applications = {} -- Delete all running apps
-_G.cursor_state.x = -1000 -- Crash mouse handling
-```
-
-**Impact:** HIGH - Sandbox escape, system instability
-
-**Recommendation:** Deep-freeze globals or use separate environments per app.
-
-### 4.3 Process Isolation
-
-#### ✅ SEPARATE APPLICATION INSTANCES:
-Each app gets its own Application instance with isolated PID and state.
-
-#### ❌ SHARED MEMORY SPACE:
-All apps run in the same Lua VM - no memory isolation:
-```lua
--- App A can access App B's data through:
-for pid, app in pairs(_G.sys.applications) do
- -- Read other app's stdout, windows, exports
- print(app:getStdout())
-end
-```
-
-**Impact:** CRITICAL - No isolation between apps
-
-**Recommendation:** Run apps in separate Lua VMs or implement memory protection.
-
----
-
-## 5. Vulnerability Summary
-
-| Severity | Count | Examples |
-|----------|-------|----------|
-| CRITICAL | 3 | No HTTPS, Manifest code execution, Shared memory |
-| HIGH | 4 | Resource exhaustion (FS/HTTP), DNS rebinding, Global pollution |
-| MEDIUM | 3 | Integer overflow (GFX), TOCTOU, Request size limits |
-| LOW | 2 | Information disclosure, Pattern limitations |
-
----
-
-## 6. Recommendations by Priority
-
-### Immediate (Critical Risk):
-
-1. **Implement manifest parsing as data**, not Lua code
-2. **Add memory/disk quotas per application**
-3. **Isolate global namespace** - prevent apps from accessing `_G.sys`, etc.
-4. **Add HTTPS/TLS support** or clearly warn users
-
-### Short-term (High Risk):
-
-5. **Limit concurrent HTTP requests** (max 5 per app)
-6. **Implement DNS rebinding protection**
-7. **Add request body size limits** for HTTP POST
-8. **Fix integer overflow in SafeGfx bounds checking**
-
-### Medium-term (Defense in Depth):
-
-9. Use proper RFC 3986 URL parser instead of regex
-10. Add file size limits to SafeFS operations
-11. Implement per-app memory isolation (separate VMs)
-12. Add integrity checking for system libraries
-
-### Long-term (Hardening):
-
-13. Add rate limiting for filesystem/network operations
-14. Implement capability-based security model
-15. Add audit logging for security-sensitive operations
-16. Code signing for applications
-
----
-
-## 7. Positive Security Findings
-
-✅ **Good practices observed:**
-
-1. **Defense in depth** - Multiple sandboxing layers
-2. **Fail-safe defaults** - Whitelist-based access control
-3. **Input validation** - Path normalization, domain checking
-4. **Clear separation of concerns** - SafeFS, SafeGfx, SafeHTTP are distinct
-5. **Timeout handling** - Prevents infinite waits
-6. **Size limits** - HTTP response size limited
-
----
-
-## 8. Conclusion
-
-LuajitOS demonstrates **security-conscious design** with sandboxing mechanisms, but suffers from **implementation gaps** typical of early-stage operating systems:
-
-- **Conceptual model is sound** - separation of concerns, whitelisting
-- **Execution has critical flaws** - shared memory, no TLS, code execution in manifests
-- **Risk appropriate for** educational/hobby OS, **NOT production use**
-
-**Overall Grade: C+ (Security-aware but vulnerable)**
-
-For a production system, address all CRITICAL and HIGH severity issues before deployment.
-
----
-
-**End of Security Audit**
diff --git a/SHADOW_BUFFER_USAGE.md b/SHADOW_BUFFER_USAGE.md
@@ -1,183 +0,0 @@
-# Shadow Buffer Implementation
-
-## Overview
-
-The VESA graphics driver now maintains a **shadow buffer** - a complete copy of the framebuffer in system memory. This enables efficient partial screen redraws by restoring regions from the last frame.
-
-## Implementation Details
-
-### C-Level Changes
-
-**vesa.h:**
-- Added `shadow_buffer` pointer to `vesa_state_t` structure
-- Added `buffer_size` field to track allocation size
-- Declared `lua_vesa_restore_region()` function
-
-**vesa.c:**
-- Allocates shadow buffer during `vesa_init()` (same size as framebuffer)
-- Modified `vesa_draw_pixel()` to write to both framebuffer AND shadow buffer
-- All drawing operations automatically update both buffers
-- Added `lua_vesa_restore_region(x, y, width, height)` to restore screen regions
-
-**luajit_init.c:**
-- Registered `VESARestoreRegion` global function
-
-### Lua-Level API
-
-**init.lua:**
-- Added `gfx_api.vesa_restore_region(x, y, w, h)` wrapper
-
-## Usage
-
-### Basic Pattern
-
-```lua
--- Draw initial frame
-gfx:fillRect(0, 0, 400, 300, 0x000000) -- Black background
-gfx:drawText(10, 10, "Hello", 0xFFFFFF)
-
--- Later, to redraw just part of the screen from last frame:
-gfx:vesa_restore_region(0, 0, 100, 50) -- Restore top-left corner
-```
-
-### Use Cases
-
-#### 1. Clearing Moving Cursor Trail
-```lua
--- Before drawing new cursor position, restore old position
-local old_x, old_y = last_mouse_x, last_mouse_y
-gfx:vesa_restore_region(old_x - 1, old_y - 1, 12, 12)
-
--- Draw cursor at new position
-draw_cursor(new_x, new_y)
-```
-
-#### 2. Optimized Window Updates
-```lua
--- Instead of redrawing entire window, restore background then redraw
-window:onDraw(function(gfx)
- -- Restore this window's region from shadow (clears old content)
- gfx:vesa_restore_region(window.x, window.y, window.width, window.height)
-
- -- Draw fresh window content
- gfx:fillRect(0, 0, window.width, window.height, 0x2C2C2C)
- gfx:drawText(10, 10, "Content", 0xFFFFFF)
-end)
-```
-
-#### 3. Partial Screen Damage Repair
-```lua
--- If only a small area changed, restore just that region
-function update_status_bar(text)
- -- Restore status bar area to last frame
- gfx:vesa_restore_region(0, 750, 1024, 18)
-
- -- Draw new status text
- gfx:drawText(10, 755, text, 0xFFFFFF)
-end
-```
-
-## Performance Considerations
-
-### Memory Usage
-- Shadow buffer is allocated at boot time
-- For 1024x768x32bpp: ~3MB of additional RAM
-- Shadow buffer persists for entire OS session
-
-### Speed
-- `VESARestoreRegion()` uses `memcpy()` for fast block copies
-- Much faster than redrawing complex graphics from scratch
-- Ideal for: cursor trails, temporary overlays, dirty rectangles
-
-### When NOT to Use
-- Don't restore if you need to redraw everything anyway
-- Don't restore before clearing entire screen
-- Don't restore region larger than what you're redrawing
-
-## Security Implications
-
-### Positive
-- Shadow buffer tracks exact screen state from last frame
-- Can be used for dirty rectangle detection
-- Enables efficient window damage tracking
-
-### Risks (from SECURITY_AUDIT.md)
-- Shadow buffer is globally accessible (not per-process)
-- Malicious app could potentially:
- - Read shadow buffer to spy on other windows (information disclosure)
- - Corrupt shadow buffer if direct access is exposed
-
-### Mitigation
-- Shadow buffer is only accessible via `VESARestoreRegion()` (read-only operation)
-- Apps cannot directly read/write shadow buffer memory
-- Restoration is bounds-checked and clamped to screen dimensions
-
-## Example: Optimized Mouse Rendering
-
-```lua
--- Track last cursor position
-local last_cursor_x, last_cursor_y = 0, 0
-
-while true do
- -- Get new mouse position
- local mouse_x = _G.cursor_state.x
- local mouse_y = _G.cursor_state.y
-
- -- Only update if mouse moved
- if mouse_x ~= last_cursor_x or mouse_y ~= last_cursor_y then
- -- Restore old cursor location (removes cursor trail)
- if last_cursor_x > 0 then
- gfx_api.vesa_restore_region(
- last_cursor_x - 1,
- last_cursor_y - 1,
- 12,
- 12
- )
- end
-
- -- Draw cursor at new position
- VESADrawRect(mouse_x, mouse_y, 10, 10, 255, 255, 255)
-
- -- Update tracking
- last_cursor_x = mouse_x
- last_cursor_y = mouse_y
- end
-end
-```
-
-## Future Enhancements
-
-### Dirty Rectangle Tracking
-Could add automatic dirty region detection:
-```lua
-function gfx:markDirty(x, y, w, h)
- -- Track which regions changed
- -- Later: restore only non-dirty regions
-end
-```
-
-### Double Buffering
-Shadow buffer could be used as back buffer:
-```lua
--- Draw to shadow buffer
--- Swap shadow <-> framebuffer atomically
-```
-
-### Compression
-For memory-constrained systems:
-```lua
--- Compress shadow buffer when idle
--- Decompress on restore
-```
-
-## Implementation Notes
-
-1. **All drawing operations update shadow buffer** - This happens automatically in `vesa_draw_pixel()`, so no changes needed in app code.
-
-2. **Shadow buffer initialized to black** - Matches initial framebuffer state.
-
-3. **Bounds checking** - `VESARestoreRegion()` clamps coordinates to screen dimensions, preventing buffer overruns.
-
-4. **No locking** - Currently single-threaded, but future multi-threaded rendering would need synchronization.
-
-5. **No cleanup** - Shadow buffer is never freed (OS doesn't have shutdown), acceptable for embedded/OS use.
diff --git a/build_debug_mouse.sh b/build_debug_mouse.sh
@@ -1,24 +0,0 @@
-#!/bin/bash
-# Build with mouse debug output enabled
-
-echo "====================================="
-echo "Building with MOUSE_DEBUG enabled"
-echo "====================================="
-echo ""
-
-# Temporarily modify build.sh to add -DMOUSE_DEBUG flag
-sed -i.bak 's/\(${CC} ${CFLAGS} ${LUAJIT_INCLUDE} -c mouse.c\)/\1 -DMOUSE_DEBUG/' build.sh
-
-# Run the build
-./build.sh
-
-# Restore original build.sh
-mv build.sh.bak build.sh
-
-echo ""
-echo "====================================="
-echo "Build complete with mouse debug!"
-echo "====================================="
-echo ""
-echo "Run with: ./test_mouse_grab.sh"
-echo "You should see PKT[...] debug output"
