Disclaimer

This project is a prototype, it has not been through any audit and is even not well tested. DO NO USE IN PRODUCTION. If you're interested in this repo, please give it a start ⭐ to encourage further development.

Introduction

Terrar.js offers HTML, CSS and JS isolations by using :

• the SES library to create rights-less JS compartements
• the native Proxy class to create parent-jailed HTMLElement objects
• the native Shadow DOM API to create HTML & CSS isolated contexts
• the Esprima library to prevent the encapsulated context from accessing disallowed objects

Installation

For server-side usage (NodeJS), Terrar.js can be installed like any NPM package :

npm install terrar

And then you can import it in your scripts using :

import "terrar";

For client-side usage (browser), simply put this <script> tag inside of your HTML document :

<script src="https://unpkg.com/terrar@latest"></script>

Usage

Like iframes, Terrar frames are a client-side way of isolating some content from the main context. However Terrar frames support SSR, which means that you can pre-populated frames with content generated on server side to reduces the amount of requests the page has to perform.

From JS

const content = `<!-- Your isolated HTML here -->`
terrar.createFrame(content)

From HTML

...
<terrar-frame src="https://isolated-content.here/index.html"></terrar-frame>
...

or

...
<terrar-frame>
  <template>
    <!-- Your isolated HTML here -->
  </template>
</terrar-frame>
...

Configuration

The preview Usage section simply shows how to insert an HTML content into a Terrar frame using the default configurations.

If the default configuration should fit most use cases, each Terrar frame can be me manually fine-grained configured to :

• allow / restrict the usage of some tags
• allow / restrict the usage of some properties
• expose / hide function from the main context

Limitations

Since Terrar.js createx SES compartement instead of a whole new Realm (a new JS context) like iframes, at lot of external ressources may not lot because of their CORS policy.

So Terrar.js is especially useful with :

• Contents you own but don't trust (e.g. user-provided HTML content)
• Contents you dynamically generate from JS and want to prevent collisions between them