Encryption

Every file is encrypted in the browser before it is uploaded to the account, and your app never handles a key. This page covers the one state an app does see, locked, and the errors that come with a key that changed.

Encryption is always on: there is no unencrypted account and no setting that turns it off. readFile and writeFile work unchanged, because the encryption happens in the broker frame, the hidden fkn.app iframe the library mounts, see how it works. The broker is the connection your app holds into FKN through that frame. The account is the FKN identity a person carries between sites, and the service is the FKN server that keeps its files.

Locked

Locked means the broker holds no usable key for this app and account. A key reaches the broker only from a first-party fkn.app window, the connect or unlock popup. The broker keeps it in its own storage partition until that record expires.

A refused read or write does not fail at once. It raises the broker’s unlock card inside the call and waits. Concurrent locked calls share the one card. StorageLockedError arrives only after the card was dismissed, could not be shown, or delivered no usable key:

app.ts

import { promises as cloud, StorageLockedError, unlock } from '@fkn/lib/cloud/fs'

const readCatalog = async (attempt = 0): Promise<string> => {
  try {
    return String(await cloud.readFile('library/catalog.json', 'utf8')) // '{"items":[]}', after the unlock card when locked
  } catch (error) {
    if (!(error instanceof StorageLockedError)) throw error // absence, a changed key and unreachable pass through
    if (attempt > 0 || !(await unlock())) throw error
    return readCatalog(attempt + 1) // once, a second dismissal is not retried
  }
}

const catalog = await readCatalog()

The read retries once and rethrows everything else. Locked is unavailable, not empty, so StorageLockedError and StorageNotFoundError are two classes, see two errors keep a class.

Every cloud.fs call on this page waits for the broker with no deadline, so in a worker nobody relayed none of them returns. The one bounded wait is the availability probe behind the hybrid fs, see connection and lifecycle.

unlock()

unlock() asks for the key without a read or a write. It answers false with no account connected and true when a usable key is already held. Otherwise it raises the card and answers what the card answered:

app.ts

await unlock() // true once unlocked, false after a dismissal or with nothing connected

true means the broker now holds a key, not that the next write will accept it, see key epochs.

The card, Storage locked. Click to unlock., never asks for a secret. Its Unlock button opens a first-party fkn.app window for the password or passkey, which this site never sees.

Two connections never unlock through unlock(): one the service has stopped accepting, where the card comes back after every popup, and one made before FKN began delivering keys, since a key crosses only from a first-party window. Disconnect and connect once to fix either, see disconnecting.

The broker’s availability probe tells a refused connection from a locked account. It is availability() on the cloud.fs behind apiPromise from @fkn/lib/api, and it answers 'disconnected' once the service has refused the connection and 'connected' while the account is merely locked, see the broker’s vocabulary. A broker older than that resolver carries only available(), so check that availability is a function before you call it.

encryption()

encryption() reports the state without raising a card:

app.ts

const { unlocked, enrolled, keyEpoch } = await encryption() // never shows a card
if (enrolled && !unlocked) await unlock() // the account has a key this browser lacks, so ask now
keyEpoch // the account's current key epoch, unix seconds at enrolment, or null

The three fields are the EncryptionStatus on TypeScript, { unlocked, enrolled, keyEpoch: number | null }, which the broker’s own vocabulary calls EncryptionState. They come from two places:

Field	What it holds
unlocked	this browser holds a usable key for this app and account, the broker’s own answer
enrolled	the service reports a key for the account, keyEpoch != null
keyEpoch	the account’s current key epoch from the service, unix seconds at enrolment, or null

Two fields are the service’s answer about the account and one is this browser’s answer about itself, so they can disagree. When the service cannot be reached the call still resolves with enrolled: false and keyEpoch: null beside whatever unlocked says, so { unlocked: true, enrolled: false } is what an outage looks like.

Never read enrolled: false as “this account has no key”. An app that gates writes or shows an enrol prompt on it does so at every outage. The account does hold no key between a settled key reset and its next enrolment, see key epochs.

On the hybrid fs

