Skip to content
PAM

The desktop mental model

PAM Desktop becomes simple when every layer has one job. PHP owns application decisions. Servo owns the document. Rust owns native authority. PAM keeps the PHP worker alive and bounded.

Four responsibilities

Section titled “Four responsibilities”

Your PHP application

Domain rules, commands, DTOs, repositories, events, policies, and product composition.

The Servo document

Trusted local HTML, CSS, JavaScript, rendering, input, and calls through the frozen window.pam bridge.

The Rust host

Windows, protocol validation, capabilities, operating-system handles, plugins, lifecycle, and failure containment.

The PAM worker

Persistent PHP execution, deadlines, cancellation, crash recovery, hot reload, and supervised concurrency.

One command, end to end

Section titled “One command, end to end”
  1. JavaScript calls window.pam.invoke('documents.save', payload).
  2. The local gateway authenticates origin, token, protocol version, size, and deadline.
  3. The Rust host sends a bounded request to the supervised PHP worker.
  4. PAM hydrates typed payload parameters and resolves application services.
  5. Your command executes and records window effects or client events.
  6. PAM normalizes the return value into the versioned response contract.
  7. Rust applies validated native effects and sends the payload to the source window.

If the handler throws, partial effects are not published. If a deadline or cancellation compromises the worker, the host terminates it and prepares a fresh worker; it does not replay the interrupted command.

Authority is declared, never discovered

Section titled “Authority is declared, never discovered”

Application classes and attributes may describe commands and windows, but code discovery cannot grant native authority. Filesystem roots, databases, remote origins, processes, secrets, dialogs, clipboard, notifications, and portals must appear in the capability manifest before the host starts.

protected function configure(Desktop $desktop): void
{
    $desktop->permissions(static fn (Permissions $permissions) => $permissions
        ->filesystem('documents', __DIR__.'/../storage', read: true, write: true)
        ->database('app', 'storage/app.sqlite')
        ->http('api', 'https://api.example.com/v1')
    );
}

JavaScript refers to documents, app, and api; it never receives ambient machine access merely because a PHP library can express an operation.

Where state belongs

Section titled “Where state belongs”
State Natural owner
Domain and persistence state PHP services, repositories, SQLite
Ephemeral interface state Frontend JavaScript
Window, tray, menu, and shortcut state Rust host, changed through typed effects
Invocation-specific window/event context Scoped PAM services
Long-running independent work Supervised jobs or isolated plugins

Failure is part of the architecture

Section titled “Failure is part of the architecture”
  • malformed or oversized bridge messages are rejected at the gateway;
  • missing capabilities fail visibly instead of silently widening access;
  • PHP command deadlines and cancellation remain bounded;
  • native plugins run in supervised processes rather than inside Servo;
  • signed updates verify key, size, digest, and feed before atomic install; and
  • compatibility snapshots protect the public PHP API and protocol shapes.

For the detailed threat boundary, continue with the security model.