Plugins for TLSN Extension

TLSN Extension has a plug-in system that safely extends the functionality of the extension.

What can you do with plugins?

A plugin can add new custom features to the extension using its built-in host functions:

• request private information from the browser, such as cookies and headers of one or more hostnames.
• submit new notarization request using the prove method in tlsn-js
• redirect a browsing window

New features/abilities will be added based on feedback from developers. Please reach out to us in Discord

Templates

tlsn-plugin-boilerplate contains a few examples of working plugins.

Configuration JSON

A plugin must include a configuration JSON file that describe its behavior and permissions.

{
  "title": "Twitter Profile",                 // name of the plugin
  "description": "Proof of profile name",     // description of the plugin's purpose
  "icon": "data:image/png;base64,...",        // OPTIONAL a base-64 string image containing the icon of the plugin
  "steps": StepConfig[],                      // An array describing the look and behavior of the Step UI described below
  "hostFunctions": ["redirect", "notarize"],  // the plugin will have access to this array of host functions
  "cookies": ["api.x.com"],                   // the plugin will have access to all cookies cached by the extension from these hosts
  "headers": ["api.x.com"],                   // the plugin will have access to all headers cached by the extension from these hosts
  "localStorage": ["x.com"],                  // the plugin will have access to all local storage cached by the extension from these hosts
  "sessionStorage": ["x.com"],                // the plugin will have access to all session storage cached by the extension from these hosts
  "requests": RequestObject[],                // list of requests that the plugin is allowed to make
  "notaryUrls": ["https://my-notary.dev"],    // list of notary that the plugin is allowed to use
  "proxyUrls": ["https://my-proxy.dev"],      // list of websocket proxy that the plugin is allowed to use
}

Step UI

The plugin system allows one to customize the UI and functionality of the side panel UI.

Step Configuation

type StepConfig = {
  title: string;         // text of the step's title
  description?: string;  // text of the step's description
  cta: string;           // text of the step's CTA button
  action: string;        // name of function that this step will execute
  prover?: boolean;      // boolean value indicating if this step outputs a notarization
}

Host Functions

Host functions are specific behavior allowed by the extension that the plugin can call. Host function usage are different depending on the language you choose to write your plugin. A javascript example is provided below.

redirect

Redirect the current tab to a different URL.

Example in JS

const { redirect } = Host.getFunctions();
const mem = Memory.fromString('https://x.com');
redirect(mem.offset);

notarize

Notarize a request using the prove method in tlsn-js

Example in JS

const { notarize } = Host.getFunctions();
const mem = Memory.fromString(JSON.stringify({
  url: "https://...",
  method: "GET",
  headers: {
    "authorization": "Bearer xxx",
    "cookie": "lang=en; auth_token=xxx",
  },
  secretHeaders: [
    "authorization: Bearer xxx",
    "cookie: lang=en; auth_token=xxx",
  ],
  getSecretBody: "parseResponse" // see redaction example below
}));
const idOffset = notarize(mem.offset);
const id = Memory.find(idOffset).readString();
Host.outputString(JSON.stringify(id)); // this outputs the notarization id 

Redaction

If a getSecretBody field is set, the corresponding method will be called to parse the response of the request

function parseResponse() {
  const bodyString = Host.inputString();
  const params = JSON.parse(bodyString);
  const revealed = `"screen_name":"${params.screen_name}"`;
  const selectionStart = bodyString.indexOf(revealed);
  const selectionEnd = selectionStart + revealed.length;
  const secretResps = [
    bodyString.substring(0, selectionStart),
    bodyString.substring(selectionEnd, bodyString.length),
  ];
  Host.outputString(JSON.stringify(secretResps));
}