Skip to content

Security model

Restura’s security posture is asymmetric between platforms by virtue of capability gaps. The UI surfaces “Desktop only” badges on fields whose underlying capability isn’t available in the browser. Here’s the model.

  • Encryption keys are persisted via Electron’s safeStorage, which wraps them with the OS keychain — macOS Keychain, Windows Credential Manager, Linux libsecret.
  • Stored data (collections, history, environments, secrets) is encrypted with AES-256-GCM using a key derived from the keychain-wrapped key.
  • With no keychain the key falls back to a 0o600 plaintext file (with a startup warning); it is re-sealed — same key, no reset — once a keychain is available. A sealed key with the keychain unavailable fails closed: the store stays unopened that session rather than being reset. Linux basic_text storage is reported as plaintext.
  • Secret-bearing auth fields use the SecretRef handle pattern (ADR 0007): the plaintext lives in electron/main/security/secret-handle-store.ts and the renderer only ever sees a handle ({ kind: 'handle', id, label? }). Plaintext is resolved only at wire-signing time in the main process — never enters the Zustand store, persistence layer, or exported collections.
  • Persisted state uses plaintext IndexedDB by default and is protected only by the browser’s same-origin policy.
  • Future: an opt-in passphrase prompt can derive an encryption key via PBKDF2; that UI has not shipped and is not advertised as an available capability.
  • mTLS, custom CA, SOCKS, and “Verify SSL = off” are not available — the browser sandbox doesn’t expose them.

SSRF guards on both Worker and Electron paths

Section titled “SSRF guards on both Worker and Electron paths”

Every outbound URL passes through shared/protocol/url-validation.ts, which blocks:

  • RFC 1918 (private networks).
  • RFC 6598 (CGNAT, 100.64.0.0/10).
  • Link-local 169.254/16 — covers the cloud-metadata endpoint.
  • Loopback and IPv6 loopback.
  • IPv6 unique-local (fc00::/7).
  • IPv4-mapped IPv6, and every other embedded-IPv4 form (SIIT ::ffff:0:0/96, 6to4, NAT64): the embedded address is re-checked as IPv4.
  • Special-use IPv4: 192.0.0.0/24 (IETF protocol assignments), 198.18.0.0/15 (benchmarking — also the “fake-IP” pool of Clash/sing-box style resolvers), multicast 224.0.0.0/4, and reserved 240.0.0.0/4 including the 255.255.255.255 broadcast address. TEST-NETs are deliberately not blocked.
  • IPv6 tunnels and multicast: Teredo 2001::/32, local-use NAT64 64:ff9b:1::/48, multicast ff00::/8.

Non-special schemes (kafka:, mqtt:, …) get an opaque host from the URL parser, so the guard percent-decodes it and applies NFKC plus the IDN full-stop mappings before checking — kafka://%31%32%37.0.0.1 and full-width digits are caught like 127.0.0.1. Malformed percent-encoding is refused.

OAuth2 token requests (Get Token, device code, auto-refresh) go through the app’s own HTTP transport — the Worker’s /api/proxy on web and self-host, IPC on desktop — not a renderer fetch, so the same SSRF policy applies to the identity provider and redirects are not followed.

The guard is the single source of truth — before the shared-protocol refactor it had drifted between backends.

DNS-rebind guard (desktop and self-host WebSocket relay)

Section titled “DNS-rebind guard (desktop and self-host WebSocket relay)”

The self-hosted Node server’s WebSocket relay resolves and validates the upstream, then dials the validated IP (Host and SNI keep the original name), so there is no rebind window between check and connect.

The Electron main process resolves hostnames and calls assertResolvedAddressAllowed on every record before connecting. HTTP, gRPC (including reflection), WebSocket, SSE, Socket.IO, MCP, and MQTT then pin the dial to the address that was checked (createPinnedLookup, createPolicyPinnedFetch, or resolveGrpcDialAddress). Kafka bootstrap brokers stop at the pre-flight check (electron/main/handlers/kafka/connect-preflight.ts), so a TTL=0 swap between resolve and connect is not mitigated for them. electron/main/security/dns-guard.ts by itself is pre-flight only.

AWS SigV4, OAuth 1.0a, and WSSE are all signed in the Worker / Electron main process, not the renderer. The signature matches the exact bytes the upstream receives — proxying through a layer that re-encodes the body would silently invalidate it.

shared/protocol/header-policy.ts strips hop-by-hop headers (Connection, Keep-Alive, Proxy-Authenticate, Transfer-Encoding, TE, Trailers, Upgrade) from both directions and rejects header names with control characters.

