Plugin and provider API 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,10 @@
+# Chrome Extension (MV3) for TLSNotary
+
+> **Important**
+> 
+> ⚠️ When running the extension against a notary server, ensure that the notary server's version matches the version of this extension.
+
+The TLSNotary browser extension includes a plugin system that allows you to safely extend its functionality with custom plugins tailored to your specific data sources. This section also explains how to interact with the TLSN Extension within web applications.
+
+- [Plugins](./plugins.md)
+- [Provider API](./provider.md)

src/extension/plugins.md

@@ -0,0 +1,121 @@
+# Browser Extension Plugins
+
+The **TLSN Extension** has a plugin system that allows you to safely extend its functionality. The plugin system is based on [Extism](https://extism.org/docs/concepts/plug-in-system), which enables you to write plugins in the programming language of your choice. This page focuses on plugins written in TypeScript.
+
+## What Can You Do with Plugins?
+
+Plugins can add new custom features to the extension by using built-in host functions, such as:
+
+- Requesting private information from the browser, such as cookies and headers of one or more hostnames.
+- Submitting a 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).
+- Redirecting a browsing window.
+
+New features and capabilities will be added based on feedback from developers. Please reach out to us on [Discord](https://discord.gg/9XwESXtcN7).
+
+## Templates and Examples
+
+You can find a boilerplate template at [tlsn-plugin-boilerplate](https://github.com/tlsnotary/tlsn-plugin-boilerplate), which is a great starting point. This repository explains how to compile and test Typescript plugins.
+
+The [examples folder](https://github.com/tlsnotary/tlsn-plugin-boilerplate/tree/main/examples) contains more examples of TLSNotary plugins.
+
+## Configuration JSON
+
+A plugin must include a configuration JSON file that describes its behavior and permissions.
+
+<!-- https://github.com/tlsnotary/tlsn-extension/blob/p2p/src/utils/misc.ts#L315-L326 -->
+```ts
+export type PluginConfig = {
+  title: string;           // The name of the plugin
+  description: string;     // A description of the plugin's purpose
+  icon?: string;           // A base64-encoded image string representing the plugin's icon (optional)
+  steps?: StepConfig[];    // An array describing the UI steps and behavior (see Step UI below) (optional)
+  hostFunctions?: string[];// Host functions that the plugin will have access to
+  cookies?: string[];      // Cookies the plugin will have access to, cached by the extension from specified hosts (optional)
+  headers?: string[];      // Headers the plugin will have access to, cached by the extension from specified hosts (optional)
+  requests: { method: string; url: string }[]; // List of requests that the plugin is allowed to make
+  notaryUrls?: string[];   // List of notary services that the plugin is allowed to use (optional)
+  proxyUrls?: string[];    // List of websocket proxies that the plugin is allowed to use (optional)
+};
+```
+
+## Step UI
+
+The plugin system allows customization of the UI and the functionality of the side panel.
+
+<img src="images/steps_ui.png" height="640">
+
+### Step Configuration
+
+The steps are declared in the JSON configuration:
+
+```ts
+type StepConfig = {
+  title: string;         // Text for the step's title
+  description?: string;  // OPTIONAL: Text for the step's description
+  cta: string;           // Text for the step's call-to-action button
+  action: string;        // The function name that this step will execute
+  prover?: boolean;      // Boolean indicating if this step outputs a notarization
+}
+```
+
+You need to implement the functionality of the steps in `src/index.ts`. The function names must match the corresponding step names in the JSON configuration.
+
+## Host Functions
+
+<!-- https://github.com/tlsnotary/tlsn-extension/blob/fe56de0b6cb4e235cabb0f8b2216853de2adb47f/src/utils/plugins.tsx#L5 -->
+[Host functions](https://extism.org/docs/concepts/host-functions) are specific behaviors provided by the extension that the plugin can call. Host function usage may vary depending on the language used to write the plugin.
+
+### `redirect`
+
+Redirects the current tab to a different URL.
+
+Example in JavaScript:
+```js
+const { redirect } = Host.getFunctions();
+const mem = Memory.fromString('https://x.com');
+redirect(mem.offset);
+```
+
+### `notarize`
+
+Notarizes 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 JavaScript:
+```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)); // Outputs the notarization ID
+```
+
+#### Redaction
+
+If the `getSecretResponse` field of the `notarize` host function call is set, the corresponding method will be called to parse the response of the request. Make sure to also export this function in the `main` module declaration in `index.d.ts`.
+
+```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,215 @@
+# TLSN Extension's Provider API
+
+This page is a reference for the **TLSN Extension's Provider API**. This API can be used in web pages to request attestation history, notarize requests, manage plugins, and more from the TLSN extension.
+
+The TLSN Extension injects a provider API into websites visited by its users using the `window.tlsn` provider object. This allows webpages to **connect to 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 connection between the website and the extension. Once connected, the website can use the provider API to request actions from 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 Methods
+
+### `client.getHistory(method, url, metadata)`
+
+This method is used to request attestation history from the extension.
+
+#### Parameters
+1. `method`: A glob pattern matching the request method of the proof. (e.g., `get`, `{get,post}`, `*`)
+2. `url`: A glob pattern matching the request URL of the proof. (e.g., `**`, `https://swapi.dev/**`)
+3. `metadata`: An object containing glob patterns that match 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 the full data of a specific proof by its ID.
+
+#### Parameters
+1. `id`: The ID of the 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 specific request.
+
+#### Parameters
+1. `url`: The 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`: The string content of the request body.
+3. `proofConfig`: An object containing the following:
+    1. `notaryUrl`: URL of the notary (defaults to the extension's setting).
+    2. `websocketProxyUrl`: URL of the websocket proxy (defaults to the extension's setting).
+    3. `maxSentData`: Maximum allowed sent data (defaults to the extension's setting).
+    4. `maxRecvData`: Maximum allowed received data (defaults to the extension's setting).
+    5. `maxTranscriptSize`: Maximum allowed transcript size (defaults to the extension's setting).
+    6. `metadata`: An object containing 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 the installation of a plugin.
+
+#### Parameters
+1. `url`: The URL to the plugin's WASM file.
+2. `metadata`: An object containing metadata about the plugin.
+
+#### Returns
+A promise that resolves to the 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 query installed plugins.
+
+#### Parameters
+1. `url`: A glob pattern matching the URL to the plugin's WASM file.
+2. `origin`: A glob pattern matching the origin requesting the plugin installation.
+3. `metadata`: An object containing glob patterns matching metadata about the plugin.
+
+#### Returns
+A promise that resolves to the plugin configuration.
+
+```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 the execution of a plugin.
+
+#### Parameters
+1. `id`: The ID of the 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)