@jokerized/decksmith 0.5.2 → 0.7.0

package/README.md

@@ -249,7 +249,13 @@ artifact. Three are worth reading as patterns rather than bugs:
   sampled frames, because `marginV` was measured to clear *player chrome* and nothing ever
   guaranteed it cleared the *composition*. Both in
   [`.planning/EXPERIMENT-010-reconcile.md`](.planning/EXPERIMENT-010-reconcile.md). The
-  caption one is **closed**: `build --reserve-captions` gives the band its own strip and
+  seam one is **closed** in the render: each scene's clip outlasts its slide and dissolves
+  over the next scene's empty opening. It stayed open in `deck.html` until 2026-09-18,
+  because the presented deck's own visibility pass read the slide instead of the clip,
+  and gliding across a seam still showed eleven 60Hz ticks of background. Every gate was
+  green, and it was found by stepping that glide one tick at a time —
+  [`.planning/2026-09-18-scene-boundary-blink.md`](.planning/2026-09-18-scene-boundary-blink.md).
+  The caption one is **closed**: `build --reserve-captions` gives the band its own strip and
   `fidelity` fails a deck that draws into it. It is worth reading for how it closed —
   the plan written to fix it asserted that every archetype lays out into `contentH`, ten
   of them do not, and the first fix therefore changed the worst stop by nothing at all.
@@ -349,7 +355,7 @@ Startup says what is missing before anyone waits on it:
 ```
 decksmith: http://127.0.0.1:8475
 decksmith: work /tmp/decksmith-server, one job at a time, 8 may wait
-decksmith: no auth, no TLS. Bound to 127.0.0.1 — set DECKSMITH_HOST to open it, knowing that.
+decksmith: no auth. Bound to 127.0.0.1, so anyone with an account on this machine can spend your Codex quota — set DECKSMITH_TOKEN_FILE to require a token.
 decksmith: codex, edge-tts and ffmpeg all found
 decksmith: images via codex, then svg
 ```
@@ -360,15 +366,24 @@ for pictures still finishes, on the tool's own SVG if it has to.
 
 ### The HTTP surface
 
-| Route | What it does |
-|---|---|
-| `POST /api/jobs` | multipart: `file` (.md/.markdown/.txt/.zip) plus option fields → `202 {id}` |
-| `GET /api/jobs/:id` | `{state, stage, steps[], log[], error, result, queuePosition}` |
-| `GET /api/jobs/:id/events` | the same payload as SSE on every change |
-| `GET /api/formats` | the presets, themes, tones, densities and canvas bounds the picker draws from |
-| `GET /d/:id/...` | the built deck, served statically; `/d/:id/deck.html` is the player |
-| `GET /player.js` | the `<decksmith-player>` element, as an ES module — see below |
-| `GET /examples/embed.html` | a page that embeds two decks with it, and the file you copy |
+| Route | What it does | With a token file |
+|---|---|---|
+| `POST /api/jobs` | multipart: `file` (.md/.markdown/.txt/.zip) plus option fields → `202 {id}` | token |
+| `POST /api/jobs/:id/retry` | runs a job the server kept on disk again, under a new id | token |
+| `GET /api/jobs/:id` | `{state, stage, steps[], log[], error, result, queuePosition}` | token |
+| `GET /api/jobs/:id/events` | the same payload as SSE on every change | token |
+| `GET /api/formats` | the presets, themes, tones, densities and canvas bounds the picker draws from | token |
+| `GET /d/:id/...` | the built deck, served statically; `/d/:id/deck.html` is the player | public |
+| `GET /player.js` | the `<decksmith-player>` element, as an ES module — see below | public |
+| `GET /examples/embed.html` | a page that embeds two decks with it, and the file you copy | token |
+| `GET /` | the uploader; with a token file and no session, the login page | public |
+| `POST /login`, `POST /logout` | set or clear the session cookie, then 303 to `/` | public, only with a token file |
+
+"Token" means `Authorization: Bearer <token>` or the session cookie the login page sets.
+A route that is not in this table answers 401 when a token file is configured, so a route
+added later starts out private. A deck id is 128 random bits and is meant to be shared,
+which is why `/d/` stays public; the job routes are keyed by the same id, which is why
+they do not.
 
 Options on `POST`, all optional, all defaulted server-side: `format`, `width`+`height`,
 `theme`, `slides`, `lang`, `tone`, `density`, `speed`, `narrate`, `voice`, `images`,