The desktop app decodes compressed responses itself, so it caps the work a hostile server can cause. It decodes at most 3 stacked Content-Encodings (more are left raw, with a notice above the body). It refuses zstd frames that need a window over 8 MB (RFC 9659). And it checks the 10 MB response limit after every decode stage, so a middle layer can’t inflate past it. HEAD, 204 and 304 responses and empty bodies are never decoded. On the web, the runtime’s fetch decodes responses.

Desktop gRPC calls have the same 10 MB limit, per message. It is checked before a message is buffered and again after gzip or brotli decompression, so a small compressed message can’t expand past it. A message over the limit ends the call with RESOURCE_EXHAUSTED.

Any RFC 9110 method token is allowed, but CONNECT, TRACE and TRACK are refused in any casing, on every platform. CONNECT would turn the proxy into a raw tunnel, and TRACE (and IIS’s TRACK) echo your request headers, credentials included, back in the response. Imports never fail on a bad method: a denied or invalid one becomes GET, with a warning.

Generated code treats the method as untrusted, because valid method tokens can contain shell characters such as `, |, & and $. cURL snippets quote any method that isn’t plain letters and digits, and PHP and Ruby snippets use single-quoted strings. A shared collection can’t hide a command in a “Copy as cURL” snippet.

Upstream cookies stay off the Restura origin

Section titled “Upstream cookies stay off the Restura origin”

On the web and self-hosted server, streaming responses (SSE, NDJSON) are passed through the proxy almost as-is. The exception is Set-Cookie: as a real header it would make your browser store the upstream’s cookies for the Restura site itself. The proxy strips it and sends the cookies in an x-restura-set-cookies header instead, which the app reads into its own cookie jar. If the upstream sends its own x-restura-set-cookies header, the proxy drops it, so a server can’t forge entries into your jar.

The network console lists each response cookie’s name and attributes, but replaces the value with [REDACTED]. Cookie values are credentials.

Digest is answered in the shared HTTP core, so web, self-hosted, desktop and the CLI follow the same rules (ADR 0029):

  • The first request carries no credentials. Restura only answers a 401 that carries a Digest challenge.
  • The challenge is answered only if every hop of the redirect chain stayed on the original origin. If any hop left it, the 401 is returned unanswered.
  • There is exactly one retry, and it shares the request’s redirect budget.
  • The password is resolved where the request is sent: in the desktop main process for keychain-stored secrets. The hosted proxy refuses keychain handles. Only a hash goes on the wire.
  • The desktop app no longer re-sends credentials for 300, 304, 305 or 306 responses. Like the web, it returns them as-is.

Residual risk: over plain http:, an attacker on the network can strip a SHA-256 challenge and force MD5, and can see the exchange anyway. Use https: for Digest-protected APIs.

NTLM authenticates a connection, so the desktop app runs the whole handshake on one connection inside the Electron main process (ADR 0036). Web and self-hosted don’t send it, and the CLI refuses it.

  • The first request carries only a negotiate message, with no credentials. After the server’s challenge, only an HMAC proof is sent, never the password.
  • The handshake is pinned to one HTTP/1.1 connection. A second connection is refused before any bytes are written, so the authenticate message can’t move to another socket. If the server closes the connection after the challenge, the request fails.
  • Credentials go only to the origin you requested, never to a redirect target on another origin.

Through an HTTP proxy, NTLM always uses a CONNECT tunnel, even for http: targets, so a pooling proxy can’t move the handshake to another upstream connection.

Residual risk: no MIC or channel binding (Extended Protection). Over plain http:, or with certificate verification off, an attacker on the network can capture the NTLMv2 response (crackable offline) or relay it. Use https: with verification on.

The Electron renderer is sandboxed (sandbox: true, contextIsolation: true, nodeIntegration: false) and pinned down by these policies:

  • Trusted IPC sender — every IPC handler accepts only the main frame of the pinned packaged entry (file://…/web/index.html). The Vite dev origin (http://localhost:5173) is trusted only for an unpackaged dev run; a packaged build rejects it.
  • Default-deny web permissions — setPermissionRequestHandler/setPermissionCheckHandler on the default session reject every web-platform permission except clipboard-sanitized-write (copy buttons). Everything privileged goes through the validated IPC surface instead. Growing the allowlist is an explicit, test-guarded change (ADR 0026).
  • CSP — production loads enforce default-src 'self' file: with object-src 'none', worker-src 'self' file:, wasm-unsafe-eval only (QuickJS), and no unsafe-eval. The policy exists twice — a response header in electron/main/main.ts and a <meta> fallback injected at build time in vite.config.mts — and a structural test (electron/main/__tests__/security-hardening.test.ts) fails if the two ever diverge.

Pre-request and test scripts run in a QuickJS WASM sandbox (shared/scripts/script-executor.ts):

  • No DOM.
  • No filesystem.
  • No network escape — fetch and XMLHttpRequest are absent.
  • Memory cap (64 MB per script runtime).
  • Execution time cap (5 seconds for synchronous scripts; 30 seconds when a host bridge such as rs.sendRequest is in use).

This matters because shared collections might carry scripts from anywhere; the sandbox guarantees they can’t exfiltrate or pivot.

Before any prompt goes to a provider, the renderer’s prompt builder (src/features/ai/lib/promptBuilder.ts, using shared/protocol/ai/redaction.ts) scrubs sensitive material from the context snapshot:

  • Sensitive header names (Authorization, Cookie, X-Api-Key).
  • Token-shaped secret values in bodies, and environment-variable values (8+ characters) wherever they appear in the URL, headers or body.

The request URL itself is not redacted: the host and path reach the provider as written (ADR 0010 amendment). The composer’s Send raw (skip redaction) switch turns redaction off for a single message.

Error reporting is on by default and can be disabled in Settings → Privacy. Desktop errors and native crashes go to Sentry only while that preference is enabled; tracing is disabled, sendDefaultPii is false, and the scrubber removes request context, hostnames, users, breadcrumb data, stack-frame locals, secrets, and file paths. The same opt-out also controls Sentry Release Health’s desktop session data (active installs, crash-free rate and version adoption). Sessions carry a random install ID that isn’t derived from the device or user, is never attached to error reports, and is deleted on opt-out (ADR 0040).

For the hosted web app, /api/telemetry/error is a redacted, rate-limited, allowlist-only log sink and is never stored or forwarded to a third party. Self-hosted deployments collect no server-side usage telemetry. See ADR 0027 — Telemetry and privacy-preserving usage signal for the full decision.

When Restura acts as an MCP server (ADR 0041), the agent is treated as an untrusted consumer:

  • Transport. The server listens on 127.0.0.1 only, requires a 256-bit bearer token minted fresh on every start (kept in a 0600 handshake file the stdio relay reads), and refuses requests carrying browser Origin / Sec-Fetch-Site headers or a non-loopback Host (CSRF and DNS rebinding).
  • Policy in the data owner. Every call is forwarded to the renderer, which re-validates the input, checks per-collection / per-environment consent, asks for approval (always for deletes, sends and anything that adds a script, with the full script shown), and re-checks consent and a fingerprint of the approved state right before acting.
  • Redaction. Read tools strip auth descriptors, credential headers and params, URL userinfo and secret variables. SecretRef handles are never resolved. Send results mask credential headers, token-like JSON fields and JWTs, and every result passes a final deep redaction in main (shared/mcp-server/redaction.ts).
  • No secrets in, no self-escalation. Credential fields accept only {{variable}} references, secrets are typed by the user, and no tool can read or change MCP settings, keys, the vault, or proxy and TLS configuration.
  • Residual risk. Response bodies are third-party data: pattern-based redaction can miss an unusually named credential, and a response can attempt prompt injection. Sends are always approved by the user for that reason.

The deployed Cloudflare Worker requires one of:

  • WORKER_PROXY_TOKEN set as a secret, sent by the client as X-Restura-Proxy-Token.
  • REQUIRE_CF_ACCESS=true with CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD, and a Cloudflare Access policy in front of the Worker. Each request’s signed assertion is verified.

Local dev bypasses auth only when ENVIRONMENT=development and either Miniflare is detected or DEV_BYPASS_AUTH=true is set in .dev.vars. Never put DEV_BYPASS_AUTH in wrangler.jsonc (the deployed config).

CSRF defences that hold even with the bypass on:

  • Every POST /api/* must be Content-Type: application/json (415 otherwise), checked before auth — so another site can’t drive the proxy with a preflight-free text/plain or form POST.
  • In bypass mode a browser request whose Origin is neither the server’s own nor in ALLOWED_ORIGIN is refused with 403.
  • docker-compose.local.yml, which runs the bypass, publishes on 127.0.0.1 only.

Report security issues privately via GitHub security advisories. See SECURITY.md.