Getting started with ADsafe

ADsafe paired a restricted JavaScript language with a controlled interface to part of a web page. To understand a widget, start with its container, then follow the objects passed to its code.

What ADsafe is

A third-party script normally runs with access to the embedding page’s JavaScript environment. ADsafe’s proposal was to admit only code that followed a mechanically checkable subset, then give that code selected services through ADSAFE. The original site described this as an object-capability model: access depends on which objects and functions code can reach.

That design has two cooperating parts. Static checks reject forbidden language forms and access paths. The runtime supplies useful operations without returning unrestricted browser objects. Loading the runtime alone does not restrict arbitrary JavaScript. Equally, a restricted language would not protect a page if an approved method handed out its raw document.

Wrap the guest in a DIV

The original widget documentation requires a containing div. Give its root an identifier made from uppercase ASCII letters followed by an underscore, such as HELLO_. Other IDs in that fragment share the prefix and use uppercase identifiers. The host must ensure that every ID on the page is unique. The documentation also requires autocomplete="off" on input elements.

<div id="HELLO_">
  <p id="HELLO_MESSAGE">Waiting.</p>
  <script>
    ADSAFE.go("HELLO_", function (dom) {
      "use strict";
      dom.q("#HELLO_MESSAGE").value("Hello from the widget.");
    });
  </script>
</div>

The root ID and the string supplied to ADSAFE.go agree exactly. The callback receives a mediated dom object. Its query returns a bunch, which wraps selected nodes. The call to value changes the paragraph through that wrapper. The snippet is displayed as text; it does not execute here.

Read the historical validation workflow

1. The host loads its controlled copy of the runtime before widgets and host interceptors.
2. The widget author prepares the HTML fragment and restricted guest code together.
3. The historical JSLint ADsafe fragment checks validate the language and widget structure. The archived documentation names {adsafe: true, fragment: true}; this describes that historical workflow, not an option promised by today’s JSLint.
4. The page supplies approved services, checks the containing IDs for uniqueness and embeds the accepted fragment.
5. The final inline script calls ADSAFE.go to start the widget through its limited interface.

Add libraries deliberately

In the library pattern, the first script calls ADSAFE.id, approved external scripts register with ADSAFE.lib, and the last inline script calls ADSAFE.go. All those scripts sit directly inside the root DIV. The callback may receive a second argument, lib, containing the registered results. A library does not automatically receive the widget’s DOM; its methods would need to receive that capability deliberately.

Know what is blocked

The original rules exclude direct access to window, document and most globals. They restrict this, arguments, eval, with, dangerous member names and dynamic property lookup. There are also restrictions on names beginning or ending with an underscore and on nondeterministic facilities. These rules belong to the language and host model; they are not a universal filter applied by the runtime to every script on a page.

Continue with the API reference for signatures and version differences, the widget template for a small skeleton, and the security model for assumptions that the wrapper cannot enforce.