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 appendChild" 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 (i.e. document.write will re-open and thus clear the entire document rather than append to the current document).

The protected application should not rely upon such functionality or behavior. If document modifications are required, use deterministic DOM manipulation such as createElement and appendChild.

Readiness events (e.g., `DOMContentLoaded`)

Scripts protected by Codesealer Enterprise are subject to deferred execution and will run after events such as DOMContentLoaded have fired.

Instead of waiting for DOMContentLoaded to initialize or run code, set defer on the script tag and run the code directly without an event handler. The defer attribute will ensure that the behavior is maintained when not protected by Codesealer Enterprise.

Alternatively, DOMContentLoaded simulation for compatibility can be enabled in the management portal, see the "Inject DomContentLoaded event" option.

ServiceWorkers and WebWorkers

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

JavaScript Scoping

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.