@transcend-io/penumbra
Advanced tools
Encrypt/decrypt anything in the browser using streams on background threads.
Quickly and efficiently decrypt remote resources in the browser. Display the files in the DOM, or download them with conflux.
| .decrypt | .encrypt | .saveZip | |
|---|---|---|---|
| Chrome | ✅ | ✅ | ✅ |
| Edge >18 | ✅ | ✅ | ✅ |
| Safari ≥14.1 | ✅ | ✅ | ✅ |
| Firefox ≥102 | ✅ | ✅ | ✅ |
| Safari <14.1 | 🐢 | 🐢 | 🟡 |
| Firefox <102 | 🐢 | 🐢 | 🟡 |
| Edge 18 | ❌ | ❌ | ❌ |
✅ = Full support with workers
🐢 = Uses main thread (lacks native WritableStream support)
🟡 = 32 MiB limit
❌ = No support
yarn add @transcend-io/penumbra
# or
npm install --save @transcend-io/penumbra
import { penumbra } from '@transcend-io/penumbra';
penumbra.get(...files).then(penumbra.save);
<script src="lib/main.penumbra.js"></script>
<script>
penumbra
.get(...files)
.then(penumbra.getTextOrURI)
.then(displayInDOM);
</script>
Check out this guide for asynchronous loading.
penumbra.get() uses RemoteResource descriptors to specify where to request resources and their various decryption parameters.
/**
* A file to download from a remote resource, that is optionally encrypted
*/
type RemoteResource = {
/** The URL to fetch the encrypted or unencrypted file from */
url: string;
/** The mimetype of the resulting file */
mimetype?: string;
/** The name of the underlying file without the extension */
filePrefix?: string;
/** If the file is encrypted, these are the required params */
decryptionOptions?: PenumbraDecryptionInfo;
/** Relative file path (needed for zipping) */
path?: string;
/** Fetch options */
requestInit?: RequestInit;
/** Last modified date */
lastModified?: Date;
/** Expected file size */
size?: number;
};
Fetch and decrypt remote files.
penumbra.get(...resources: RemoteResource[]): Promise<PenumbraFile[]>
Encrypt files.
penumbra.encrypt(options: PenumbraEncryptionOptions, ...files: PenumbraFile[]): Promise<PenumbraEncryptedFile[]>
/**
* penumbra.encrypt() encryption options config (buffers or base64-encoded strings)
*/
type PenumbraEncryptionOptions = {
/** Encryption key */
key: string | Buffer;
};
Encrypt an empty stream:
size = 4096 * 128;
addEventListener('penumbra-progress', (e) => console.log(e.type, e.detail));
addEventListener('penumbra-complete', (e) => console.log(e.type, e.detail));
file = penumbra.encrypt(null, {
stream: new Response(new Uint8Array(size)).body,
size,
});
data = [];
file.then(async ([encrypted]) => {
console.log('encryption complete');
data.push(new Uint8Array(await new Response(encrypted.stream).arrayBuffer()));
});
Encrypt and decrypt text:
const te = new self.TextEncoder();
const td = new self.TextDecoder();
const input = '[test string]';
const buffer = te.encode(input);
const { byteLength: size } = buffer;
const stream = new Response(buffer).body;
const options = null;
const file = {
stream,
size,
};
const [encrypted] = await penumbra.encrypt(options, file);
const decryptionInfo = await penumbra.getDecryptionInfo(encrypted);
const [decrypted] = await penumbra.decrypt(decryptionInfo, encrypted);
const decryptedData = await new Response(decrypted.stream).arrayBuffer();
const decryptedText = td.decode(decryptedData);
console.log('decrypted text:', decryptedText);
Get decryption info for a file, including the iv, authTag, and key. This may only be called on files that have finished being encrypted.
penumbra.getDecryptionInfo(file: PenumbraFile): Promise<PenumbraDecryptionInfo>
Decrypt files.
penumbra.decrypt(options: PenumbraDecryptionInfo, ...files: PenumbraEncryptedFile[]): Promise<PenumbraFile[]>
const te = new TextEncoder();
const td = new TextDecoder();
const data = te.encode('test');
const { byteLength: size } = data;
const [encrypted] = await penumbra.encrypt(null, {
stream: data,
size,
});
const options = await penumbra.getDecryptionInfo(encrypted);
const [decrypted] = await penumbra.decrypt(options, encrypted);
const decryptedData = await new Response(decrypted.stream).arrayBuffer();
return td.decode(decryptedData) === 'test';
Save files retrieved by Penumbra. Downloads a .zip if there are multiple files. Returns an AbortController that can be used to cancel an in-progress save stream.
penumbra.save(data: PenumbraFile[], fileName?: string): AbortController
Load files retrieved by Penumbra into memory as a Blob.
penumbra.getBlob(data: PenumbraFile[] | PenumbraFile | ReadableStream, type?: string): Promise<Blob>
Get file text (if content is text) or URI (if content is not viewable).
penumbra.getTextOrURI(data: PenumbraFile[]): Promise<{ type: 'text'|'uri', data: string, mimetype: string }[]>
Save a zip containing files retrieved by Penumbra.
type ZipOptions = {
/** Filename to save to (.zip is optional) */
name?: string;
/** Total size of archive in bytes (if known ahead of time, for 'store' compression level) */
size?: number;
/** PenumbraFile[] to add to zip archive */
files?: PenumbraFile[];
/** Abort controller for cancelling zip generation and saving */
controller?: AbortController;
/** Allow & auto-rename duplicate files sent to writer. Defaults to on */
allowDuplicates: boolean;
/** Zip archive compression level */
compressionLevel?: number;
/** Store a copy of the resultant zip file in-memory for inspection & testing */
saveBuffer?: boolean;
/**
* Auto-registered `'progress'` event listener. This is equivalent to calling
* `PenumbraZipWriter.addEventListener('progress', onProgress)`
*/
onProgress?(event: CustomEvent<ZipProgressDetails>): void;
/**
* Auto-registered `'complete'` event listener. This is equivalent to calling
* `PenumbraZipWriter.addEventListener('complete', onComplete)`
*/
onComplete?(event: CustomEvent<{}>): void;
};
penumbra.saveZip(options?: ZipOptions): PenumbraZipWriter;
interface PenumbraZipWriter extends EventTarget {
/**
* Add decrypted PenumbraFiles to zip
*
* @param files - Decrypted PenumbraFile[] to add to zip
* @returns Total observed size of write call in bytes
*/
write(...files: PenumbraFile[]): Promise<number>;
/**
* Enqueue closing of the Penumbra zip writer (after pending writes finish)
*
* @returns Total observed zip size in bytes after close completes
*/
close(): Promise<number>;
/** Cancel Penumbra zip writer */
abort(): void;
/** Get buffered output (requires saveBuffer mode) */
getBuffer(): Promise<ArrayBuffer>;
/** Get all written & pending file paths */
getFiles(): string[];
/**
* Get observed zip size after all pending writes are resolved
*/
getSize(): Promise<number>;
}
type ZipProgressDetails = {
/** Percentage completed. `null` indicates indetermination */
percent: number | null;
/** The number of bytes or items written so far */
written: number;
/** The total number of bytes or items to write. `null` indicates indetermination */
size: number | null;
};
Example:
const files = [
{
url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/tortoise.jpg.enc',
name: 'tortoise.jpg',
mimetype: 'image/jpeg',
decryptionOptions: {
key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
iv: '6lNU+2vxJw6SFgse',
authTag: 'ELry8dZ3djg8BRB+7TyXZA==',
},
},
];
const writer = penumbra.saveZip();
await writer.write(...(await penumbra.get(...files)));
await writer.close();
Configure the location of Penumbra's worker threads.
penumbra.setWorkerLocation(location: WorkerLocationOptions | string): Promise<void>
const decryptedText = await penumbra
.get({
url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/NYT.txt.enc',
mimetype: 'text/plain',
filePrefix: 'NYT',
decryptionOptions: {
key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
iv: '6lNU+2vxJw6SFgse',
authTag: 'gadZhS1QozjEmfmHLblzbg==',
},
})
.then((file) => penumbra.getTextOrURI(file)[0])
.then(({ data }) => {
document.getElementById('my-paragraph').innerText = data;
});
const imageSrc = await penumbra
.get({
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==',
},
})
.then((file) => penumbra.getTextOrURI(file)[0])
.then(({ data }) => {
document.getElementById('my-img').src = data;
});
penumbra
.get({
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==',
},
})
.then((file) => penumbra.save(file));
// saves africa.jpg file to disk
penumbra
.get([
{
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==',
},
},
{
url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/NYT.txt.enc',
mimetype: 'text/plain',
filePrefix: 'NYT',
decryptionOptions: {
key: 'vScyqmJKqGl73mJkuwm/zPBQk0wct9eQ5wPE8laGcWM=',
iv: '6lNU+2vxJw6SFgse',
authTag: 'gadZhS1QozjEmfmHLblzbg==',
},
},
{
url: 'https://s3-us-west-2.amazonaws.com/bencmbrook/tortoise.jpg', // this is not encrypted
filePrefix: 'tortoise',
mimetype: 'image/jpeg',
},
])
.then((files) => penumbra.save({ data: files, fileName: 'example' }));
// saves example.zip file to disk
// 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);
You can listen to encrypt/decrypt job completion events through the penumbra-complete event.
window.addEventListener(
'penumbra-complete',
({ detail: { id, decryptionInfo } }) => {
console.log(
`finished encryption job #${id}%. decryption options:`,
decryptionInfo,
);
},
);
You can listen to download and encrypt/decrypt job progress events through the penumbra-progress event.
window.addEventListener(
'penumbra-progress',
({ detail: { percent, id, type } }) => {
console.log(`${type}% ${percent}% done for ${id}`);
// example output: decrypt 33% done for https://example.com/encrypted-data
},
);
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>
// Set only the base URL by passing a string
penumbra.setWorkerLocation('/penumbra-workers/');
// Set all worker URLs by passing a WorkerLocation object
penumbra.setWorkerLocation({
base: '/penumbra-workers/',
penumbra: 'worker.penumbra.js',
StreamSaver: 'StreamSaver.js',
});
// Set a single worker's location
penumbra.setWorkerLocation({ penumbra: 'worker.penumbra.js' });
penumbra-ready event<script src="lib/main.penumbra.js" async defer></script>
const onReady = async ({ detail: { penumbra } } = { detail: self }) => {
await penumbra.get(...files).then(penumbra.save);
};
if (!self.penumbra) {
self.addEventListener('penumbra-ready', onReady);
} else {
onReady();
}
You can check if Penumbra is supported by the current browser by comparing penumbra.supported(): PenumbraSupportLevel with penumbra.supported.levels.
if (penumbra.supported() > penumbra.supported.levels.possible) {
// penumbra is partially or fully supported
}
/** penumbra.supported.levels - Penumbra user agent support levels */
enum PenumbraSupportLevel {
/** Old browser where Penumbra does not work at all */
none = -0,
/** Modern browser where Penumbra is not yet supported */
possible = 0,
/** Modern browser where file size limit is low */
size_limited = 1,
/** Modern browser with full support */
full = 2,
}
Penumbra is compiled and bundled on npm. The recommended use is to copy in the penumbra build files into your webpack build.
We do this with copy-webpack-plugin
i.e.
const fs = require('fs');
const CopyPlugin = require('copy-webpack-plugin');
const path = require('path');
const PENUMBRA_DIRECTORY = path.join(
__dirname,
'node_modules',
'@transcend-io/penumbra',
'dist',
);
module.exports = {
plugins: [
new CopyPlugin({
patterns: fs.readdirSync(PENUMBRA_DIRECTORY)
.filter((fil) => fil.indexOf('.') > 0)
.map((fil) => ({
from: `${PENUMBRA_DIRECTORY}/${fil}`,
to: `${outputPath}/${fil}`,
})),
}),
]
# setup
yarn
yarn build
# run tests
yarn test:local
# run tests in the browser console
yarn test:interactive
FAQs
Crypto streams for the browser.
The npm package @transcend-io/penumbra receives a total of 1,122 weekly downloads. As such, @transcend-io/penumbra popularity was classified as popular.
We found that @transcend-io/penumbra demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.