From 8501f0ac3aada12a14ad67960525307ed3db9aa1 Mon Sep 17 00:00:00 2001
From: Abel Luck <abel@guardianproject.info>
Date: Thu, 26 Feb 2026 13:58:40 +0100
Subject: [PATCH] add docs

---
 .gitignore          |  1 +
 CHANGELOG.md        | 18 ++++++++++++++++++
 README.md           | 41 +++++++++++++++++++++++++++++++++++++++++
 nix-cache/README.md | 35 ++++++++++++++++++++++++-----------
 4 files changed, 84 insertions(+), 11 deletions(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
index 2362848..131dc80 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 .direnv
 node_modules
+result
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..ccd6232
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,18 @@
+# Changelog
+
+## [Unreleased]
+
+Changes yet to be released are documented here.
+
+## v0.1.0
+
+Initial release.
+
+- `nix-cache` Worker serving Nix binary cache from Cloudflare R2
+- JWT authentication via Keycloak OIDC (RS256, cached JWKS)
+- Group-based authorization (`nix-cache-users` claim required)
+- Bearer and Basic auth support (Basic for Nix netrc compatibility)
+- Range request support (single byte ranges)
+- Conditional request handling (etag, if-match, if-modified-since)
+- Edge caching via Cloudflare Cache API
+- Nix flake with checks (vitest in sandbox) and devShell
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8fbaab4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# cloudflare-workers
+
+Cloudflare Workers for Guardian Project infrastructure.
+
+Canonical Repository: https://guardianproject.dev/ops/cloudflare-workers
+
+## Workers
+
+- **[nix-cache](nix-cache/)** — Nix binary cache proxy backed by Cloudflare R2 with JWT authentication
+
+## Development
+
+```bash
+# enter dev environment
+nix develop
+
+# run all checks in the Nix sandbox
+nix flake check
+```
+
+## Maintenance
+
+This project is actively maintained by [Guardian Project](https://guardianproject.info).
+
+### Issues
+
+For bug reports and feature requests, please use the [Issues][issues] page.
+
+### Security
+
+For security-related issues, please contact us through our [security policy][sec].
+
+[issues]: https://guardianproject.dev/ops/cloudflare-workers/issues
+[sec]: https://guardianproject.info/contact/
+
+## License
+
+Copyright (c) 2026 Abel Luck <abel@guardianproject.info>
+
+This project is licensed under the GNU General Public License v3.0 or later -
+see the [LICENSE](LICENSE) file for details.
diff --git a/nix-cache/README.md b/nix-cache/README.md
index 5e752bc..315c5aa 100644
--- a/nix-cache/README.md
+++ b/nix-cache/README.md
@@ -1,14 +1,27 @@
-# Nix cache proxy for R2
+# nix-cache
 
-# Heavily based on https://github.com/piperswe/nix-cache
+Serves a Nix binary cache from Cloudflare R2 with JWT-based authentication.
+Only users with a valid Keycloak token and membership in the `nix-cache-users`
+group can read from the cache.
 
-## Setting up on your domain
+Nix clients authenticate via netrc (Basic auth), while other clients can use
+Bearer tokens directly. JWTs are verified locally using cached JWKS public keys.
 
- 1. Create an A record on the subdomain you want this Worker to run on which points to `192.0.2.1` (see https://community.cloudflare.com/t/a-record-name-for-worker/98841/2 for why)
- 2. Edit `wrangler.toml`
-    - `account_id` should be your Cloudflare account's tag
-    - `route` should be the subdomain this Worker will run on followed by `/*`
-    - `bucket_name` and `preview_bucket_name` should be the name of the R2 bucket you'll use
- 3. Run `npm run login` to login to Wrangler
- 4. Run `npm run deploy`!
- 5. Upload an `index.html` to your bucket if you want a landing page
\ No newline at end of file
+## Development
+
+```bash
+npm install    # install dependencies
+npm test       # run vitest (uses miniflare locally)
+npm run dev    # start wrangler dev server on localhost:8787
+```
+
+## Cloudflare Setup
+
+1. Create an A record on the subdomain you want this Worker to run on which
+   points to `192.0.2.1`
+2. Edit `wrangler.jsonc`:
+   - `route` should be the subdomain followed by `/*`
+   - `bucket_name` should be the name of the R2 bucket you'll use
+3. Run `npx wrangler login` to login to Wrangler
+4. Run `npm run deploy`
+5. Upload an `index.html` to your bucket if you want a landing page