nativeapps

README

Floe Native Apps

Prepare a private native graphical stack for Linux applications. Applications continue running directly on the host. The library downloads pinned original archives, verifies every byte, extracts into a private staging directory, and activates only after an isolated Xpra session proves GIO application launch, window discovery, decoded pixels, and input delivery.

The host product owns consent, authorization, application metadata and launch, UI, and window lifecycle. This library owns only component preparation.

Use

pkg, err := nativeapps.NativePackage()
// Handle unsupported platforms before offering preparation.
manager, err := nativeapps.New(absolutePrivateStateRoot, pkg, nil)
defer manager.Close()
status, err := manager.Start(authenticatedOwner, requestID, "download", 0)

Watch notifications are coalesced invalidations: read Snapshot after subscribing and after each notification. A disconnected observer does not cancel preparation. Retain the same request ID when response delivery is uncertain. Cancellation requires the original authenticated owner. A restart reports interrupted work; it never silently restarts a download or executes partial files.

After ready, resolve Directory and ResolveTools. Use the complete managed toolset and Tools.Environment for support processes. Before launching a user application, restore the saved FLOE_NATIVE_APPLICATION_ENV map onto its launch context and remove both FLOE_NATIVE_APPLICATION_ENV and FLOE_NATIVE_ROOT. Keep the session's display and D-Bus addresses. Never export the private loader path to the host program.

Components and portability

The checked-in catalog pins Alpine 3.23 Xpra 6.2.2 packages and Xpra HTML5 v20 source. Each architecture carries its own musl loader and library closure; it does not use the host's glibc or musl installation. Supported architectures are Linux amd64 and arm64. macOS capture and permissions belong to the consuming product's native macOS integration.

No root password, package manager, desktop environment, physical monitor, container, or virtual machine is required in production. A writable executable state filesystem, a compatible Linux kernel, ordinary process/Unix socket permissions, and network access to the pinned publishers are required. Host security policy remains authoritative; failure never enables a privileged fallback. Individual applications still require their own host dependencies and X11 support. Native Wayland-only applications and GPU/DRM capture are outside this package's contract.

Xvfb embeds its xkbcomp directory. Installation verifies the reviewed binary shape and replaces the single /usr/bin directory literal with . while its private wrapper selects the package's tool directory. XKB data, D-Bus config, fonts, Python and image loaders also use private paths. No host paths are linked or changed. The graphical self-check exercises this relocation after installation.

Offline preparation

go run ./cmd/floe-native-apps -arch arm64 -state /absolute/private/cache -bundle /absolute/native-arm64.zip

The ZIP contains original pinned publisher archives. Use its actual byte length with Start(owner, requestID, "upload", size), then WriteChunk with ordered 256 KiB maximum chunks and CompleteUpload. Replayed identical chunks are idempotent. The receiving host independently verifies every archive and performs the same native self-check. Never accept client-supplied executable paths, URLs, catalogs, hashes, or package identities.

Qualification and licenses

go test -race ./... and go vet ./... cover extraction boundaries, integrity, owner/idempotency rules, interruption, cancellation, persistence failures, and atomic activation. floe-native-apps -state ... performs actual installation; floe-native-apps -check ... repeats the native picture/input qualification in an installed directory. Disposable containers may test clean distributions; they are never part of the production implementation.

This library is MIT-licensed. Catalog entries record original licenses and source locations. Downloaded components retain their original licenses. This repository publishes the installer and catalog, not a combined third-party binary distribution. Redistributing an offline ZIP or installed stack creates separate obligations under the components' licenses, including applicable source availability obligations. Original license files are retained during extraction.

The v0.1.1 qualification exercised Ubuntu 22.04 arm64 and Debian 11 amd64 hosts, and clean Debian 13 and Alpine 3.23 fixtures on both architectures. The same amd64 stack passed Arch Linux, Rocky Linux 9, AlmaLinux 9 and RHEL UBI 9 fixtures. This evidence covers component rendering/input; it does not promise that every third-party application works on every distribution.

Documentation

Overview

Package nativeapps prepares a private native graphical stack without changing system packages. Callers own user consent, authorization, and application launch.

Index

