WIP: extension documentation

src/SUMMARY.md

@@ -31,6 +31,12 @@
 - [MAC](./mpc/mac.md)
 - [Commitments](./mpc/commitments.md)
 
+# Browser Extension
+
+- [Extension](./extension/extension.md)
+  - [Plugins](./extension/plugins.md)
+  - [Provider API](./extension/provider.md)
+
 <!-- [Verification Steps](./spec/verification_steps.md) -->
 
 +[Glossary](./glossary.md)

src/extension/extension.md

@@ -0,0 +1,11 @@
+# Chrome Extension (MV3) for TLSNotary
+
+> Important
+> 
+> ⚠️ When running the extension against a notary server, please ensure that the server's version is the same as the version of this extension
+
+
+TODO
+
+  - [Plugins](./plugins.md)
+  - [Provider API](./provider.md)

src/extension/plugins.md

@@ -0,0 +1,105 @@
+# Browser extension plugins
+
+TLSN Extension has a plugin system that safely extends the functionality of the extension. The plug-in system is based on [Extism](https://extism.org/docs/concepts/plug-in-system) which allows you to write plugins in the language of your choice. This page focuses on plugins in TypeScript.
+
+## 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](https://github.com/tlsnotary/tlsn-js/blob/main/src/tlsn.ts#L48-L89) method in [tlsn-js](https://www.npmjs.com/package/tlsn-js)
+- redirect a browsing window
+
+New features/abilities will be added based on feedback from developers. Please reach out to us in [Discord](https://discord.gg/9XwESXtcN7)
+
+## Templates and examples
+
+[tlsn-plugin-boilerplate](https://github.com/tlsnotary/tlsn-plugin-boilerplate/tree/main) contains a few examples of working plugins.
+
+## Configuration JSON
+
+A plugin must include a configuration JSON file that describe its behavior and permissions. 
+
+```ts
+{
+  "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
+  "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.
+
+<img src="images/steps_ui.png" height="640">
+
+### Step Configuation
+```ts
+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](https://extism.org/docs/concepts/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
+```js
+const { redirect } = Host.getFunctions();
+const mem = Memory.fromString('https://x.com');
+redirect(mem.offset);
+```
+
+### `notarize`
+Notarize a request using the [prove](https://github.com/tlsnotary/tlsn-js/blob/main/src/tlsn.ts#L48-L89) method in [tlsn-js](https://www.npmjs.com/package/tlsn-js)
+
+#### Example in JS
+```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
+```ts
+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));
+}
+```

src/extension/provider.md

@@ -0,0 +1,206 @@
+# TLSN Extension's Provider API
+
+This page is a reference for the TLSN Extension's Provider API. The TLSN Extension injects a provider API into websites visited by its users using the `window.tlsn` provider object. This allows webpages to connect with the TLSN Extension and query TLSN attestations, with the User's permission of course.
+
+## Connect to TLSN Extension
+
+### `tlsn.connect()`
+
+This method is used to request a website to be connected to the extension. Once a provider is connected, a website can use the provider API to suggest actions to the extension.
+
+#### Parameters
+None.
+
+#### Returns
+A promise that resolves to the full provider API object.
+
+#### Example
+```ts
+const client = await tlsn.connect();
+```
+
+#### Screenshot
+![Screenshot 2024-07-04 at 2 22 00 PM](./images/connect.png)
+
+
+## Provider API Method
+
+### `client.getHistory(method, url, metadata)`
+
+This method is used to request proof history from the extension.
+
+#### Parameters
+1. `method`: a glob pattern matching request method of the proof. (e.g. `get`, `{get,post}`, `*`)
+2. `url`: a pattern matching request url of the proof. (e.g. `**`, `https://swapi.dev/**`)
+3. `metadata`: an object containing glob patterns of matching metadata about the request. (e.g. `{id: "swapi-proof-1"}`)
+
+#### Returns
+A promise that resolves to an array of proof header data.
+```ts
+type ProofHeader = {
+  id: string;
+  method: string;
+  notaryUrl: string;
+  time: string;
+  url: string;
+  websocketProxyUrl: string;
+}
+```
+
+#### Example
+```ts
+const proofs = await client.getHistory('*', '**', {id: '0x1234567890'});
+```
+
+#### Screenshot
+![Screenshot 2024-07-04 at 2 41 56 PM](./images/share_proof_history.png)
+
+### `client.getProof(id)`
+This method is used to request full data of a specific proof id.
+
+#### Parameters
+1. `id`: id of a proof
+
+#### Returns
+A promise that resolves to the proof data or null.
+```ts
+type ProofData = {
+  notaryUrl: string;
+  session: Session; // https://github.com/tlsnotary/tlsn-js/blob/main/src/types.ts#L7-L11;
+  substrings: Substrings; // https://github.com/tlsnotary/tlsn-js/blob/main/src/types.ts#L73-L76
+}
+```
+#### Example
+```ts
+const proof = await client.getProof('FE512M1.72007336176400000000000000000000');
+```
+#### Screenshot
+![Screenshot 2024-07-04 at 2 44 00 PM](./images/share_proof_data.png)
+
+### `client.notarize(url, requestOptions, proofConfig)`
+This method is used to request notarization of a request.
+
+#### Parameters
+1. `url`: url of the request
+2. `requestOptions`: An object containing the following:
+    1. `method`: `GET`, `POST`, `PUT`, etc
+    2. `headers`: a map of headers
+    3. `body`: string content of the request body
+3. `proofConfig`: An object containing the following:
+    1. `notaryUrl`: url of the notary (default to the extension setting)
+    2. `websocketProxyUrl`: url of the websocket proxy (default to extension setting)
+    3. `maxSentData`: Max Sent Data allowed (default to extension setting)
+    4. `maxRecvData` Max Recv Data allowed (default to extension setting)
+    5. `maxTranscriptSize`: Max transcript size allowed  (default to extension setting)
+    6. `metadata`: a object of metadata
+
+#### Returns
+A promise that resolves to the proof data.
+```ts
+type ProofData = {
+  notaryUrl: string;
+  session: Session; // https://github.com/tlsnotary/tlsn-js/blob/main/src/types.ts#L7-L11;
+  substrings: Substrings; // https://github.com/tlsnotary/tlsn-js/blob/main/src/types.ts#L73-L76
+}
+```
+#### Example
+```ts
+const proof = await client.notarize(
+  'https://swapi.dev/api/planets/9',
+  {
+    method: 'get',
+    headers: {
+      "Accept": "application/json",
+      "Accept-Encoding": "identity",
+      "Connection": "close",
+      "Cookie": "csrftoken=blahblahblah",
+    }
+  },
+  {
+    metadata: {id: 'test-1'},
+  }
+);
+```
+
+#### Screenshot
+![Screenshot 2024-07-04 at 2 54 48 PM](./images/notarize.png)
+
+### `client.installPlugin(url, metadata)`
+This method is used to request installation of a plugin.
+
+#### Parameters
+1. `url`: url to the plugin wasm file
+2. `metadata`: a object of metadata about the plugin
+
+#### Returns
+A promise that resolves to plugin id.
+
+#### Example
+```ts
+const pluginId = await client.installPlugin(
+  'https://github.com/tlsnotary/tlsn-extension/raw/main/plugins/twitter_profile/index.wasm',
+  { id: 'demo-plugin-1' }
+);
+```
+
+#### Screenshot
+![Screenshot 2024-07-04 at 3 05 54 PM](./images/install_plugin.png)
+
+### `client.getPlugins(url, origin, metadata)`
+This method is used to request installation of a plugin.
+
+#### Parameters
+1. `url`: a glob pattern matching url to the plugin wasm file
+2. `origin`: a glob pattern matching origin that request installation of the plugin
+3. `metadata`: a object of glob patterns matching metadata about the plugin
+
+#### Returns
+A promise that resolves to plugin config.
+
+```ts
+type PluginConfig = {
+  hash: string;
+  title: string;
+  description: string;
+  icon?: string;
+  steps?: StepConfig[];
+  hostFunctions?: string[];
+  cookies?: string[];
+  headers?: string[];
+  requests: { method: string; url: string }[];
+  notaryUrls?: string[];
+  proxyUrls?: string[];
+};
+```
+
+#### Example
+```ts
+const plugin = await client.getPlugins('**', 'https://swapi.dev', {id: 'demo-plugin-1'});
+```
+
+#### Screenshot
+![Screenshot 2024-07-04 at 3 23 14 PM](./images/share_installed_plugins.png)
+
+### `client.runPlugin(id)`
+This method is used to request execution of a plugin.
+
+#### Parameters
+1. `id`: id of a plugin
+
+#### Returns
+A promise that resolves to the proof data.
+```ts
+type ProofData = {
+  notaryUrl: string;
+  session: Session; // https://github.com/tlsnotary/tlsn-js/blob/main/src/types.ts#L7-L11;
+  substrings: Substrings; // https://github.com/tlsnotary/tlsn-js/blob/main/src/types.ts#L73-L76
+}
+```
+
+#### Example
+```ts
+const plugin = await client.runPlugin("6931d2ad63340d3a1fb1a5c1e3f4454c5a518164d6de5ad272e744832355ee02");
+```
+
+#### Screenshot
+![Screenshot 2024-07-04 at 3 24 09 PM](./images/execute_plugin.png)