@transcend-io/penumbra

Penumbra (work in progress)

Note: this repo is a work in progress and should not be used in production yet.

Usage

Display an encrypted file

// Decrypt and display text
const decryptedText = await penumbra.getDecryptedContent({
  url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/NYT.txt.enc',
  filePrefix: 'NYT',
  mimetype: 'text/plain',
  decryptionOptions: {
    key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
    iv: '6lNU+2vxJw6SFgse',
    authTag: 'gadZhS1QozjEmfmHLblzbg==',
  },
});

document.getElementById('my-paragraph').innerText = decryptedText;


// Decrypt and display media
const imageSrc = await penumbra.getDecryptedContent({
  url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/tortoise.jpg.enc',
  filePrefix: 'tortoise',
  mimetype: 'image/jpeg',
  decryptionOptions: {
    key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
    iv: '6lNU+2vxJw6SFgse',
    authTag: 'ELry8dZ3djg8BRB+7TyXZA==',
  },
})

document.getElementById('my-img').src = imageSrc;

Download an encrypted file

penumbra.downloadEncryptedFile({
  url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/africa.topo.json.enc',
  filePrefix: 'africa',
  mimetype: 'image/jpeg',
  decryptionOptions: {
    key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
    iv: '6lNU+2vxJw6SFgse',
    authTag: 'ELry8dZ3djg8BRB+7TyXZA==',
  },
  progressEventName: 'download-progress' // defaults to the url
});

Prepare connections for file downloads in advance

// Resources to load
const resources = [
  {
    url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/NYT.txt.enc',
    filePrefix: 'NYT',
    mimetype: 'text/plain',
    decryptionOptions: {
      key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
      iv: '6lNU+2vxJw6SFgse',
      authTag: 'gadZhS1QozjEmfmHLblzbg==',
    },
  },
  {
    url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/tortoise.jpg.enc',
    filePrefix: 'tortoise',
    mimetype: 'image/jpeg',
    decryptionOptions: {
      key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
      iv: '6lNU+2vxJw6SFgse',
      authTag: 'ELry8dZ3djg8BRB+7TyXZA==',
    },
  }
]

// preconnect to the origins
penumbra.preconnect(...resources);

// or preload all of the URLS
penumbra.preload(...resources);

Download Progress Event Emitter

You can listen to a download progress event. The event name is the same as the url parameter

window.addEventListener(url, e => {
  console.log(`${e.detail.percent}% done`);
});

Note: this feature requires the Content-Length response header to be exposed. This works by adding Access-Control-Expose-Headers: Content-Length to the response header (read more here and here)

On Amazon S3, this means adding the following line to your bucket policy, inside the <CORSRule> block:

<ExposeHeader>Content-Length</ExposeHeader>

Big Thanks

Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs