Docly Developers
Knowledge base Best practice Recommended

Turn off compression on API responses that carry a secret

In shortDocly compresses what your #/API/ endpoints return (brotli or gzip) once the response is 1 KB or more. If one response body carries a secret - an API key, a one-time code, a token you return in JSON - and also something the caller sent, the compressed size gives the secret away a few characters at a time (the BREACH attack). Set Cache-Control: no-store, no-transform on that response with docly.setHeader, and Docly sends it uncompressed. Only the body is compressed, so the session cookie from writeJwt is not affected.
Applies to API endpointsSecurityPublished sites
  1. What you'll see

    Nothing. The endpoint works, and the browser's network tab shows content-encoding: br on the response - which is what you want for nearly every endpoint. Nothing tells you that one of them returns a value a third party should not be able to work out.

  2. What's actually happening

    Compression removes repetition. When a guess the attacker placed in the request matches part of the secret in the same response, the two compress together and the response gets shorter:

    The caller sent ?label=The body containsCompressed size
    key=sk_7Q"label":"key=sk_7Q" ... "key":"sk_7Qm4..."shorter - the guess matches
    key=sk_7X"label":"key=sk_7X" ... "key":"sk_7Qm4..."one byte longer

    Someone who can make the visitor's browser send many such requests, and can see the size of the encrypted responses on the network, guesses the secret one character at a time. HTTPS does not hide the length. The attack is slow and needs both conditions in one response - which is why only those responses need the header.

    Only the body is compressed, never the headers. The session cookie writeJwt sets is a header, so it is not affected.

  3. What to do

    Set the header in the endpoint that returns the secret

    setHeader replaces the Cache-Control Docly sets, so include no-store too - a secret should not be cached either.

    // #/API/createKey.js - returns a new API key and echoes the label the caller sent
    export default (label) => {
        docly.setHeader("Cache-Control", "no-store, no-transform");
        return { label: label, key: createKey(label) };
    };

    Which responses need it

    The response body containsSet no-transform?
    A secret and something the caller sent (query, form, a header)Yes
    A secret, and nothing from the requestNot needed - harmless if set
    Neither - lists, pages, search resultsNo, keep the compression

    What Docly does for you

    Docly's own sign-in and token endpoints are never compressed, and the cookie from writeJwt is a header, which is never compressed. What your own endpoints write in the body is up to the endpoint.

Last reviewed 19 Nov 2026