Developing with Codesealer

Codesealer aims to not interfere with the normal development flow of web applications. However, there are a few things that a developer should be aware of when creating an application that is to be protected by Codesealer. These a described in the following sections.

Requirements

A site protected by Codesealer Enterprise must respond correctly to the Host header or SNI used by the end-user browser. This means that if the end-user enters https://example.com, the backend server must expect and respond to a HTTP Host header field value of “example.com”, serve content where absolute URLs are based on https://example.com, and respond with cookies scoped to example.com.

Codesealer Enterprise can perform rudimentary host remapping for testing and debugging purposes, but this functionality is limited and not intended for production use.

Limitations

Script tag content and attribute access

Scripts protected by Codesealer Enterprise have their original script tag replaced with an empty script tag with no attributes (a placeholder). This is done to hide all details about the code that is being executed. The empty placeholder script tag is left behind in order to not change DOM node indices.

As a side-effect, code that searches for script tags or inspects the content of script tags that we are protecting will not be able to find what it is looking for. This is intentional behavior. To retain some of this functionality, see the "Retain attributes on protected scripts" option.

In most cases, this behavior can be avoided or disabled. How this is done depends on the code in question.

Loading scripts by appending tags to the document

Protection of script tags is performed as the original HTML is delivered. Injection of additional script tags will operate as if Codesealer Enterprise was not there, with no additional protection.

Application Network Protection (ANP) must be used to securely transfer scripts needed at runtime. This can be done transparently through XMLHttpRequest and fetch if enabled in the Management Portal for the Endpoint, see the "Enable ANP on dynamic content" option.

Scripts in HTML template tags

Scripts can be placed in an HTML <template> tag and then be inserted into the actual DOM at a later point in time. Such scripts are not protected by Codesealer, i.e. their content or src attribute will be visible. The content scripts inserted from a template can be protected by using the the "Enable ANP on dynamic content" option.

ES6 Modules

Codesealer handles ES6 modules (<script type="module">) by bundling each module into a single file in the reverse proxy. This can result in a client side performance hit and increased traffic to the backend, especially where dynamic imports of larger files are used, as the proxy will need to fetch all dynamic imports even if they end up not being used.

In order to reduce the performance hit, it is recommended to use Codesealer's caching feature. See the "Cache Settings" section for more details.

Synchronous DOM access (e.g., document.write)

Scripts protected by Codesealer Enterprise are subject to deferred execution, and will not be executing while the DOM is open at the point of the script tag.

For all intents and purposes, scripts protected by Codesealer can be considered to have the defer attribute. As a result, the document will have processed further than without Codesealer Enterprise, and the document will be closed. A call to document.write at this point willl re-open and thus clear the entire document rather than append to the current document.

Instead of using document.write, an application should use deterministic DOM manipulation APIs, such as createElement and appendChild.

Alternatively, document.write compatibility can be enabled in the management portal, see "document.write compatibility mode".

ServiceWorkers and WebWorkers

Codesealer Enterprise does not currently protect ServiceWorkers or WebWorkers. These will continue operating unaffected, without any change in operation.

One important thing to note, is that when a ServiceWorker is used as a proxy for requests, it will see the encrypted requests that Codesealer has already processed. This means that instead of requests to individual resources, it will see multiple requests to the /~bl/x endpoint. If the service worker takes action based on the content or URL of these requests, that functionality is likely to break when using codesealer. Examples could be a ServiceWorker used for selective caching of resources, that will simply cease to cache when using Codesealer.

JavaScript Scoping

Running an application through Codesealer changes the scope of the running Javascript code. Some of the effects are described below. Most of these changes can be automatically fixed by Codesealer by enabling the Window scope compatibility mode.

Global variable shadowing

Some statements present in traditional scripts executed in global scope of an HTML document, such as the assignment

var window = window || {};

will have no functional effect without Codesealer. With Codesealer, however, scripts are internally executed in a functional scope, which means that JavaScript variable hoisting will run through all var assignments before executing the code in the function scope. This will effectively shadow the global window object, replacing it with an empty object.