Feature Proposal: Encrypted Disk Cache

[o-nnerb]

Overview

DataCache's disk tier stores every entry fully in plaintext today — both response.record (JSON metadata, including the original response's headers) and data.record (the raw body), at a predictable path (<tmp>/com.request-dl-nio.Swift.Cache/<suiteName>), with a merely-obfuscated (reversible base64) key. This proposes optional, consumer-keyed encryption for the disk tier.

Does this make sense? Depends what's being cached

A response cache is a copy of something already legitimately received over TLS — for public, non-sensitive content, encrypting it at rest is pure cost with no benefit. For anything carrying PII, session/auth-adjacent data, or regulated content, local-storage compromise (malware, a misconfigured sandbox boundary, physical access to an unlocked device) is a real, distinct threat from transport security. So this is opt-in, not on-by-default — the opposite default from the automatic cookie jar (#251), since there's a genuine performance cost and no universal benefit.

Key management, not encryption, is the hard part — and it's not RequestDL's job to own

AES-GCM via swift-crypto is a solved problem. Secure key storage is a deeply platform-specific one (Keychain + accessibility classes + biometric gating on Darwin, nothing equivalent through FoundationEssentials on Linux) that a networking library shouldn't try to own — same reasoning that kept Public Suffix List data and RFC 7616 hashing out of RequestDL's own responsibility in earlier proposals this session. So the key is consumer-supplied: the app decides how to store it (Keychain, a KMS, whatever fits its own threat model), RequestDL just uses it.

API

.cache(memoryCapacity: ..., diskCapacity: ..., encryptionKey: Cache.EncryptionKey)

Cache.EncryptionKey wraps Crypto.SymmetricKey rather than exposing it directly — matching this codebase's existing convention of never leaking an external type as public API (ResponseHead, HTTPHeaders both wrap rather than re-export their NIO/AsyncHTTPClient equivalents). Threads through the same path capacity already takes: CacheConfigurationProperty → make.cacheConfiguration.encryptionKey (new field on Internals.CacheConfiguration) → .build(logger:) → DataCache(url:logger:encryptionKey:).

This is a new direct dependency, not just a transitive one. swift-crypto is already in Package.resolved transitively (via the TLS chain), but RequestDL's own Package.swift doesn't declare it — this adds .product(name: "Crypto", package: "swift-crypto") to the main target, a real manifest change, unlike the PSL/SOCKS proposals which stayed consumer-side or purely transitive.

Where it hooks in

DiskStorage.writeAndClose(_:to:) and readResponseData(at:) (DiskStorage.swift:382/188) are the two places raw bytes cross the filesystem boundary. Encryption wraps right there — encrypt before handle.write, decrypt after handle.readToEnd — leaving capacity tracking, eviction, and key hashing above it untouched. Both response.record and data.record get encrypted: CachedResponse embeds Internals.ResponseHead, which carries the original response's headers (Set-Cookie, an echoed auth header, anything) — the metadata file is just as sensitive as the body.

Scope: whole-blob authenticated encryption, not seekable/chunked

AES-GCM authenticates the entire ciphertext as one unit — no decrypting from an arbitrary offset the way plaintext pread/pwrite random access (Internals.FileStreamBuffer) currently allows. Since cached entries aren't served via partial/range reads today (both files are read start-to-finish on a cache hit, never sliced), whole-blob encryption is sufficient for v1. Chunked/independently-decryptable-block encryption would only be worth the real added complexity if partial cached-response reads become a need later.

Nonce handling is close to free: AES.GCM.SealedBox.combined already bundles a fresh random nonce with the ciphertext and auth tag in one blob — write sealedBox.combined, reconstruct with AES.GCM.SealedBox(combined:) on read.

Failure handling

A decrypt failure (wrong/rotated key, corrupted or tampered file) is a cache miss — nil, not a crash — consistent with the existing try?-based fault tolerance already throughout DiskStorage.

Key rotation: freely replaceable, not locked

DataCache.Storage is shared and keyed by directory URL. The key must not be locked at first creation the way capacity-lowering is barred (Internals.Log.loweringCacheCapacityOnInitNotPermitted) — that precedent doesn't transfer, because a key is a rotating secret by design, not a structural resource limit. Supplying a new key just replaces it going forward on the shared storage. Reads under the new key against old-key-encrypted entries fail → become misses (per the failure handling above) → the next write for that entry re-encrypts with the current key. The cache self-heals to the new key organically, one entry at a time, through ordinary use — no special-case code needed.

One real nuance: if a rotation happens because the old key may be compromised, lazy replacement alone doesn't fully address that — old entries stay on disk, still decryptable by anyone holding the old key, until naturally evicted. RequestDL doesn't bake automatic clearing into supplying a new key (not every rotation is compromise-driven, and unconditionally wiping the cache on every key change means a thundering-herd refill against the origin every time). Instead: DataCache.removeAll() already exists as public API today — for a suspected-compromise rotation, the app calls it deliberately alongside supplying the new key. RequestDL provides the primitive; the app makes the call it's actually in a position to make.

Out of scope (v1)

• MemoryStorage stays unencrypted. Exfiltrating memory-resident data needs a live process dump or swapped pages — a narrower, harder threat than plaintext files sitting indefinitely in a predictable temp directory. Encrypting every in-memory cache hit would be real CPU cost against a threat most apps aren't defending against.
• Chunked/seekable encryption — see above.
• Any built-in key storage/derivation (Keychain integration, KMS helpers) — deliberately consumer-supplied only.

Milestone: 4.2.0

[adamantmm]

Opt-in plus a consumer-supplied key is the right split. Looking at the current DiskStorage, both readResponseData and writeAndClose already do whole-file I/O (readToEnd / write(contentsOf:)), so AES-GCM SealedBox.combined slots in at those two sites without fighting a seekable buffer.

One detail for freeSpace: it accounts with entry.size. After encryption the on-disk blob is plaintext + nonce + tag, so if size is measured from the original body you'll under-count and evict too late. Measure the ciphertext you actually wrote.

Decrypt failure as a cache miss matches the existing try? path. I would not retry decrypt inside retryingUntilSuccess — a wrong or rotated key should miss once, not spin.

[o-nnerb]

Thanks @adamantmm for the review — the size-accounting catch is right, though worth pinning down exactly where it bites. Record.size (freeSpace's own eviction accounting) stats the actual file on disk, so it already reflects whatever was written, ciphertext included — no fix needed there. The real gap is upstream of it: allocateBuffer's admission guard (writableBytes = response.count + contentLength) and updateCached's spaceChange both compute from plaintext sizes, so they'll under-book by the GCM overhead (nonce + tag) per file. Given freeSpace's own doc comment already treats an undercounted knownUsage as a bounded, self-correcting overshoot (never data loss), this is minor — but the proposal should say so explicitly rather than leave it implied.

On the decrypt-retry point: already true by construction. retryingUntilSuccess in DiskStorage.readResponseData only wraps openFile; decrypt would sit after readToEnd, outside the loop. Worth stating in the proposal so it's not re-litigated during implementation.

A bigger gap: the two named hook points don't cover data.record

DiskStorage.writeAndClose(_:to:) and readResponseData(at:) only ever touch response.record (the JSON head/metadata). data.record — the actual response body, arguably the more sensitive of the two files — never passes through either function. It's written and read via Internals.FileBuffer(record.dataURL), backed by Internals.FileStreamBuffer, a generic streaming primitive shared across the networking stack, not cache-specific.

More importantly, the write side isn't whole-blob at all: Internals.CacheControl.cacheIfNeeded streams the response body straight from the network into that buffer chunk-by-chunk as it arrives (for try await buffer in asyncBuffers { await cacheBuffer.writeBuffer(buffer) }), specifically to avoid holding the full body in memory. There's no single write to wrap encryption around — which breaks the "whole-blob AES-GCM, encrypt before handle.write" model for this file. As scoped, the proposal would only encrypt the metadata file and leave the actual response payload in plaintext.

Proposed fix: chunked encryption on write, lazy chunked decrypt on read

Accumulate plaintext in memory up to a fixed chunk size (a few MB), seal each chunk independently with AES-GCM, and write chunks sequentially to data.record. On read, decrypt lazily chunk-by-chunk as the (already-sequential) consumer advances. This keeps peak memory at O(chunk size) instead of O(response size) — preserving the property the current streaming design exists for — and matches the actual read pattern (sequential, never sliced), so no real random-access decryption is needed for v1.

This is essentially the STREAM construction (same idea behind libsodium's secretstream and the age format), and it's worth borrowing its two safeguards rather than reinventing them:

• Counter-derived nonce, not random per chunk: one random base nonce per cache entry, chunk nonce derived from a monotonic index. Removes any need to reason about cross-chunk collision.
• AAD binding chunk index + a last-chunk flag: without it, a chunk-level GCM tag check alone doesn't catch chunk reordering or trailing-chunk truncation — each remaining chunk still verifies fine on its own. Whole-blob encryption got this for free; chunking has to close it explicitly.

Architecturally, this shouldn't live inside DiskStorage's two named functions — it belongs as a new StreamBuffer-conforming wrapper around Internals.FileStreamBuffer (mirroring how Internals.FileBuffer is already Buffer<FileStreamBuffer>), swapped in by DiskStorage.allocateBuffer/subscript only when encryptionKey is set. That keeps DataCache/CacheControl unaware of the change, the same way fileProtection is threaded today.

Net effect on the doc: "Scope: whole-blob authenticated encryption, not seekable/chunked" should become "chunked, sequential-only" — not fully seekable (no current need for that), but no longer whole-blob either.

[o-nnerb]

Implemented and merged in #309, following the design revised through this discussion — chunked STREAM-construction AES-GCM for data.record (counter-derived nonces, AAD binding chunk index + finality) instead of the whole-blob scheme originally proposed, since the response body is written incrementally and never touches the two functions that proposal named. response.record stays whole-blob AES-GCM as originally proposed. Thanks again @adamantmm for the review.

Closing as resolved.