# App Security

Whisk is a modern macOS application. As such, it must utilize many platform security technologies to be distributed both on the Mac App Store and via direct download.

Usability and security are classically in conflict with each other: a 100% secure app would not do much. Data does not live in a vacuum. As a user you need to be informed to make the decision on risks and tradeoffs you are willing to accept by using software. This page documents the primary security technologies employed by Whisk and the access the app requires to maintain usability.

# App Sandboxing

App Sandboxing is a security technology Apple introduced in macOS 10.7 restricting the files and hardware an application is allowed to access. Applications must explicitly declare what abilities they need with a system called "entitlements." The App Sandbox can also grant access to files based on intent: if a file is chosen from an File > Open… panel or dragged in from the Finder, then the application is granted access.

It may seem that a lightweight editor like Whisk would not need file access beyond this, but Whisk would not be very useful in such a scenario. Consider that a .html file as part of a project with many assets. It was granted access by dragging onto the Whisk app icon in the Dock, and therefore gets opened by Whisk. It contains the following markup:

<img src = "./mySecondImage.jpg" />

In this case, the ./myImage.jpg asset is a local file not granted access to Whisk, and it will fail to display – the page will appear broken in the Web Preview.

The situation gets more complex with PHP code. Here, PHP can call require() or include() to load associated files, along with code containing fread() and fwrite() to read and write files as your program directs.

The arbitrary nature of paths within code coupled with the rapid development Whisk seeks to enable means that individually granting access to required files would become a usability nightmare. Therefore Whisk needs broad filesystem access. This is achieved differently on the Tumult Store and Mac App store version of Whisk.

# App Sandboxing on the Mac App Store

Since macOS 10.7.4, Apple has required App Sandboxing to be enabled for all applications submitted to the Mac App Store. It is highly unlikely the file system access entitlements Whisk needs (and that the Tumult Store version uses) would ever be approved by Apple's review process. Therefore to function, users are required to grant permissions in the implicit manner of opening a folder or volume.

If Whisk detects trying to preview a file it does not have permission to or run PHP, it will prompt for access:

Clicking "Allow Access…" will show a typical Open Panel:

You can navigate to a top-level folder of your project or all projects and then click the "Allow Access" button to give Whisk access to those files. The further up you go, the less prompts you are likely to see in the course of using Whisk. If you navigate to the root of your disk, typically titled "Macintosh HD", and click the "Allow Access" button and then Whisk will function as expected without any additional prompts.

The Mac App Store version has an additional File Access Preference Pane which shows all folders and volumes that you have granted permission to access.

Whisk's File Access Preferences
Whisk's File Access Preferences

You can grant access in this preference panel. This is especially useful if Whisk had not autodetected that outside assets are being used.

If you intend to never allow Whisk to have file system access, you can uncheck "Prompt when further access is needed" to never display the access dialog.

If you want to revoke Whisk's file system access, you can do so by clicking the "Restore Defaults" button. A confirmation is required:

Confirmation to revoke file system access
Confirmation to revoke file system access

# App Sandboxing on the Tumult Store

Direct distribution apps like the Tumult Store version of Whisk are not required by Apple to use the App Sandboxing technology. To improve user security and keep the two versions as close together as possible, the Tumult Store version of Whisk still enables App Sandboxing. To improve common usability, it has these two entitlements:

  • The Tumult Store version of Whisk has a full access entitlement to read as your user account to the file system. This is for any files referenced in your code can be rendered by the web preview.
  • The Tumult Store version of Whisk has a full access entitlement to write as your user account to the file system. This is for PHP code to use write commands.

While these may sound overly permissive, all non-sandboxed apps can read and write to the filesystem. Thus, this is the case for a vast majority of apps that are not distributed on Mac App Store. Whisk is not privileged beyond the user account in which it is run; standard UNIX file permissions, access control lists, and other macOS technologies will still restrict certain file operations.

# Other Entitlements

Both the Tumult Store and Mac App Store versions of whisk also declare these entitlements:

  • Read access to HyperEdit (aka Whisk 1.0) preferences and color swatches
  • Network client access, as your HTML content may access online resources
  • Network server access, because the preview uses a web server to create network conditions and host previews to browsers installed on your computer

