Add a security section to the docs (#409)

Author: woodruffw

Makefile

@@ -19,8 +19,7 @@ format:
 
 doc: $(VENV)/bin/sphinx-build
 	. $(ACTIVATE) && \
-		cd docs && \
-		make html
+		make -C docs html
 
 clean: clean-build clean-pyc clean-test
 

docs/hacking.rst

@@ -0,0 +1,42 @@
+=======================
+Hacking on CacheControl
+=======================
+
+CacheControl is a pure Python library. We use uv_ to manage its development.
+
+Linting and Formatting
+======================
+
+We use Ruff_ and mypy_ for linting/formatting and type checking. You can run
+them with:
+
+.. code-block:: console
+
+  $ make lint
+  $ make format
+
+Tests
+=====
+
+The tests are all in ``cachecontrol/tests`` and are runnable by ``py.test``.
+
+You can use ``make test`` to run the tests:
+
+.. code-block:: console
+
+  $ make test
+
+Documentation
+=============
+
+The documentation is built with Sphinx_. You can build it by running
+``make doc``:
+
+.. code-block:: console
+
+  $ make doc
+
+.. _uv: https://docs.astral.sh/uv/
+.. _Ruff: https://docs.astral.sh/ruff/
+.. _mypy: https://mypy-lang.org/
+.. _Sphinx: https://www.sphinx-doc.org/

docs/index.rst

@@ -34,6 +34,10 @@ requirements. See :doc:`storage` for more info.
 Quick Start
 ===========
 
+.. important::
+
+    You **must** read the :doc:`security` page before using CacheControl.
+
 For the impatient, here is how to get started using CacheControl:
 
 .. code-block:: python
@@ -52,25 +56,11 @@ For the impatient, here is how to get started using CacheControl:
 This uses a thread-safe in-memory dictionary for storage.
 
 
-Tests
-=====
-
-The tests are all in ``cachecontrol/tests`` and are runnable by ``py.test``.
-
-
 Disclaimers
 ===========
 
-CacheControl is relatively new and might have bugs. I have made an
-effort to faithfully port the tests from httplib2 to CacheControl, but
-there is a decent chance that I've missed something. Please file bugs
-if you find any issues!
-
-With that in mind, CacheControl has been used successfully in
-production environments, replacing httplib2's usage.
-
-If you give it a try, please let me know of any issues.
-
+HTTP caching comes with important security considerations. Please
+read the :doc:`security` page for more information.
 
 .. _httplib2: https://github.com/httplib2/httplib2
 .. _requests: https://requests.readthedocs.io/en/latest/
@@ -89,12 +79,14 @@ Contents
    etags
    custom_heuristics
    tips
+   security
 
 .. toctree::
    :hidden:
    :caption: Development
    :maxdepth: 2
 
+   hacking
    release_notes
    GitHub <https://github.com/psf/cachecontrol>
    PyPI <https://pypi.org/project/cachecontrol>

docs/security.rst

@@ -0,0 +1,77 @@
+..
+  SPDX-FileCopyrightText: SPDX-FileCopyrightText: 2026 William Woodruff
+
+  SPDX-License-Identifier: Apache-2.0
+
+=======================
+Security Considerations
+=======================
+
+HTTP caching is a security-sensitive operation. Improper caching and use
+of cached data can introduce security vulnerabilities into otherwise secure
+applications.
+
+This page will help you decide if you *can* use CacheControl securely
+in your application, and if so, how to do so.
+
+CacheControl's security model
+=============================
+
+CacheControl's security model is based on the following assumptions:
+
+* CacheControl provides a **private** cache. This means that both shared
+  *and* private responses are cached, and the cache is assumed to be accessible only
+  to a single logical user. You **cannot** use CacheControl securely
+  in a multi-user environment where cached data may be shared between
+  different logical users. **Do not** use CacheControl for this;
+  it **will** end badly for you.
+
+* You **must** treat cached data as potentially sensitive. CacheControl
+  does not natively encrypt or otherwise protect cached data. If an attacker
+  can read your cache, they can read all cached responses. You must
+  ensure that your cache storage is protected appropriately for the
+  sensitivity of the data you are caching. Another framing of this is that
+  CacheControl **assumes** the security of your cache storage, similar to
+  how browsers assume the security of your local machine for the purpose
+  of storing history, cookies, and cached data.
+
+* You **must** trust the origins (i.e., servers)
+  you are communicating with. A malicious origin can always send
+  you malicious responses, which in the context of caching can mean
+  sending you cacheable responses that you don't expect, spamming you
+  with cache entries, and so on. In practice, this means that you must
+  also trust your transport layer; if you use HTTP, any
+  adversary on your network path can tamper with your connected
+  origin's responses, and CacheControl has no way to protect you from that.
+
+Conversely, here are some assumptions that CacheControl **does** attempt
+to enforce; violating these assumptions would be a security vulnerability in
+CacheControl itself:
+
+* An attacker should not be able to trick CacheControl into caching across
+  origins. For example, an attacker who controls ``evil.example.com``
+  should not be able to trick CacheControl into caching responses for
+  ``bank.example.com``.
+
+* An attacker should not be able to trick CacheControl into serving cached
+  responses to requests that would not normally receive those cached
+  responses. For example, an attacker should not be able to trick
+  CacheControl into serving a cached response to an unauthenticated
+  request when the cached response was originally received in response
+  to an authenticated request.
+
+Reporting security issues
+=========================
+
+.. important::
+
+    Please make sure to read the security model above before reporting
+    issues. Reports that don't take the security model into account will
+    be considered invalid.
+
+We take security reports very seriously, and aim to address them as quickly
+as possible.
+
+Please use GitHub's `security advisory process`_ to report security issues.
+
+.. _security advisory process: https://github.com/psf/cachecontrol/security/advisories/new

docs/usage.rst

@@ -7,6 +7,10 @@
  Using CacheControl
 ====================
 
+.. important::
+
+    You **must** read the :doc:`security` page before using CacheControl.
+
 CacheControl assumes you are using a `requests.Session` for your
 requests. If you are making ad-hoc requests using `requests.get` then
 you probably are not terribly concerned about caching.