# virtru-sdk-proxy

> A proxy to protect AppIds and bypass CORS

Latest version **2.0.1** (published 2021-05-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install virtru-sdk-proxy
pnpm add virtru-sdk-proxy
yarn add virtru-sdk-proxy
bun add virtru-sdk-proxy
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2021-05-11 |
| First published | 2021-05-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 6.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ryan Schumacher |
| Maintainers | virtru-admin |
| Keywords | cors, ie8, polyfill |

## Links

- npm: https://www.npmjs.com/package/virtru-sdk-proxy
- Repository: https://github.com/virtru/eternia
- Homepage: https://github.com/virtru/eternia#readme
- Issues: https://github.com/virtru/eternia/issues
- npm.io page: https://npm.io/package/virtru-sdk-proxy

## Dependencies (7)

- [binary](https://npm.io/package/binary.md) 2.0.0
- [precond](https://npm.io/package/precond.md) 1.0.0
- [bluebird](https://npm.io/package/bluebird.md) ~3.7.2
- [array.from](https://npm.io/package/array.from.md) ^1.1.0
- [vjwt-client](https://npm.io/package/vjwt-client.md) 0.3.1
- [url-ponyfill](https://npm.io/package/url-ponyfill.md) ^0.5.9
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.12.5

## Recent versions

- 2.0.1 (latest) — 2021-05-11

## README

# DEPRECATED

This browser proxy library is deprecated in favor of new Keycloak OIDC flows - current TDF SDKs/KAS
do not use this. Things that depend on this library should either be updated to use that flow or are
themselves deprecated.

# Virtru SDK Proxy · [![Build status](https://badge.buildkite.com/058c40802e584b21c8985471a8ab0b4774b82da41b53573af7.svg)](https://buildkite.com/virtru/virtru-sdk-proxy)

## What is this?

The Virtru SDK Proxy is a forked implementation of [XDomain](https://github.com/jpillora/xdomain)
whose purpose is to enable customers of the [Virtru SDK](https://developer.virtru.com/docs/sdk) to
embed the SDK on their own site under any domain. This allows the protection of files as well as
appIds being exposed via XSS and other vulnerabilities while

a.) allowing Virtru to maintain Origin restrictions on backend services, and b.) ~allowing the
customer to use the SDK without requiring Virtru intervention~ _Virtru requires whitelisting of
domains_ c.) allowing all AppIds to be secure behind
[same-origin policies](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) and
replacing them with shared secrets

## How does it work?

From a high level, the proxy workflow is as follows:

1. The Virtru SDK initiates a proxy url ([proxy.html](https://sdk.virtru.com/js/latest/proxy.html)
   for Production) that is hosted by Virtru, and hooks all XHR requests to Virtu's servers from the
   user's domain to use this proxy.
2. The Virtru-hosted `proxy.html` uses XDomain to create an iframe in the user's browser.
3. The Virtru SDK then makes requests to Virtru servers from any domain using XHR, and that XHR
   traffic is captured and proxied through the iframe via
   [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
4. The proxy code behind the iframe processes and forwards these requests to Virtru's backend
   services.
5. If needed, the proxy also filters or reformats data before sending it back to the Virtru SDK.

## Additional Protections

The Virtru SDK uses [virtru-client-oauth](https://github.com/virtru/virtru-client-oauth) for both
email loop as well as Oauth authentication with Virtru accounts, and as such the utility stores
Virtru appIds in browser local storage for easy storage and retrieval.

Due to the insecure nature of a customer hosting their own SDK implementation on an untrusted
domain, this appId could be potentially compromised via malicious scripts executing on that domain.
This issue is addressed by the proxy as follows:

1. The Virtru SDK hosted from, say, `example.com` makes an authentication request.
2. Once the account using the SDK is authenticated, the response from Virtru accounts is intercepted
   via the Virtru-hosted proxy (`proxy.html`).
3. The proxy, in its own iframe under the `sdk.virtru.com` domain, creates a random "shared secret"
   and uses this secret, in conjunction with the `example.com` domain, as a local storage key and
   stores the appId in local storage. Only scripts running under the `sdk.virtru.com` domain would
   be able to access this appId.
4. The proxy then returns as a response to the SDK (virtru-client-oauth), the "shared secret".
5. The "shared secret" is then stored in the user's local storage under the `example.com` domain.
6. Further requests to Virtru's backend services are handled by the Virtru SDK via construction of
   an Authorization header using the "shared secret". This shared secret is extracted via the proxy,
   and the proxy replaces it with the correct appId. Finally, the proxy forwards this request to the
   Virtru backend service.

### Add client domain to whitelist

To protect the Virtru ecosystem a whitelist has been enabled for the proxy. Follow these steps to
add a new client domain:

1. Checkout repo and create a new branch identifying the change (i.e.
   `feature/NOREF-add-mydomain.com`
2. Run `npm i` to install the dependencies
3. Add the client to `whitelist-clients.json`
4. Run `make bump`
5. Update the `changelog.md` bumping the version and identifying the change
6. Create the PR

A good example PR is #25. After your PR is approved merge it in and notify maintainers.

#### Maintainer Steps

Maintainer will need to go to
[buildkite](https://buildkite.com/virtru/virtru-sdk-proxy/builds?branch=master) and push to
production.

## Testing

To run tests

```
npm run test
```

### Local testing

The `testserver` folder contains an express server that enables local development of the TDF3 JS SDK
and proxy.

1. Clone virtru-tdf3-js locally and build it using `npm run build:local`.
2. Copy the resulting script packaged for the web at `dist/virtru-sdk.web.js` into this repo at
   `testserver/public`
3. In this repo, add `demos.developer.virtru.com` as a valid request URL by updating the
   isValidRequestUrl function found in `src/lib/virtru.js`:

```
if (currentHostnameEnv === 'demos.developer.virtru.com') {
  return true;
}
```

4. Build the proxy with `npm run build`, which should produce `proxy.html` in the `dist` folder.
5. Set your /etc/hosts to redirect `demos.developer.virtru.com` to localhost (127.0.0.1). This URL
   works because our backend has whitelisted it for CORS.
6. Run `node testserver/index.js` to start the express server
7. Open the testing file at https://demos.developer.virtru.com/

---
_Source: https://npm.io/package/virtru-sdk-proxy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._