@@ -392,46 +407,150 @@ generous one.
 | Variable | Default | Why |
 |---|---|---|
 | `PORT` | `8475` | |
-| `DECKSMITH_HOST` | `127.0.0.1` | There is no auth. Opening it should require typing something. |
+| `DECKSMITH_HOST` | `127.0.0.1` | `127.0.0.1`, `::1` and `localhost` are loopback. **Anything else refuses to start** without `DECKSMITH_TOKEN_FILE`, `DECKSMITH_TLS_CERT` and `DECKSMITH_TLS_KEY` — `127.0.0.2` and `::ffff:127.0.0.1` included. |
+| `DECKSMITH_TOKEN_FILE` | unset | A file holding the token (`openssl rand -base64 32 > f; chmod 600 f`). Set, every route but the public ones in the table above needs it, on any bind. Refused unless it is a regular file, not readable by group or others, 32–1024 characters, one line. |
+| `DECKSMITH_TLS_CERT` / `DECKSMITH_TLS_KEY` | unset | A PEM chain, leaf first, and its **unencrypted** PEM key (mode 600). Set both or neither. Refused unless the certificate is PEM (not DER), matches the key, is in date, has subjectAltNames, and loads into OpenSSL at TLS 1.2. On an exposed bind those subjectAltNames are the only `Host` names the server answers to, and the startup banner prints one of them. |
+| `DECKSMITH_TOKEN` | — | **Not read, and refused if present**, even empty: ignoring it would leave a server someone believes is protected open, and an environment variable reaches shell history and every process the server starts. |
 | `DECKSMITH_WORK` | `$TMPDIR/decksmith-server` | One directory per job; swept by age. |
 | `DECKSMITH_MAX_UPLOAD` | 25 MB | |
 | `DECKSMITH_MAX_QUEUE` | `8` | Concurrency is 1. Past 8 the answer is "full", not "position 400". |
 | `DECKSMITH_JOB_TTL_MIN` | `120` | Files outlive the in-memory record; orphans are swept on boot. |
 | `DECKSMITH_JOBS_PER_HOUR` | `5` | Per IP. Charged only on an **accepted** job. |
 | `DECKSMITH_REQS_PER_MIN` | `240` | Per IP. |
-| `DECKSMITH_FETCH_FIGURES` | off | See below. |
-| `DECKSMITH_DECK_SANDBOX` | on | Serves decks under `CSP: sandbox`. |
+| `DECKSMITH_FETCH_FIGURES` | on | See below. |
+| `DECKSMITH_DECK_SANDBOX` | on | Serves decks under `CSP: sandbox`. Turning it off is refused with a token file or on an exposed bind. |
 | `DECKSMITH_IMAGES` | unset | `openai` names a separate image backend for `illustrate`. Unset, pictures come from the Codex account, then the tool's own SVG. |
 | `DECKSMITH_IMAGES_API_KEY` | | The backend's key. Environment only — never a preference, a config file, a `.deck`, or an error message. |
 | `DECKSMITH_IMAGES_BASE_URL` | `https://api.openai.com/v1` | Any OpenAI-compatible `images/generations` endpoint. |
 | `DECKSMITH_IMAGES_MODEL` | `gpt-image-2` | The backend's model. The Codex rung draws with the account's own. |
 
