Skip to content

Security Model

Jump to bottom
Nick edited this page Mar 8, 2026 · 2 revisions

Security Model

Dispatch handles authentication and file operations without storing or transmitting passwords, API keys, or secrets in cleartext.

Authentication: OAuth 2.0 Device Authorization Grant

Dispatch uses RFC 8628 — OAuth 2.0 Device Authorization Grant, the same flow used by the GitHub CLI and AWS CLI.

  1. Dispatch requests a short-lived device code from Telex.
  2. The user opens a URL and enters the code — on any device, any browser.
  3. Dispatch polls for the resulting access token.
  4. Once authorized, the token is encrypted and stored locally.

There is no password field, no API key to copy, and no secret in any environment variable.

Token Storage: AES-256-GCM Encryption

OAuth access tokens are encrypted before being written to wp_options:

  1. A random 12-byte initialization vector (IV) is generated for every write.
  2. The token is encrypted with AES-256-GCM using a key derived from wp_salt('auth').
  3. The ciphertext, IV, and authentication tag are base64-encoded and stored with a v2: prefix.
  4. The plaintext token is never written to disk, never logged, and never appears in error output.

The encryption key is derived from your site's own secret salts and never leaves your server.

Download Validation: SHA-256 Checksums

Every build file downloaded from Telex is validated before installation:

  1. The build manifest includes a SHA-256 checksum for each file.
  2. Dispatch downloads the file and recomputes the checksum.
  3. If checksums don't match — even by a single byte — the install is aborted and nothing is written to disk.

Path Traversal Protection

Before extracting any file, every path in the zip is validated:

  • ZipSlip prevention: No path may contain .. or resolve outside the target directory.
  • Extension blocklist: Files with dangerous extensions are blocked before extraction.

If any file fails validation, the entire install is aborted.

Webhook Validation

The auto-deploy endpoint (POST /telex/v1/deploy) is open (no capability check) but protected by:

Protection Detail
HMAC-SHA256 signature Every request must include a valid X-Telex-Signature header.
Replay prevention Requests older than 5 minutes (via X-Telex-Timestamp) are rejected.
Rate limiting Excessive requests from the same IP are throttled.

Capability Checks

Every REST endpoint and admin action checks current_user_can('manage_options') before executing. Unauthenticated or unauthorized requests return 403 immediately.

Audit Log

Every install, update, removal, disconnect, and connection event is recorded in a custom database table with a timestamp, acting user ID, action type, project ID, and IP address. The log is registered with WordPress Privacy Tools for GDPR compliance — export or erase a user's history from Tools → Personal Data.

Reporting Vulnerabilities

Please read SECURITY.md before reporting a security issue. Do not open a public GitHub issue for vulnerabilities.

Clone this wiki locally