/**  * 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?: PenumbraDecryptionOptions; /** Relative file path (needed for zipping) */ path?: string; /** Fetch options */ requestInit?: RequestInit; /** Last modified date */ lastModified?: Date; /** Expected file size */ size?: number; };

penumbra.get(...resources: RemoteResource[]): Promise<PenumbraFile[]>

penumbra.encrypt(options: PenumbraEncryptionOptions, ...files: PenumbraFile[]): Promise<PenumbraEncryptedFile[]> /**  * penumbra.encrypt() encryption options config (Uint8Array or base64-encoded string)  */ type PenumbraEncryptionOptions = { /** Encryption key */ key: string | Uint8Array; };

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())); });

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);

penumbra.getDecryptionInfo(file: PenumbraFile): Promise<PenumbraDecryptionOptions>

penumbra.decrypt(options: PenumbraDecryptionOptions, ...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';

penumbra.save(data: PenumbraFile[], fileName?: string): AbortController

penumbra.getBlob(data: PenumbraFile[] | PenumbraFile | ReadableStream, type?: string): Promise<Blob>

penumbra.getTextOrURI(data: PenumbraFile[]): Promise<{ type: 'text'|'uri', data: string, mimetype: string }[]>

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; };

const files = [ { url: 'https://s3-us-west-2.amazonaws.com/your-bucket/tortoise.jpg.enc', filePrefix: '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();

if (penumbra.supported() > penumbra.supported.levels.none) { // penumbra is supported } /** penumbra.supported.levels - Penumbra user agent support levels */ enum PenumbraSupportLevel { /** Old browser where Penumbra does not work at all */ none = -0, /** Modern browser with full support */ full = 2, }