-**Remote figures are off by default, and that is a security decision.** `fetchFigures`
-does `readFile(src)` on anything that is not an http URL, so an uploaded document
-containing `![](../../../etc/ssh/ssh_host_rsa_key)` would have this process read it.
-Relative paths are resolved inside the upload directory and confined there; http figures
-are dropped with a named warning unless you turn them on. A hostname allowlist does not
-close the SSRF — DNS can answer differently the second time — so none is pretended.
+**Remote figures are fetched by default, and what makes that safe is not the flag.** A
+paper's markdown usually links its images rather than attaching them. `guardFigures` in
+`src/server/pipeline.ts` drops any figure whose host resolves to a private, loopback or
+link-local address, and the fetch checks the address again when it connects, because DNS
+can answer differently the second time. `fetchFigures` does `readFile(src)` on anything
+that is not an http URL, so an uploaded document containing
+`![](../../../etc/ssh/ssh_host_rsa_key)` would have this process read it: relative paths
+are resolved inside the upload directory and confined there. `DECKSMITH_FETCH_FIGURES=0`
+drops every http figure with a named warning. (The table above said "off" until
+2026-09-18, while `main.ts` defaulted it on.)
+
+### Opening it to a network
+
+To use a server on another machine yourself, leave it on loopback and tunnel:
+`ssh -L 8475:127.0.0.1:8475 <host>`, then open `http://127.0.0.1:8475` locally. Nothing
+else is needed. If other people have accounts on either machine, add a token file.
+
+To bind anything else, the server needs all three:
+
+```sh
+openssl rand -base64 32 > ~/.decksmith-token && chmod 600 ~/.decksmith-token
+DECKSMITH_HOST=0.0.0.0 \
+DECKSMITH_TOKEN_FILE=~/.decksmith-token \
+DECKSMITH_TLS_CERT=/etc/decksmith/fullchain.pem \
+DECKSMITH_TLS_KEY=/etc/decksmith/privkey.pem \
+npm run serve
+```
+
+Missing any of them, it refuses to start, names every problem at once, and exits 1 before
+it touches the work directory. There is no override. The certificate must list the names
+people will type as subjectAltNames: those names, and nothing else, are what the server
+answers to, so DNS rebinding is refused on this bind as well as on loopback — and the
+startup banner prints a URL built from one of those SANs, not from the bind address,
+because `https://0.0.0.0:8475` is a URL this server answers 403 to. The certificate is
+checked as far as OpenSSL will check it before anything is created on disk: a PEM chain
+(a DER file is refused by name, with the `openssl x509 -inform der` line that converts
+it), matching the key, in date, with SANs — and then loaded into a real
+`tls.createSecureContext`, so a key OpenSSL will not use, such as an RSA key under 2048
+bits, is a refusal here rather than an OpenSSL stack trace out of `listen`. There is no
+plain-http listener or redirect beside it, and no HSTS. Renewing the certificate or
+rotating the token means restarting.
+
+A browser gets a login page at `/`. The token goes in a password field, so a password
+manager can keep it. The server sets a cookie named for the port it is bound to —
+`__Host-decksmith-8475` over TLS, `decksmith-8475` on plain loopback — `HttpOnly`,
+`SameSite=Strict`, valid seven days. It is signed with a key derived from the token and
+from `host:port`, so it survives a restart, rotating the token file logs every browser
+out, and a second DeckSmith on the same machine neither overwrites this one's cookie nor
+accepts a session it minted. Scripts send `Authorization: Bearer <token>` instead. A
+write that relies on the cookie must carry `Sec-Fetch-Site` or `Origin`; a current
+browser sends both on a POST. Ten wrong tokens from one address lock that address out for
+fifteen minutes, including a right token sent during that time; the lockout is logged
+once and every attempt refused during it is logged too. The log records refusals and
+never the token, a cookie or an `Authorization` header.
+
+Three things that cookie does **not** do, each of which this README claimed until
+2026-09-18:
+
+- **Logging out does not revoke the session.** `POST /logout` clears the browser's copy.
+  The value is a MAC over an expiry, checked with no server-side state, so a copy taken
+  before the logout keeps working until it expires — up to seven days. Rotating the token
+  file and restarting is what actually revokes.
+- **`SameSite=Strict` does not stop another site steering a logged-in viewer.** It
+  withholds the cookie from a navigation another site starts, and sends it on one this
+  origin starts. A deck is public and opens top-level, so a link from anywhere can put a
+  hostile deck on screen, and that deck can navigate itself to
+  `/examples/embed.html?a=<its own directory>` — a same-site hop, which arrives with the
+  session. Measured, and it queued a job. `/examples/embed.html` now carries
+  `connect-src 'none'`, which is what refuses that job; the page needs no network of its
+  own, and the decks it frames still load.
+- **The cookie is not confined to this port.** Cookies have no port (RFC 6265 §1), so the
+  browser sends this one to every listener on the host. See below.
+
+Every response that is not a deck file carries `X-Frame-Options: DENY` and
+`Content-Security-Policy: … frame-ancestors 'none'`, so nothing can frame the uploader,
+the API, or an error page.
+
+#### What a same-host attacker can still do
+
+Anything on this machine that the browser can be made to talk to is handed the session
+cookie, because cookies are scoped by host and never by port. So, with a token file set
+and a browser logged in, another local account can:
+
+- **read the session cookie** by getting the browser to make any request to a port it
+  listens on — a page the viewer opens, an image, a redirect — and then **replay that
+  value from a script**, as the logged-in user, until it expires. Naming the cookie after
+  the port does not hide it; nothing this server does can, because the decision is the
+  browser's. The fix is not on this host: it is a distinct hostname per service, or decks
+  and API on separate origins with a `__Host-` cookie that cannot leave one;
+- **read the token file**, if its mode allows it — which is why a mode other than 600 is a
+  refusal at startup;
+- **lock the owner out for fifteen minutes** by sending ten wrong tokens. Every local
+  process shares `127.0.0.1` as far as `socket.remoteAddress` is concerned, and that is
+  the only key the limiter has. The lockout and each refusal during it are in the log, so
+  it is at least visible;
+- **reach a loopback bind at all, when no token file is set.** That is the default.
+
+Over the LAN, with an exposed bind, none of the above follows: the cookie is `__Host-`
+and `Secure`, the connection is TLS 1.2 or better with no plain-http listener beside it,
+and a request by any name the certificate does not list is refused before the token is
+even considered. What a LAN attacker gets without the token is the deck files whose
+128-bit id they already know, and nothing else.
 
 ### What is missing before this is public
 
