Orbit Desktop Offline WAL Outbox, AES-256-GCM Payload Encryption & Replay Resilience

1. Disaster Recovery & Zero-Data-Loss Architecture

Point-of-sale workstations and field kiosks operate under unpredictable network conditions:

• Metropolitan Fiber Cuts: Extended physical ISP outages lasting several hours.
• Local Wi-Fi Channel Saturation: High client density during peak rush hours causing transient packet drops.
• Counter Power Interruption: Abrupt power disconnection while local transactions are being committed to disk.

To maintain operations under these conditions, Orbit Desktop employs an encrypted local outbox pattern implemented in apps/desktop/crates/orbit-desktop-core/src/storage/encrypted_outbox.rs:

[Retail / Clinical / School Transaction]
                   |
                   v
    [AES-256-GCM Cryptographic Seal]
     - Machine-Derived Key (Hardware Hash + Salt)
     - Fresh 12-Byte Random Nonce per Entry
                   |
                   v
   [Local Embedded Transactional Outbox (WAL Mode)]
     - Immediate Disk Flush (< 5 ms)
     - Thermal Receipt Printed / Action Confirmed
                   |
       (Network Restored Event)
                   |
                   v
     [Transactional Outbox Replay Worker]
     - Deterministic Chronological Batch Drain
     - Server Idempotency Key De-duplication
     - Automatic 409 Conflict Quarantine

2. Interactive Offline Outbox Console

Store supervisors and systems engineers monitor pending queue depth, cryptographic integrity, and synchronization progress through the desktop outbox monitor:

3. Machine-Bound Key Derivation & AES-256-GCM Encryption

To prevent an adversary from reading the embedded database file by extracting the physical hard drive or copying orbit_offline.db to an unauthorized computer, the encryption key is bound to the local hardware.

3.1 Hardware-Derived Encryption Key

The storage key is computed dynamically at runtime using derive_storage_key() in encrypted_outbox.rs:

fn derive_storage_key() -> [u8; 32] {
    let fp = generate_hardware_fingerprint();
    let mut hasher = Sha256::new();
    hasher.update(b"ORBIT_OFFLINE_STORAGE_KEY_DERIVATION_V2_2026");
    hasher.update(fp.as_bytes());
    let result = hasher.finalize();
    let mut key = [0u8; 32];
    key.copy_from_slice(&result);
    key
}

Because the hardware fingerprint aggregates the machine GUID, CPU architecture, core topology, and static salt, the resulting 256-bit encryption key cannot decrypt the database file on any other physical workstation.

3.2 Authenticated Encryption with Nonce-Prepended Storage

When enqueue() is called, the outbox engine generates a fresh 12-byte random cryptographic nonce using the operating system entropy source (OsRng). This guarantees that even identical transactions produce distinct ciphertexts:

let key = derive_storage_key();
let cipher = Aes256Gcm::new_from_slice(&key).map_err(|e| e.to_string())?;
let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
let ciphertext = cipher
    .encrypt(&nonce, payload_json.as_bytes())
    .map_err(|e| e.to_string())?;

// Prepend 12-byte random nonce to ciphertext for per-entry nonce uniqueness
let mut encrypted = Vec::with_capacity(12 + ciphertext.len());
encrypted.extend_from_slice(&nonce);
encrypted.extend_from_slice(&ciphertext);

The 12-byte nonce is prepended directly to the ciphertext blob in the embedded database. When reading the record during replay, dequeue_unsynced() extracts the first 12 bytes as the nonce and passes the remaining bytes to Aes256Gcm::decrypt().

4. Embedded WAL Mode & Concurrency Architecture

Point-of-sale checkout counters require sub-millisecond database commit latency. Writing synchronously to a standard disk file can cause lockups if multiple threads write simultaneously.

Orbit Desktop configures high-concurrency PRAGMAs during database initialization:

PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA busy_timeout = 5000;

4.1 Parameter Mechanics

• PRAGMA journal_mode = WAL: Enables Write-Ahead Logging. Readers never block writers, and writers never block readers. Transactions append sequentially to orbit_offline.db-wal without locking the main database file.
• PRAGMA synchronous = NORMAL: Eliminates redundant disk sync operations on modern file systems while preserving data safety across power cuts.
• PRAGMA busy_timeout = 5000: Ensures that if another process or thread briefly accesses the outbox, concurrent write calls wait up to 5,000 milliseconds rather than failing with an immediate SQL busy error.

4.2 Table Schema & Index Design

The relational schema provides chronological FIFO queuing:

CREATE TABLE IF NOT EXISTS offline_outbox (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    tenant_id TEXT NOT NULL,
    action TEXT NOT NULL,
    encrypted_payload BLOB NOT NULL,
    created_at INTEGER NOT NULL,
    synced INTEGER NOT NULL DEFAULT 0
);
CREATE INDEX IF NOT EXISTS idx_outbox_synced ON offline_outbox(synced, created_at);

The composite index on (synced, created_at) allows the replay daemon to fetch unsynced records in chronological order with zero table-scan overhead.

5. Network Recovery & Conflict Quarantine Replay Pipeline

When connectivity to the central application server is restored, the desktop runtime initiates the automated outbox drainage pipeline:

5.1 Idempotency & Conflict Quarantine Protocol

1. Deterministic Idempotency Key Injection: Every offline transaction enqueued includes a unique client-generated UUID idempotency key. When the server processes the replayed transaction, it validates that the key has not been previously committed.
2. HTTP 409 Conflict Quarantine: If an item in the offline outbox conflicts with server state (such as an item sold out concurrently online while the physical register was offline), the server returns an HTTP 409 Conflict.
3. Quarantine Isolation: The outbox worker flags the conflicting entry as quarantined (synced = -1), logs an audit notice, and proceeds to drain remaining transactions. This prevents a single failed line item from blocking the entire checkout queue.

6. Outbox Throughput & Cryptographic Latency Benchmarks

The embedded outbox delivers fast write throughput during offline operation:

7. Failure Modes & Recovery SOP

The following operational contingency protocols resolve offline storage exceptions:

8. Cross-Vertical Internal Linkages

The encrypted offline outbox secures offline transaction capture across all Orbit modules:

• Split-Tender Cashiering & Offline Resilience — Relies on the encrypted outbox for multi-tender checkout resilience during network dropouts.
• Offline Mode & Local Queue in Hospitality — Powers offline table order queues and kitchen order ticket persistence.
• Tamper-Proof QR Verification & Balance Gates — Stores offline patient diagnostic collection events securely.
• RFID Turnstile Gate Kiosk & Tardiness Escalation — Buffers thousands of morning gate RFID taps during perimeter network failures.
• Enterprise SQL Kernel Row-Level Security — Synchronizes replayed transactions with server-side tenant isolation boundaries.