Document the auth UI, encrypted-URL routes, q/fit parameters, and the undocumented config keys #75

New Issue

clawbot · 2026-08-09T03:47:47+02:00

clawbot commented

2026-08-09 03:47:47 +02:00

Verified against main at 61f42e6. Covers the "documentation: configuration options / API endpoints" items in TODO.md.

README.md:51-60 documents exactly one route, /v1/image/.... internal/server/routes.go:48-60 registers considerably more, none of it documented anywhere:

GET / and POST / — signing-key login form (internal/handlers/auth.go:16-67)
GET /logout
POST /generate — encrypted-URL generator
GET /v1/e/{token}/* — encrypted image URLs (internal/handlers/imageenc.go)
GET /robots.txt, GET /.well-known/healthcheck.json, GET /static/*, GET /metrics

The entire encrypted-URL scheme — the encurl, seal, and session packages, built on CBOR + NaCl secretbox + HKDF — is undocumented. It is a major user-facing feature (an operator-facing web UI for minting time-limited URLs) that a reader of the README would not know exists.

Also undocumented:

q and fit query parameters (internal/handlers/image.go:50-63): q is 1-100, fit is one of cover|contain|fill|inside|outside (internal/imgcache/imgcache.go:53-60). Both affect the cache key. Note their interaction with signing is a separate security issue.
Config keys db_url and env (internal/config/config.go:119-130,220-223). env is a smartconfig feature providing env-var injection and env:VARNAME value interpolation — which partly satisfies the "environment variable overrides" item in TODO.md, and nobody can use it because it is written down nowhere.
PIXA_CONFIG_PATH and the config search path (config.go:340,352-359): /etc/pixa/config.yml, ~/.config/pixa/config.yml, ./config.yml, plus .yaml variants. README mentions only --config.
scripts/manual-test.sh, which sits alongside the documented script/ entrypoints and is not mentioned.

Definition of done

A README "Routes" section covering every registered route, with method, purpose, auth requirement, and response codes.
A section describing the encrypted-URL flow end to end: what it is for, how a token is generated, how TTL works, and what an expired token returns (410).
q and fit documented with their valid ranges and their effect on caching.
db_url, env, and PIXA_CONFIG_PATH documented, plus the config file search order.
config.example.yml lists every key the code accepts, with defaults — making README.md:119's "all options with defaults" claim true. (Coordinate with the issue adding the four missing README keys; whichever lands second completes the set.)
scripts/manual-test.sh mentioned in the Entrypoints section, or moved/removed.
make fmt run and the formatted markdown committed; make check green.

Process note

Docs-only if it stays confined to README.md and config.example.yml — in which case it skips adversarial review per repo policy. If it turns out a key needs code changes to be documentable, split that into its own issue rather than mixing.

Verified against `main` at `61f42e6`. Covers the "documentation: configuration options / API endpoints" items in `TODO.md`. `README.md:51-60` documents exactly one route, `/v1/image/...`. `internal/server/routes.go:48-60` registers considerably more, none of it documented anywhere: - `GET /` and `POST /` — signing-key login form (`internal/handlers/auth.go:16-67`) - `GET /logout` - `POST /generate` — encrypted-URL generator - `GET /v1/e/{token}/*` — encrypted image URLs (`internal/handlers/imageenc.go`) - `GET /robots.txt`, `GET /.well-known/healthcheck.json`, `GET /static/*`, `GET /metrics` The entire encrypted-URL scheme — the `encurl`, `seal`, and `session` packages, built on CBOR + NaCl secretbox + HKDF — is undocumented. It is a major user-facing feature (an operator-facing web UI for minting time-limited URLs) that a reader of the README would not know exists. Also undocumented: - **`q` and `fit` query parameters** (`internal/handlers/image.go:50-63`): `q` is 1-100, `fit` is one of `cover|contain|fill|inside|outside` (`internal/imgcache/imgcache.go:53-60`). Both affect the cache key. Note their interaction with signing is a separate security issue. - **Config keys `db_url` and `env`** (`internal/config/config.go:119-130,220-223`). `env` is a smartconfig feature providing env-var injection and `env:VARNAME` value interpolation — which partly satisfies the "environment variable overrides" item in `TODO.md`, and nobody can use it because it is written down nowhere. - **`PIXA_CONFIG_PATH`** and the config search path (`config.go:340,352-359`): `/etc/pixa/config.yml`, `~/.config/pixa/config.yml`, `./config.yml`, plus `.yaml` variants. README mentions only `--config`. - **`scripts/manual-test.sh`**, which sits alongside the documented `script/` entrypoints and is not mentioned. ## Definition of done 1. A README "Routes" section covering every registered route, with method, purpose, auth requirement, and response codes. 2. A section describing the encrypted-URL flow end to end: what it is for, how a token is generated, how TTL works, and what an expired token returns (410). 3. `q` and `fit` documented with their valid ranges and their effect on caching. 4. `db_url`, `env`, and `PIXA_CONFIG_PATH` documented, plus the config file search order. 5. `config.example.yml` lists every key the code accepts, with defaults — making `README.md:119`'s "all options with defaults" claim true. (Coordinate with the issue adding the four missing README keys; whichever lands second completes the set.) 6. `scripts/manual-test.sh` mentioned in the Entrypoints section, or moved/removed. 7. `make fmt` run and the formatted markdown committed; `make check` green. ## Process note Docs-only if it stays confined to `README.md` and `config.example.yml` — in which case it skips adversarial review per repo policy. If it turns out a key needs code changes to be documentable, split that into its own issue rather than mixing.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:47:47 +02:00

clawbot referenced this issue

2026-08-09 07:04:27 +02:00

Port is not overridable with the PORT environment variable #99

clawbot referenced this issue

2026-08-09 16:10:39 +02:00

Tracking: 1.0.0 sequencing and critical path #103

Sign in to join this conversation.