Examples

Streaming Encryption & Decryption

The streaming API accepts and returns standard ReadableStream<Uint8Array> objects. This makes it composable with any browser streaming source or sink — file inputs, fetch() uploads, Service Worker downloads, or the upcoming File System Access API.

These examples use StreamSaver.js to stream encrypted bytes directly to a file download without buffering the entire file in memory.

Future: Once showSaveFilePicker() ships in Safari and Firefox, StreamSaver can be replaced with the native File System Access API (see last example).

Error handling

If the auth tag check fails at the end of the stream (data was tampered with), the plaintextStream will error. When using pipeTo(), this automatically aborts the destination writable. Wrap the pipeTo() call to catch it:

Ts

try {
    await plaintextStream.pipeTo(destination);
} catch (err) {
    if (err.message.includes("auth tag")) {
        // Document was tampered with — partial plaintext was already
        // written to the destination. Delete or discard the output.
    }
    throw err;
}

Important: Because streaming decryption emits plaintext before the final auth tag is verified, a tampered document will produce partial output before the error. Applications should treat incomplete output as untrusted and clean it up on failure.

Encrypt a file and download the result

Ts

import streamSaver from "streamsaver";
import * as ironweb from "@ironcorelabs/ironweb";

async function encryptFileToDownload(file: File, options?: DocumentCreateOptions) {
    const {encryptedStream, documentID} = await ironweb.document.encryptStream(
        file.stream(),
        options
    );

    const fileStream = streamSaver.createWriteStream(`${file.name}.iron`);
    await encryptedStream.pipeTo(fileStream);

    return documentID;
}

Decrypt a file and download the result

Ts

import streamSaver from "streamsaver";
import * as ironweb from "@ironcorelabs/ironweb";

async function decryptFileToDownload(documentID: string, file: File) {
    const {plaintextStream} = await ironweb.document.decryptStream(
        documentID,
        file.stream()
    );

    const outputName = file.name.replace(/\.iron$/, "");
    const fileStream = streamSaver.createWriteStream(outputName);
    await plaintextStream.pipeTo(fileStream);
}

Encrypt a file and upload to a server

Streams encrypted bytes directly into a fetch() request body. The file is never fully buffered in memory on either side.

Note: Streaming request bodies require duplex: "half" and a server that accepts chunked Transfer-Encoding. Content-Length cannot be set because the encrypted size (ciphertext + 16-byte auth tag) isn’t known until the stream finishes.

Ts

import * as ironweb from "@ironcorelabs/ironweb";

async function encryptFileAndUpload(
    file: File,
    uploadUrl: string,
    options?: DocumentCreateOptions
) {
    const {encryptedStream, documentID} = await ironweb.document.encryptStream(
        file.stream(),
        options
    );

    await fetch(uploadUrl, {
        method: "PUT",
        body: encryptedStream,
        headers: {"Content-Type": "application/octet-stream"},
        duplex: "half",
    });

    return documentID;
}

Download an encrypted file from a server and decrypt

Ts

import streamSaver from "streamsaver";
import * as ironweb from "@ironcorelabs/ironweb";

async function downloadAndDecrypt(documentID: string, url: string, filename: string) {
    const response = await fetch(url);
    if (!response.ok || !response.body) {
        throw new Error(`Failed to fetch: ${response.status}`);
    }

    const {plaintextStream} = await ironweb.document.decryptStream(
        documentID,
        response.body
    );

    const fileStream = streamSaver.createWriteStream(filename);
    await plaintextStream.pipeTo(fileStream);
}

Using the File System Access API (no StreamSaver)

Chrome, Edge, and Opera already support showSaveFilePicker(). When Safari and Firefox ship it, this becomes the preferred approach — no Service Worker required.

Ts

import * as ironweb from "@ironcorelabs/ironweb";

async function decryptToFileSystemAccess(documentID: string, encryptedFile: File) {
    const {plaintextStream} = await ironweb.document.decryptStream(
        documentID,
        encryptedFile.stream()
    );

    const handle = await showSaveFilePicker({
        suggestedName: encryptedFile.name.replace(/\.iron$/, ""),
    });
    const writable = await handle.createWritable();
    await plaintextStream.pipeTo(writable);
}