# macOS 10.15+ Catalina Files and Folder Access

Whisk is also subject to further OS-level file and folder protections. On macOS 10.15 Catalina and later, Whisk may prompt for access to your Documents, Desktop, or Downloads folders. You can audit this access via the System Preferences' Security Pref Pane under the Privacy tab's "Files and Folders" section.

# WKWebView-based Web Preview

Whisk's web preview renders content using the macOS component known as WKWebView. Under-the-hood, this is the same WebKit rendering engine that powers Safari. It is standards compliant and fast.

More specifically, WKWebView is built upon a technology called WebKit2. The salient feature of WebKit2 is that all web page content is rendered using a separate process than the host application. This improves security through isolation and the separate rendering process can be sandboxed more aggressively than the host application.

# Preview Server

To more accurately simulate how your content would behave on its final server, Whisk uses its own web server to host content for the application's web preview and browser-based previews. (The alternative would be to use file:///-style URLs which are subject to different CORS rules and cannot make XMLHTTPRequests.)

By default, Whisk's preview server only allows your machine (localhost) to connect; all other attempted connections are rejected. Therefore others on your network or on the wider internet cannot see the content you are working on.

Previews can be made to iPhones or iPads over the network using the Hype Reflect application. These are initiated by you within the Whisk application. This adds the IP address of the iOS device to the access list, and then the device is allowed to request the page. This access is reset when Whisk is relaunched.

# Validation Process

For HTML/XHTML validation, Whisk uses The Nu Html Checker (v.Nu). This is a Java-based program, and therefore Whisk contains a minimal version of the Java Runtime. The vnu process itself hosts a HTTP server. Whisk connects to this and makes queries with the HTML page and vnu returns a list of issues or errors. This server only accepts connections from your machine (localhost).

# PHP

To render PHP, Whisk runs the command line php application. Its path is specified in Whisk's General Preferences.

The program runs with permissions that are inherited from the App Sandbox. On the Mac App Store version of Whisk, you will need to grant access to use functionality like require(), include(), fread() or fwrite().

WARNING

Be careful when using PHP with a live preview. Half-written lines of code may by syntactically correct but have seriously wrong consequences. It is often a good idea to change the web preview refresh to be manually triggered.

# Direct Download Distribution

The Tumult Store direct download version of Whisk makes use of several OS technologies which ensure you are running a malware-free application which came from Tumult.

# Code Signing

Whisk is Code Signed with Tumult's Developer ID certificate. This ensures that the app comes from Tumult and its contents have not been modified.

# Notarization & Gatekeeper

Whisk is notarized by Apple. Notarization ensures known malware is not contained in the application. Notarization also imposes other strict app security requirements on Whisk, such as using a hardened runtime.

The basic flow of notarization is:

  • The code signed Whisk application is uploaded to Apple's servers
  • Apple checks the application for malware and other issues which ensure its security
  • If everything checks out, Apple's servers keep a record that the specific bits are okay
  • When you launch the application for the first time, Gatekeeper looks online for this record, and on macOS 10.14.5 or later will only allow running if it is found.

On first launch of the Tumult Store version, Gatekeeper will present a dialog that looks like:

Gatekeeper dialog presented on first launch
Gatekeeper dialog presented on first launch

The dialog and its wording has changed over the course of macOS releases, but all versions will list the source as coming from tumult.com. If it does not state this then the application may have been compromised. "Apple checked it for malicious software and none was detected" appears on some variants and indicates you are running an notarized app.

TIP

Notarization is only checked on macOS 10.14 or later. Prior to this, Gatekeeper will instead display a dialog on first launch regarding Whisk's code signing status alone.

Apple has a support document about how to Safely open apps on your Mac.

# Updating

The Tumult Store version of Whisk uses a 3rd party library called Sparkle to assist in downloading and installing app updates. Sparkle is widely used by other macOS apps. Whisk updates are distributed over a secure HTTPS connection, and verified with an EdDSA signature.