LIMONATA MARKETPLACE BACKEND — ISOLATION AND TRUST BOUNDARIES
2026-10-30
===========================================================

Architecture
------------
Customer -> HTTPS account/API gateway -> durable rental/job control plane
         <- outbound provider agent <- an installed service or rental VM.

The public application never opens a customer/provider-supplied endpoint URL.
Provider credentials and local model connectors remain on the provider machine.
Every request belongs to an account and a funded, active rental. Provider jobs
are leased with expiring random credentials and restricted to the key's listings.
Cancellation, rental expiry and provider failure invalidate queued/leased work
and remove undelivered prompts. Confirmed teardown is required before reuse of
the resource; a timeout alone never proves that the previous machine stopped.
Chain reconciliation cannot block a provider's request for pending teardown.

Existing blockchain consensus, encrypted mempool and the user-never-pays-gas
payment model are separate from workload execution. VM/provider processes do
not belong on validators, indexers or machines holding chain/operator keys.

Two different products
----------------------
1. Model API: the provider installs and runs a fixed model service. The agent
   forwards bounded text-only, non-streaming inference to its installed endpoint.
   The renter cannot select a URL, a model outside the listing or host
   credentials. Function schemas/calls/results are data for the renter client;
   they never authorize provider-host commands. An HTTP connector is not a rented VM and is not described as one.
2. User code / compute service: use a separate VM kernel for unknown renters.
   The reference kind: kata profile requests io.containerd.kata.v2 explicitly;
   failed or unavailable Kata never falls back to runc. The current VM driver
   is CPU/server only. A plain Docker profile needs the owner's explicit
   trusted-container declaration and is reserved for trusted workloads.

Kata/container profiles expose bounded HTTP. The separate QEMU profile exposes
SSH inside a full CPU Linux guest through an authenticated outbound WSS relay.
It does not expose arbitrary provider TCP targets or a browser terminal. The
QEMU host must be dedicated and locally qualified; native Windows VM hosting and
GPU passthrough are unsupported. Guest disks and access are temporary.
For Kata/container HTTP profiles, Approved images
must contain their service and Node >=20 at /usr/local/bin/node. A fixed helper
runs INSIDE the rental and accepts request data over stdin; no variable shell
command or host-side fetch is used to reach a tenant service. This transport
allows a gateway-less isolated internal network without exposing host services.

VM and GPU qualification
------------------------
VM isolation protects the host and other renters against a workload. It does
not automatically hide guest RAM, disks or prompts from the host owner. Model
providers necessarily receive the prompts they process. Confidentiality against
the host requires compatible confidential-computing hardware, remote attestation
and a reviewed secret-release policy; ordinary VM isolation does not provide it.

The provider code distinguishes declared isolation from verified isolation.
Heartbeat/runtime metadata and a successful service response are not attestation.
The platform retains isolationVerified:false and hardwareVerified:false.

GPU access in trusted-container profiles uses exact full GPU UUIDs, never all
devices. One installed listing cannot share a UUID with another installed listing
in the same agent. This is configuration enforcement, not a proof against a
malicious host or another independently managed agent. GPU time-slicing alone
does not isolate tenant memory or faults. The current Kata driver refuses GPU
passthrough rather than pretending that Docker's GPU flag creates an isolated VM.

Public execution of unknown GPU workloads still requires an actual dedicated
GPU host qualification: supported hardware/driver matrix, IOMMU and whole-device
passthrough, reset/cleanup between renters, VM isolation, blocked host/metadata
access, bounded resources and failure/reboot tests. No GPU was detached from this
machine and no host daemon, kernel, firewall or validator was reconfigured.

API and persistence controls
----------------------------
Passwords use salted scrypt, with a bounded number of concurrent password hashes.
Browser sessions use HttpOnly/SameSite cookies and Origin/CSRF checks. API secrets
are hashed, shown once and revocable. New keys expire after90days by default
(1..365days configurable). New provider keys bind to selected owned listings;
the browser asks which listings are installed on the particular provider machine.
Omitting listingIds through the API snapshots the current owned listings, never
future listings. Legacy provider keys without a valid expiry or explicit listing binding are
refused on every authenticated route. Replace them from the signed-in account;
a scope error never deletes or recreates the local machine configuration.

Listing-bound keys cannot read account-wide private dashboard/balance aggregates
or access another listing through mixed permissions, job routes or result polls.
Public listing responses use an explicit allowlist and never expose endpoint
credentials, account email, private runtime fields or physical GPU UUIDs.