fs reaches the account through mount() and the read rule, and through pull() and readFileSealed(). On a locked account await fs.mount() is where the card appears. It reads every listed file in turn, and each account read raises the card and blocks on the user. Each dismissal costs one more card for the next path this device holds no copy of.

A path whose read failed stays present but unreadable. existsSync is true and readdirSync lists it from the root, while readFileSync, statSync, lstatSync, writeFileSync, appendFileSync and renameSync throw with code FKN_E2E_LOCKED. Nothing creates its parent directory, so readdirSync on that parent throws ENOENT unless a readable file shares it:

app.ts

await fs.mount() // on a locked account, the unlock card, one more per unread file after a dismissal

fs.readdirSync('.') // ['library'], an unread path is still listed
fs.readdirSync('library') // throws ENOENT, an unread path gets no directory
fs.existsSync('library/catalog.json') // true

try {
  fs.readFileSync('library/catalog.json', 'utf8')
} catch (error) {
  const { code, message } = error as NodeJS.ErrnoException
  code // 'FKN_E2E_LOCKED'
  message // 'storage: library/catalog.json exists but could not be read, retry once its scope is available'
}

The message is storage: <path> exists but could not be read, retry once its scope is available. The code means listed in the account and unreadable here. fs marks a path unreadable on any failed read, whether the account is locked, the file was encrypted under a reset key, its integrity check failed or the service answered an error, and it cannot tell the four apart.

A path still unreadable after an unlock is one of the other three, and only a read that reaches the account names the cause: cloud.fs, pull() and readFileSealed() reject with StorageLockedError while locked, and otherwise with the sentences under the messages.

fs refuses a write to an unreadable path rather than queueing one. Deleting it needs no key. A later callback or promise call re-runs that read after 5 seconds, so a locked file appears on its own after an unlock. adopt() and the drain, the background process that replicates queued writes, stop at the first locked failure and keep the work queued, see adopting files written before sign-in.

Only ENOENT means empty, so the readOr helper on error codes rethrows this code. Its locked branch calls unlock() and then remount(), and the fresh hydrate reads the path:

app.ts

const readOr = async (path: string, fallback: string): Promise<string> => {
  try {
    return String(fs.readFileSync(path, 'utf8'))
  } catch (error) {
    const { code } = error as NodeJS.ErrnoException
    if (code === 'ENOENT') return fallback
    if (code === 'FKN_E2E_LOCKED' && await unlock()) {
      await fs.remount() // a fresh hydrate, which reads the path now that a key is held
      return String(fs.readFileSync(path, 'utf8')) // throws again when the cause was not the lock
    }
    throw error // a dismissed card, or a path unreadable for one of the other three reasons
  }
}

await readOr('library/settings.json', '{}') // '{}' until the app writes one, the file after an unlock

We recommend calling encryption() first, then unlock() on your own terms, and mounting after, so the card does not appear mid-load.

Key epochs

keyEpoch is the account’s key epoch, the unix time in seconds when the key was enrolled. A key generation is that epoch paired with a fingerprint of the key, since a reset and a new enrolment in the same second repeat the epoch. Every stored file records the generation it was encrypted under. So keyEpoch alone is for display and coarse comparison, never a key’s identity.

A write encrypts under the account’s current generation, read fresh from the service, and its commit names it. A commit naming a generation the account has since left is refused with Superseded key. When the held key is behind, the broker raises the unlock card before it can encrypt again:

app.ts

const saveCatalog = async (catalog: string, attempt = 0): Promise<void> => {
  try {
    await cloud.writeFile('library/catalog.json', catalog) // encrypted under the current generation and committed
  } catch (error) {
    const message = error instanceof Error ? error.message : ''
    if (message.startsWith('Superseded key') && attempt === 0) return saveCatalog(catalog, attempt + 1) // encrypts again, after the card when the held key is behind
    throw error
  }
}

await saveCatalog(JSON.stringify({ items: [] }))

The block retries Superseded key once, the one write refusal here worth a retry. A read accepts any generation the broker still holds.

A generation changes when the user resets the account’s key and enrols again on the Security page of fkn.app. Between the two the account holds no key at all, so encryption() answers enrolled: false and FKN refuses every write rather than storing anything readable.

