add docs

.gitignore

@@ -1,2 +1,3 @@
 .direnv
 node_modules
+result

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

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.

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)
+## Development
- 2. Edit `wrangler.toml`
+
-    - `account_id` should be your Cloudflare account's tag
+```bash
-    - `route` should be the subdomain this Worker will run on followed by `/*`
+npm install    # install dependencies
-    - `bucket_name` and `preview_bucket_name` should be the name of the R2 bucket you'll use
+npm test       # run vitest (uses miniflare locally)
- 3. Run `npm run login` to login to Wrangler
+npm run dev    # start wrangler dev server on localhost:8787
- 4. Run `npm run deploy`!
+```
- 5. Upload an `index.html` to your bucket if you want a landing page
+
+## 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