# Security boundaries

The service grants policy-controlled filesystem access to configured filesystems. Keep it on a private network or behind TLS and restrict its listener/firewall to intended clients. A VPN is transport, not authentication. The standalone service requires a username and password; embedding applications can supply authentication hooks. The stock CLI is a single-principal reference service; use authorization hooks and credential ownership checks in multi-user applications.

Without a config file, `remotefs serve` exposes the home directory, mounted volumes and the host's private subnets, read/write, on loopback only; the banner lists them. Pass `--root`, `--allow-network` or `--no-defaults` to narrow that, and bind to a non-loopback address only on purpose: anyone who reaches the port and has valid login credentials can access every listed root according to policy. Configured services and the SDK start from empty roots and network ranges. Connections are checked against allowlists and hostnames are resolved/pinned inside the worker. Python SMB redirects to other servers are blocked. The standalone service supports writes by default; `--read-only` and explicit operation policies restrict it. The embedding SDK defaults to read-only. Local traversal, alternate Windows data streams and symlink/reparse entries are rejected. POSIX file access walks directory descriptors with `O_NOFOLLOW`; Windows file reads validate the final opened handle against the selected root. Windows directory metadata enumeration still uses pathname APIs: do not expose a writable adversarial namespace as a security boundary. Remote SMB/NFS servers and their filesystem namespace are trusted to enforce their own permissions; this is not an OS sandbox against a malicious NAS.

A worker owns one backend connection and at most four file streams. Operations time out and the worker is terminated if necessary. Workers expire after inactivity; streams close on completion/disconnect. Explicit session deletion closes immediately. HTTP control bodies are limited to 16 KiB; authenticated requests are rate-limited per principal. Native directory enumeration is capped and signals truncation. File responses are bounded chunks, with single-range support and attachment/nosniff headers.

Do not put passwords in descriptors, URLs, CLI arguments, logs or source control. Credential resolvers must check that the requesting principal owns each reference. Hook implementations must not log secrets. Config files contain the password hash and saved-location storage key and need restrictive permissions.

The standalone `remotefs serve` command can remember local, SMB and NFS folders, including SMB credentials, when the person saves a folder to the shortlist; folders on one share share those credentials. They are written to `saved.json` beside the service config, mode 600, encrypted with AES-GCM under a key derived from the private storage key with scrypt. Password changes preserve that key; a different storage key cannot open the file and the service refuses to overwrite it. Use "Forget" in the picker or delete `saved.json` to remove them. The SDK and `create_app` persist nothing unless an application passes a store or resolver.

System installers run the service as root/SYSTEM so NFS can use reserved source ports and local roots are visible. Narrow the policy carefully. Prefer an unprivileged service account when your NAS permissions allow it; filesystem permissions can then further limit access. Windows desktop drive mappings may not be visible to SYSTEM; connect to the SMB share directly instead.

Mounting (`--allow-mounts`, or `"mount"` in `policy.operations`) is off by default. When it is on, a signed-in user can make an SMB share, NFS export or cloud connection that their session can reach appear as a folder or drive on the service host. Programs running as the account that owns the mount can then use it within the mount's permissions. On Windows the drive's access list names only that account, and the SYSTEM service starts rclone inside the `mount_owner` account's own session, refusing to mount when that account isn't signed in. On Linux and macOS a mount made by a root service is usable by root only. Mounts allow changes when the session allows writes, unless the user asks for a read-only mount. NFS mounts add a WebDAV server per mount that listens only on 127.0.0.1 behind its own random password. Each mount's rclone configuration (with the SMB password in rclone's obscured, reversible form) is written with owner-only permissions under the service's configuration folder (on Windows under the mount owner's own profile when the service runs as SYSTEM) and deleted on eject. Its remote-control endpoint listens only on 127.0.0.1 behind a random password passed through the environment. Enable mounting only on hosts where the people who can sign in may also use those files locally. On Windows, the app can install WinFsp from its official release after checking a pinned SHA-256; this runs an elevated installer and requires the signed-in user to approve Windows' prompt.

If you identify a vulnerability, use GitHub's private vulnerability reporting for this repository. Do not post credentials, real filesystem data, or exploitable access details in public issues.

Standalone login stores a salted scrypt hash (N=131072, r=8, p=1). Browser cookies are HttpOnly, SameSite=Strict, eight-hour sessions and Secure over HTTPS. Cookie-authenticated mutations require the same Origin. Ten login attempts per client address per five minutes are allowed, and concurrent password hashing is limited to two. Use HTTPS or an encrypted tunnel when sending passwords across a network. Account reset requires local config access and a service restart; it preserves the saved-location storage key. The SDK can still supply its own authentication hook or explicit bearer credential for existing integrations.

Writes are staged and no-replace publication uses atomic platform primitives for local/SMB files and NFS LINK. Multi-entry operations are not transactions. POSIX mutation parents are held by directory descriptors; Windows mutation parents are held without delete sharing and the final handle path is validated. Remote namespaces remain trusted. See the README for interrupted-operation and permission-inheritance limits.