Request/body/output sizes, body deadlines, concurrent HTTP operations, password
work, synchronous inference waits and per-account/key/IP rates are bounded.
Changing source IP cannot bypass the account/key quotas. Forwarded visitor IPs
are accepted only from the loopback tunnel peer and are syntactically validated.
Canonical service paths are validated before allowlist checks and URL resolution;
traversal, ambiguous/double encoding, encoded separators and redirects are refused.

The current database is a private single-host durable store: serialized bounded
transactions, an exclusive writer lock, fsync/atomic rename and fail-closed corrupt
state. State must be an owned regular file, mode0600; symlink reads are refused.
Disappearance after initialization fails instead of silently recreating accounts
and balances. This is not PostgreSQL, a distributed queue or high availability.
Multi-host operation needs a transactional database and shared admission/rate
limits; do not start multiple independent public instances with private copies.
Backup/restore drills and recovery from a crash-left lock remain operator work.
Password recovery and account-email change use expiring, attempt-limited email
codes and revoke old sessions after completion. They remain disabled until an
operator configures Resend and a verified sender. Signup email verification, MFA
and account deletion/export still need their own implemented and tested workflow.

Runtime operations
------------------
Run provider software on a dedicated compute host. Keep the agent and its cleanup
watchdog supervised independently. An application timeout, SIGKILL or lost API key
must not leave an orphaned tenant able to consume resources indefinitely. Network,
container and state ownership are checked before reuse or cleanup; an unverified
resource is quarantined, not assumed free. Preserve private state and reconcile
existing version1 instances before using the incompatible version2 runtime state.
Never delete old state/locks merely to make the new agent start.

Read provider-guide.txt for the exact profiles, supported transports and cleanup
commands shipped with the current package. Activation of real payments still
requires the separate mainnet/acquisition/settlement inputs in ACTIVATE.txt.

Automatic Linux discovery and account pairing
---------------------------------------------
The setup assistant reads CPU, RAM/cgroup limits, storage and GPU diagnostics on
the provider host. Recommended allocations reserve capacity for the host. MIG
or display-bound GPUs are not automatically offered as exclusive GPU rentals.
Detection is local and read-only; it is not hardware attestation or permission
to start a VM. Model discovery is limited to known loopback services after the
owner's choice. No hostname, MAC, host IP or running-container inventory is part
of the hardware report. Physical GPU UUIDs stay out of browser/public responses.

A machine starts an expiring device connection with its own X25519 public key.
The browser uses a separate short code, requires a signed-in account, CSRF and
verified payout wallet, and approves explicit resources/prices. Allocations cannot
exceed the report's recommendations or reuse a GPU within the selected offers.
Approval atomically creates offline/unverified listings and a90day provider key
bound to those exact listings. The API secret is encrypted using X25519, HKDF
and AES-GCM for the machine; neither the browser nor application state receives
its plaintext. The terminal confirms the account/payout identity before saving
credentials; declining can revoke only that connection's key and pause its ads.

An interrupted ten-minute connection resumes using a private local mode0600
file containing the device token and private key. It is removed after a successful
commit. The durable encrypted reply is safe to poll again; reconnecting does not
duplicate listings or credentials. Completed configuration can be finished later
with --configure without another enrollment. Unprepared services stay pending
and do not report available rental capacity.

The Linux bootstrap verifies an immutable release SHA256 before extraction and
uses a pinned official Node runtime when needed. It writes only a private user
installation, refuses altered existing releases and does not silently install
Docker, GPU drivers, Kata or firewall rules. Optional user-service installation
requires an explicit choice. The foreground runner keeps independent cleanup
alive until the agent's workload state confirms teardown, including Ctrl+C.

Windows provider boundary
--------------------------
Release1.3.0 adds native Windows account/hardware connection and already installed
model APIs. The Windows ZIP contains a double-click launcher for the matching
versioned PowerShell installer. Official Node x64/ARM64 ZIP and executable hashes
are pinned; release integrity is checked before extraction/execution. Archive
traversal, alternate streams, links, filename collisions and excessive expansion
are rejected. The installer does not need administrator elevation, disable Defender,
change machine execution policy, enable WSL/Hyper-V or detach a graphics device.