The old key is gone everywhere, so every file encrypted before the reset answers fkn:e2e-stale-epoch from then on. The only way back is an encrypted export taken before the reset. An app has nothing to retry: report it, and never write a guess over the file.

The messages

A hop out of the broker keeps an Error’s name, message, stack and cause only, see what crosses a realm, so the broker throws fixed sentences rather than codes. The library matches the locked one and re-mints StorageLockedError on your side. @fkn/lib/messages exports all five names below. The first three are the messages themselves, matched by prefix, and the last two are codes you read off error.code:

Constant	Value	What it marks
E2E_LOCKED_MESSAGE	fkn:e2e-locked	the locked signal, re-minted as StorageLockedError before you see it
E2E_STALE_EPOCH_MESSAGE	fkn:e2e-stale-epoch: this file is encrypted under a previous key you reset	encrypted under a key a reset removed
E2E_INTEGRITY_MESSAGE	fkn:e2e-integrity: stored data failed its integrity check	no seal marker, the field naming the envelope layout, an unknown one, a scope or connection that is not this caller’s own, or an envelope whose authentication tag does not verify
STORAGE_NOT_FOUND	FKN_STORAGE_NOT_FOUND	an error code: no object at that path, what isNotFound tests
STORAGE_UNREACHABLE	FKN_API_UNREACHABLE	a code set beside storage: api unreachable that is not guaranteed to arrive

Test the locked case with StorageLockedError and absence with isNotFound, on reads and writes only, since the re-mint does not run for unlink, see unlink() skips the re-mint. Match stale-epoch, integrity and unreachable by message prefix:

app.ts

const cached = async (): Promise<Uint8Array | null> => {
  const data = await opfs.promises.readFile('backup/library.bin').catch(() => null) // this device's last good copy, or nothing
  if (data === null) return null
  return data instanceof Uint8Array ? data : new TextEncoder().encode(data)
}

const loadBackup = async (attempt = 0): Promise<Uint8Array | null> => {
  try {
    const data = await cloud.readFile('backup/library.bin')
    return data instanceof Uint8Array ? data : new TextEncoder().encode(data)
  } catch (error) {
    if (isNotFound(error)) return null // nothing stored yet, safe to write a first backup
    if (error instanceof StorageLockedError) {
      if (attempt === 0 && await unlock()) return loadBackup(attempt + 1) // once, after the user unlocked
      throw error
    }
    const message = error instanceof Error ? error.message : ''
    if (message.startsWith(E2E_STALE_EPOCH_MESSAGE)) throw error // a reset key, nothing to retry
    if (message.startsWith(E2E_INTEGRITY_MESSAGE)) throw error // unreadable, never overwrite
    if (message.startsWith('storage: api unreachable')) return cached() // keep this device's copy, retry later
    throw error
  }
}

const backup = await loadBackup() // the bytes, null with nothing stored, or cached while unreachable

isNotFound and instanceof StorageLockedError come first, because those two classes are minted on your side and keep their code. The order to test a mixed handler in is on handling errors.

What the service sees

The service stores the encrypted bytes and, beside them, the five fields of FileEntry: path, size, contentType, updatedAt, and the seal marker in encryption, the field that names the envelope layout and nothing else. cloud.fs.quota() meters usedBytes and objects against their caps, see limits and timeouts.

OPFS, the local half of fs and all of opfs, is not encrypted by the platform and belongs to the origin, not the account, see scope and paths.

Errors you might see

The five rows an app meets most:

Message	What happened
fkn:e2e-locked	Arrives as StorageLockedError. Call unlock() and retry once.
fkn:e2e-stale-epoch: this file is encrypted under a previous key you reset	A key a reset removed. Never retry or overwrite.
fkn:e2e-integrity: stored data failed its integrity check	The seal marker, scope, connection or authentication tag does not verify. Never overwrite.
This account has no encryption keys yet	An account holding no key, between a settled reset and the next enrolment.
This account stores sealed objects	A write with no seal marker, which the broker never sends.

Superseded key and the hybrid’s own sentence are above, and every other message is on every error.

See also

• storage
• account and quota
• handling errors
• limits and timeouts
• TypeScript