-This runs a demo on a laptop. It is **not** ready to face the internet, and the gap is
-not a polish gap:
-
-- **No authentication and no TLS.** Anyone who can reach the port can spend your Codex
-  quota. This is why the default bind is loopback.
-- **DNS rebinding is refused only on a loopback bind.** A write another site's page makes
-  a browser send is refused on any bind: `Sec-Fetch-Site`, or `Origin` where that is
-  missing. But a rebinding page is same-origin to itself, and the only thing that gives it
-  away is a `Host` naming something other than the server. On `127.0.0.1` that check is
-  on. On any other `DECKSMITH_HOST` the server cannot know its own names, so the check is
-  off until it is given an allowlist.
+A token and TLS are in: see "Opening it to a network" above. This is what is still
+missing, and some of it is not a polish gap:
+
+- **One token, no accounts.** Everyone who holds the token is the same user, with the same
+  quota and the same view of every job whose id they know. A single session cannot be
+  revoked, and neither can logging out revoke one: rotate the token file and restart. No
+  roles, no per-token quota, no OIDC.
+- **The session cookie is shared with every other port on this host**, and a captured one
+  replays until it expires. See "What a same-host attacker can still do" above.
+- **No reverse-proxy support.** `X-Forwarded-*` is not read (see the rate-limit item
+  below), and on a loopback bind the `Host` check refuses whatever public name a proxy
+  forwards.
+- **Without a token file, loopback is open to this machine.** Anyone with an account on it
+  can reach `127.0.0.1`. `DECKSMITH_TOKEN_FILE` on loopback turns the token on there too.
 - **Codex spend is unmetered per upload.** The per-IP hourly limit is the only brake, and
   it is per-IP.
 - **Rate limiting is by `socket.remoteAddress` only.** `X-Forwarded-For` is deliberately
   not read, because unproxied it is a header the client writes. Behind a reverse proxy
   every client therefore looks like one address and the limits collapse — teach the proxy