• Variables
• func SelfTest(parent context.Context, root string) (result error)
• func WriteBundle(ctx context.Context, pkg Package, cacheRoot string, output io.Writer, ...) error
• type Artifact
• type Manager
  • func New(root string, pkg Package, validate func(context.Context, string) error) (*Manager, error)
  • func (m *Manager) Cancel(owner, id string) (Status, error)
  • func (m *Manager) Close()
  • func (m *Manager) CompleteUpload(owner, id string) (Status, error)
  • func (m *Manager) Directory() (string, error)
  • func (m *Manager) Package() Package
  • func (m *Manager) Snapshot(owner string) Status
  • func (m *Manager) Start(owner, requestID, source string, uploadSize int64) (Status, error)
  • func (m *Manager) Watch() (<-chan struct{}, func())
  • func (m *Manager) WriteChunk(owner, id string, offset int64, data []byte) (Status, error)
• type Package
  • func ForPlatform(platform, architecture string) (Package, error)
  • func NativePackage() (Package, error)
  • func (p Package) Digest() string
  • func (p Package) Validate() error
• type Status
  • func (s Status) Active() bool
• type Tools
  • func ResolveTools(root string) (Tools, error)
  • func (t Tools) Environment(base []string) []string

Variables

var ErrBusy = errors.New("native preparation is already running")

var ErrForbidden = errors.New("native preparation belongs to another caller")

var ErrInvalid = errors.New("invalid native preparation request")

var ErrUnsupported = errors.New("native graphical components are unavailable for this platform")

Functions

func SelfTest

func SelfTest(parent context.Context, root string) (result error)

SelfTest creates only its own virtual display and transient GTK fixture. A successful check proves actual window discovery, rendered pixels, and input; importing a module or starting a process alone is not readiness evidence.

func WriteBundle

func WriteBundle(ctx context.Context, pkg Package, cacheRoot string, output io.Writer, progress func(int64)) error

WriteBundle acquires the exact catalog archives for an offline host. It neither extracts nor executes them; the destination host verifies every original byte. Callers must publish the output only after this function returns successfully.

Types

type Artifact

type Artifact struct {
	Name    string `json:"name"`
	URL     string `json:"url"`
	SHA256  string `json:"sha256"`
	Size    int64  `json:"size_bytes"`
	Format  string `json:"format"`
	License string `json:"license"`
	Source  string `json:"source"`
}

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

func New

func New(root string, pkg Package, validate func(context.Context, string) error) (*Manager, error)

New requires a private state root. Creating a manager never downloads or starts native processes. The optional validator is useful for host-owned qualification; production callers use the built-in graphical self-check by passing nil.

func (*Manager) Cancel

func (m *Manager) Cancel(owner, id string) (Status, error)

func (*Manager) Close

func (m *Manager) Close()

func (*Manager) CompleteUpload

func (m *Manager) CompleteUpload(owner, id string) (Status, error)

func (*Manager) Directory

func (m *Manager) Directory() (string, error)

func (*Manager) Package

func (m *Manager) Package() Package

func (*Manager) Snapshot

func (m *Manager) Snapshot(owner string) Status

func (*Manager) Start

func (m *Manager) Start(owner, requestID, source string, uploadSize int64) (Status, error)

func (*Manager) Watch

func (m *Manager) Watch() (<-chan struct{}, func())

func (*Manager) WriteChunk

func (m *Manager) WriteChunk(owner, id string, offset int64, data []byte) (Status, error)

type Package

type Package struct {
	ID             string     `json:"id"`
	Architecture   string     `json:"architecture"`
	SizeBytes      int64      `json:"size_bytes"`
	InstalledBytes int64      `json:"installed_bytes"`
	Artifacts      []Artifact `json:"artifacts"`
}

func ForPlatform

func ForPlatform(platform, architecture string) (Package, error)

func NativePackage

func NativePackage() (Package, error)

func (Package) Digest

func (p Package) Digest() string

func (Package) Validate

func (p Package) Validate() error

type Status

type Status struct {
	State         string `json:"state"`
	OperationID   string `json:"operation_id,omitempty"`
	ReceivedBytes int64  `json:"received_bytes"`
	ExpectedBytes int64  `json:"expected_bytes"`
	ErrorCode     string `json:"error_code,omitempty"`
	CanCancel     bool   `json:"can_cancel"`
}

func (Status) Active

func (s Status) Active() bool

type Tools

type Tools struct{ Root, Xpra, Python, Xvfb, Xauth, DBus, HTML string }

func ResolveTools

func ResolveTools(root string) (Tools, error)

func (Tools) Environment

func (t Tools) Environment(base []string) []string

Environment scopes support-tool overrides. The GIO launcher must restore this small saved map on its AppLaunchContext before starting the user's program. Display and D-Bus addresses are deliberately not restored: those belong to the caller's private graphical session.