solid-crypt

Encrypt files in the browser before you store them in a Solid pod, and decrypt them after you read them back. The pod only ever sees ciphertext — plaintext never leaves the user's device.

npm install @solid-data/solid-crypt

New to Solid? The 30-second version

A Solid pod is a user-owned file store on the web. Your app reads and writes files in it over plain HTTP — GET to read, PUT to write — using an authenticated fetch (a normal fetch with the user's login attached).

The catch: by default those files are readable by whoever hosts the pod. solid-crypt fixes that. You wrap your authenticated fetch, and from then on every file is encrypted on the way out and decrypted on the way back. The server stores only scrambled bytes; the key stays in the browser.

How it works

1. You pick a directory in the pod to encrypt (e.g. .../notes/).
2. enableEncryption sets a passphrase and stores a small key file in that directory. Do this once.
3. openCrypt unlocks the directory with the passphrase and gives you a crypt.
4. cryptFetch(fetch, crypt) wraps your authenticated fetch. Use it exactly like fetch — it encrypts PUTs and decrypts GETs for you.

The passphrase derives the key; the server never sees either. Lose the passphrase and the data is gone — there is no recovery.

Quick start

import { isEncrypted, enableEncryption, openCrypt, cryptFetch } from "@solid-data/solid-crypt";

// `authFetch` = your authenticated Solid fetch (see the Next.js example below).
const dir = "https://alice.solidpod.example/notes";

// One-time: turn encryption on for this directory.
if (!(await isEncrypted({ dirUrl: dir, fetch: authFetch }))) {
  await enableEncryption({ dirUrl: dir, passphrase: "a strong passphrase", fetch: authFetch });
}

// Unlock, then wrap your fetch.
const crypt = await openCrypt({ dirUrl: dir, passphrase: "a strong passphrase", fetch: authFetch });
const cryptedFetch = cryptFetch(authFetch, crypt);

// Write encrypted, read decrypted — same shape as fetch.
await cryptedFetch(`${dir}/hello.txt`, { method: "PUT", body: "my secret note" });
const res = await cryptedFetch(`${dir}/hello.txt`);
console.log(await res.text()); // "my secret note"

Example: a Next.js app

This is a client component. Solid login and Web Crypto both run in the browser, so encryption code belongs in "use client" components.

"use client";

import { useState } from "react";
import { login, handleIncomingRedirect, fetch as solidFetch }
  from "@inrupt/solid-client-authn-browser";
import { enableEncryption, isEncrypted, openCrypt, cryptFetch } from "@solid-data/solid-crypt";

const DIR = "https://alice.solidpod.example/notes";
const PASSPHRASE_PROMPT = "Enter your encryption passphrase";

export default function Notes() {
  const [text, setText] = useState("");

  // 1. Log the user into their pod (redirects to their Solid provider).
  async function connect() {
    await handleIncomingRedirect();          // completes the login round-trip
    await login({
      oidcIssuer: "https://solidpod.example",
      redirectUrl: window.location.href,
      clientName: "My Notes App",
    });
  }

  // 2. Get an unlocked, encrypting fetch. `solidFetch` is the authenticated fetch.
  async function getCryptedFetch() {
    const passphrase = window.prompt(PASSPHRASE_PROMPT)!;
    if (!(await isEncrypted({ dirUrl: DIR, fetch: solidFetch }))) {
      await enableEncryption({ dirUrl: DIR, passphrase, fetch: solidFetch });
    }
    const crypt = await openCrypt({ dirUrl: DIR, passphrase, fetch: solidFetch });
    return cryptFetch(solidFetch, crypt);
  }

  // 3. ENCRYPT + SEND: the body is encrypted before it reaches the pod.
  async function save() {
    const cf = await getCryptedFetch();
    await cf(`${DIR}/note.txt`, { method: "PUT", body: text });
  }

  // 4. FETCH + DECRYPT: the response is decrypted before you read it.
  async function load() {
    const cf = await getCryptedFetch();
    const res = await cf(`${DIR}/note.txt`);
    setText(res.ok ? await res.text() : "");
  }

  return (
    <div>
      <button onClick={connect}>Connect pod</button>
      <textarea value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={save}>Save (encrypted)</button>
      <button onClick={load}>Load (decrypted)</button>
    </div>
  );
}

In a real app you'd unlock once and reuse the crypt for the session (prompting for the passphrase every save is just for clarity here), and call crypt.lock() on logout to drop the key from memory.

Working with binary files

cryptFetch handles any body — pass a Blob, ArrayBuffer, or Uint8Array:

await cryptedFetch(`${dir}/photo.jpg`, { method: "PUT", body: fileFromInput });
const bytes = new Uint8Array(await (await cryptedFetch(`${dir}/photo.jpg`)).arrayBuffer());

Or encrypt/decrypt bytes yourself without the fetch wrapper:

const ciphertext = await crypt.encrypt(bytes);
const plaintext  = await crypt.decrypt(ciphertext);

API

isEncrypted({ dirUrl, fetch }): Promise<boolean>
// Is encryption already set up for this directory? (cheap check)

enableEncryption({ dirUrl, passphrase, fetch }): Promise<void>
// Turn encryption on. Run once per directory. Won't overwrite an existing setup.

openCrypt({ dirUrl, passphrase, fetch }): Promise<Crypt>
// Unlock with the passphrase. Returns a `crypt` for this directory.

changePassphrase({ dirUrl, oldPassphrase, newPassphrase, fetch }): Promise<void>
// Change the passphrase. Existing encrypted files stay readable.

cryptFetch(fetch, crypt): typeof fetch
// Wrap an authenticated fetch so PUT bodies are encrypted and GET bodies decrypted.

interface Crypt {
  encrypt(bytes): Promise<Uint8Array>;
  decrypt(bytes): Promise<Uint8Array>;
  encryptString(s): Promise<Uint8Array>;
  decryptString(bytes): Promise<string>;
  lock(): void;   // forget the key
}

Errors: WrongPassphraseError, NotEncryptedError, CryptLockedError, KeystoreCorruptError, and EncryptedPatchError (you tried an HTTP PATCH — not supported on encrypted files; use a full PUT instead).

Good to know

• Each app/directory is separate. Different directories have different keys, so apps can't read each other's files. Point each app at its own directory.
• No PATCH. Encrypted files are replaced whole on each save, not patched.
• Lost passphrase = lost data. There is no recovery; tell your users.
• Runs where Web Crypto exists — browsers, and Node 20+ for tests/SSR.

Documentation

• docs/CLAUDE.md — integration guide for coding agents, including a Next.js Solid app recipe.
• docs/PLAN.md — design rationale and architecture decisions.

License

MIT