-  to rate-limit, or teach this to trust exactly one hop.
+  to rate-limit, or teach this to trust exactly one hop. On a loopback bind every local
+  process is already that one address, so the failed-token lockout is a denial of service
+  any local account can aim at the owner; it is logged, not prevented.
 - **Deck files are readable by anyone holding the 128-bit id.**
 - **The deck sandbox does not isolate the origin, and cannot on one host.** Decks are
   served under `Content-Security-Policy: sandbox allow-scripts allow-same-origin
@@ -440,6 +559,18 @@ not a polish gap:
   drives the composition through `iframe.contentDocument`, so an opaque origin makes
   every slide render blank while the job reports `done`. Real isolation means serving
   `/d/:id` from a **separate origin**, which is a second listener and is not built.
+- **A deck shown inside the uploader can act as whoever is logged in.** The deck is
+  same-origin with the page around it, so its script can call `parent.fetch`. That call
+  runs under the uploader's policy, not the deck's `connect-src 'none'`, and carries the
+  session. Measured: a stub deck doing this queued a job
+  (`.planning/2026-09-18-deck-parent-reach.md`). A deck opened on its own cannot: nothing
+  it could frame will load, and the one page it can navigate the viewer to,
+  `/examples/embed.html`, carries `connect-src 'none'` — both measured, both with their
+  control. So what is left needs hostile content converted by the operator, script that
+  survives into the deck, and the operator watching that deck **in the uploader**, which
+  is the one page that must be able to reach the API.
+  `DECKSMITH_JOBS_PER_HOUR` still caps what it can spend. The fix is the separate deck
+  origin above.
 - **No persistence.** A restart forgets every job record. The files survive and are swept
   by age on boot.
 - **Disk is bounded only by TTL × queue rate**, and uploaded files are not scanned.
@@ -719,8 +850,8 @@ Three, each a position rather than a hue.
 
 `mono`'s four tones are a grey ladder plus one red rather than four hues, because value is
 what survives a bad projector and hue is not; four hues would have collapsed into one
-grey. All three keep the Inter stack — font families auto-resolve from a fixed allowlist,
-and a serif naming a family the bundle does not declare falls back silently.
+grey. All three keep the Inter stack — `build` ships Inter beside every deck, and a serif
+naming a family the deck does not declare falls back silently.
 
 A theme is a name and a palette, and that is the whole extension point: a new one is a
 file in `src/emit/themes/` plus a line in `THEMES`. No archetype learns it exists.
@@ -745,6 +876,20 @@ that just appeared, and the deck advances on speech rather than on a number some
 guessed. Write one sentence per reveal, in reveal order. Fewer sentences than stops leaves
 the later reveals silent; more, and the surplus joins the last one.
 
+**A beat's stop count can depend on the canvas.** At 1600×900 the demo's stack beat does
+not fit, so `narrate` puts all four of its sentences on one stop; at 1920×1080 it has four.
+So `narrate` takes the same `--format`, `--width`/`--height` and `--reserve-captions` flags
+as `build`, and `narration.json` records the stop count each narrated beat was split over.
+`build` compares that count with its own staging for every beat it keeps, and refuses a
+beat whose sentences it would split differently. The error names the beats and prints the
+`narrate` flags that fix it. Narration made once at the default canvas still builds the
+short, the `--reserve-captions` deck and an unpacked `.deck` wherever those stage the kept
+beats the same way, which on the demo is every one. Re-narrating in the directory the
+narration was made in only synthesises sentences that now split differently. An unpacked
+`.deck` has no TTS cache, so there it synthesises all of them. A `narration.json` or pack
+written before the counts were recorded still builds, and `build` says it could not check
+it. See `.planning/2026-09-18-narrate-build-canvas.md`.
+
 Playback reads the audio element's own clock, never a timer: a timer agrees with the audio
 right up until the first stall, and a stall is exactly when a viewer looks at the subtitle
 to find out what they missed. `m` mutes (captions keep tracking, and a muted element is
@@ -1059,8 +1204,10 @@ mechanically rather than free-hand.
   presented, never rendered, and its subtitle loop legitimately reads a clock.
 - `deck.html` never contains the string `data-composition-id`. A root-level HTML file that
   does trips lint's `multiple_root_compositions`, and the deck stops being navigable.
-- Fonts auto-resolve only from a fixed allowlist. Inter is on it, Noto Sans KR is not, so
-  every CJK deck ships its own subsetted `@font-face` or the text silently falls back.
+- Every deck declares the face its stack names. A CJK deck ships a subsetted Noto; every
+  other deck ships Inter from `@fontsource-variable/inter`. HyperFrames resolves Inter from
+  its own allowlist, but only inside a render: the gates' page and `deck.html` never run its
+  compiler, and without the deck's own face they drew SF on a Mac and DejaVu on Linux.
 - Audience text never goes below 40px at 1920x1080, display equations sit at 60–76px. A
   30px equation passes every automated gate and is unreadable from row six.
 - **No archetype declares its own content width.** The box comes from