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

New Issue

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

clawbot commented

2026-10-04 06:25:22 +02:00

Plan, checked against next at 3a274aa (after #74 landed). Some items are already done: db_url, PIXA_CONFIG_PATH and the env: section are documented under Configuration, and q and fit are documented where the signature is.

README.md "Routes": every route internal/server/routes.go registers (GET /, POST /, POST /generate, GET /logout, GET /v1/image/..., GET /v1/e/{token}/..., GET /robots.txt, GET /.well-known/healthcheck.json, GET /static/..., GET /metrics), each with its method, purpose, what it needs (a signature, a login session, the metrics username and password, or nothing) and the status codes it answers with, read from the handlers.
A section on encrypted URLs from start to end: what they are for, logging in with the signing key, generating one on the page (POST /generate), how its lifetime works, and what an expired one returns.
q and fit: say under "Routes" that both are part of what is cached, so each value is a separate cached image.
The config file search order, as the config loader does it (including .yaml names if it accepts them).
config.example.yml lists every key the code accepts, each with its default, so the README's "all options with defaults" is true.
Item 6 (scripts/manual-test.sh) is left to #97, which decides what happens to the scripts/ directory.
Documentation only. If a key turns out to need a code change before it can be documented truthfully, that is a separate issue. Markdown is wrapped by hand in the README's style until #100 makes make fmt format it.

Model: opus-5-5

Plan, checked against `next` at `3a274aa` (after https://git.eeqj.de/sneak/pixa/issues/74 landed). Some items are already done: `db_url`, `PIXA_CONFIG_PATH` and the `env:` section are documented under Configuration, and `q` and `fit` are documented where the signature is. - `README.md` "Routes": every route `internal/server/routes.go` registers (`GET /`, `POST /`, `POST /generate`, `GET /logout`, `GET /v1/image/...`, `GET /v1/e/{token}/...`, `GET /robots.txt`, `GET /.well-known/healthcheck.json`, `GET /static/...`, `GET /metrics`), each with its method, purpose, what it needs (a signature, a login session, the metrics username and password, or nothing) and the status codes it answers with, read from the handlers. - A section on encrypted URLs from start to end: what they are for, logging in with the signing key, generating one on the page (`POST /generate`), how its lifetime works, and what an expired one returns. - `q` and `fit`: say under "Routes" that both are part of what is cached, so each value is a separate cached image. - The config file search order, as the config loader does it (including `.yaml` names if it accepts them). - `config.example.yml` lists every key the code accepts, each with its default, so the README's "all options with defaults" is true. - Item 6 (`scripts/manual-test.sh`) is left to https://git.eeqj.de/sneak/pixa/issues/97, which decides what happens to the `scripts/` directory. - Documentation only. If a key turns out to need a code change before it can be documented truthfully, that is a separate issue. Markdown is wrapped by hand in the README's style until https://git.eeqj.de/sneak/pixa/issues/100 makes `make fmt` format it. Model: opus-5-5

clawbot referenced this issue from a commit

2026-10-04 06:47:46 +02:00

Document every route, encrypted URLs and the config file search (closes #75)

clawbot referenced a pull request that will close this issue

2026-10-04 06:56:32 +02:00

Document every route, encrypted URLs and the config file search (closes #75) #174

clawbot commented

2026-10-04 06:56:39 +02:00