Private files use Windows security descriptors, not POSIX mode bits. The current
SID owns protected DACLs restricted to that SID, SYSTEM and Administrators. Creation
protects directories atomically and protects empty files before secret writes.
Reparse points, hardlinks, non-NTFS/ReFS storage and destructively writable path
ancestors are refused. TrustedInstaller is recognized only for trusted OS ancestors.
Fixed PowerShell programs receive paths as data; executable paths are absolute.
An IPC stop request permits graceful model-agent shutdown on native Windows.
Release1.3.1 aligns the launcher with the installer parent policy: LOCALAPPDATA
may be owned by the current user, SYSTEM or Administrators. The private Limonata
directories must still be owned by the current user with protected DACLs, and
untrusted writes or reparse points remain refused. Empty/null parent and ancestor
ACL rule collections are rejected. No parent permissions change.
Release1.3.2 uses Node's direct --version output for runtime compatibility,
avoiding inline JavaScript quotes lost by Windows PowerShell5.1's native argument
serialization. Nonzero exits, malformed/multiline versions and unsupported Node
majors are refused. Installer failures emit a clear diagnostic and nonzero exit.
Release1.3.3 adds bounded NVIDIA DriverStore discovery using validated package
basenames under the fixed Windows DriverStore root; arbitrary returned paths,
PATH/current-directory binaries and reparse directories are not used. NVIDIA
probes share a15-second deadline. Observed-only adapters carry vendor/model/reason
through a bounded allowlist into the browser; no fallback UUID/VRAM are invented
and they cannot create GPU capacity or bypass exclusive-allocation checks.
Release1.3.4 adds a read-only scoped provider-connection check before local setup
reuse. Only an authenticated removed status or an explicit revoked/expired-key
401 permits the wizard to offer private archival and fresh pairing. Transient,
scope and malformed-response failures preserve files. Archival holds the setup
and runtime locks, rejects live/uncertain state, linked credential parents and
managed Linux autostart units, preserves external credentials, and rolls back
partial renames. The runtime reservation is released before new service startup.

Release1.3.5 hardens failed cleanup and local Linux path checks. One failed or
quarantined workload no longer prevents attempts to stop other expired rentals;
unconfirmed entries remain reserved and the watchdog withholds a healthy report.
Private Linux paths and the installer refuse intermediate symlinks and unsafe
shared writable ancestors; root/current-owned sticky temporary roots are allowed.
These checks do not protect a process from other programs running as its user.

Native Windows CPU/GPU VM profiles are refused. Docker Desktop/WSL presence and
detected NVIDIA hardware do not establish a qualified rental VM. Windows automatic
startup tasks are not installed by this release; its prepared model agent runs
in the foreground. Software/PowerShell fixtures and UI/API tests were run on Linux;
a physical Windows installation, real NTFS DACL enforcement and device behavior
still need an actual Windows acceptance run. No real Windows or GPU VM was launched.

Deployment and remaining trust limits
--------------------------------------
A provider agent is privileged relative to its workloads: access to a rootful
Docker socket is effectively host administration. Run it on a dedicated compute
host/account without personal files, wallet seeds, production keys or unrelated
services. The public gateway, settlement signers and blockchain validators need
separate service identities and deployment boundaries. Same-user private-file
permissions do not separate a compromised application from that user's keys.

The existing model connector forwards to an owner-installed service; it does not
sandbox that service. Disable tools, shell execution, arbitrary URL fetching and
host-file access in the model application unless isolated separately. The gateway
accepts bounded text requests and cannot make an unsafe model server safe.

Provider-reported health, hardware, model identity and teardown are not remote
proofs. A malicious host can inspect data, fabricate outputs or lie about service
readiness. Current billing uses server-observed rental time within the buyer's
signed maximum, not the provider's reported token count. It does not prove the
quality of an answer. Public launch requires provider qualification, independent
service checks and a clear dispute/refund process. Keep production rentals closed
until those checks and real VM/GPU/reboot acceptance have been completed.

Release hashes protect against changed archive bytes relative to the downloaded
installer. The installer and hashes share the site's HTTPS trust root: they do
not protect against a compromised release origin. Independently signed releases,
protected release credentials and signing verification are remaining release work.
The encrypted mempool and gas sponsorship do not encrypt workload data from hosts.

Primary implementation references
---------------------------------
Docker alternative runtimes (Kata shim):
https://docs.docker.com/engine/daemon/alternative-runtimes/
Docker isolated gateway networking:
https://docs.docker.com/engine/network/port-publishing/#gateway-modes
Kata NVIDIA passthrough reference (not a Limonata hardware qualification):
https://github.com/kata-containers/kata-containers/blob/main/docs/use-cases/NVIDIA-GPU-passthrough-and-Kata-QEMU.md
NVIDIA Kata support/Technology Preview restrictions:
https://docs.nvidia.com/datacenter/cloud-native/gpu-operator/latest/gpu-operator-kata.html
NVIDIA GPU time-slicing isolation limits:
https://docs.nvidia.com/datacenter/cloud-native/gpu-operator/latest/gpu-sharing.html
