pyweb-stack 0.6.1__tar.gz → 0.6.3__tar.gz

{pyweb_stack-0.6.1 → pyweb_stack-0.6.3}/CHANGELOG.md

@@ -6,6 +6,246 @@ project uses [semantic versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [0.6.3]
+
+An audit release. A security and reliability pass over the whole
+framework (guards and RLS fail closed, forms only accept their own fields,
+dropped database connections recover, Redis hiccups no longer switch
+features off), and the pieces apps missed most: HTTP routes and
+middleware, page caching, translations, error boundaries, better testing
+and debugging, CSV export, drag-and-drop uploads, a form stepper,
+responsive images, and rename in the editor. Read **Changed** before
+upgrading: `pyweb serve` now needs `PYWEB_AUTH_SECRET`, and Postgres
+tenant tables get a new policy.
+
+### Security
+- **Guards fail closed without a secret.** A server function guarded by
+  `@auth.required` or permissions used to run unchecked when the app had no
+  `PYWEB_AUTH_SECRET`; it is now refused. Rate limits run before any other
+  check.
+- **Forms only accept the fields they rendered.** Each `<Form>` carries a
+  signed list of its field names; extra fields in a submit (`is_admin=1`)
+  are ignored, and a submit without the list is refused ("reload the page").
+- **Row policies cover bulk writes and the stored row.** `update()` and
+  `delete()` on a policied Model check every affected row, and `save()`
+  checks the row as stored as well as the new values.
+- **Postgres row-level security fails closed.** A connection that never set
+  the organization sees no rows (it used to see every organization), and
+  the organization is set before every statement, so views and functions
+  are covered too.
+- **Spread attributes** (`{**attrs}`) can't add `on*` handlers in any
+  case, `srcdoc`, or unchecked URLs (`formaction`, `data`, `poster`, ...).
+- **Emailed links** never use a foreign `Host` header, in development too.
+- **Accounts:** 2FA codes work once; setting a first password and signing
+  out other devices need a recent sign-in (10 minutes); OAuth
+  `email_verified` must really be true; form redirects go through
+  `safe_next`.
+- **Webhooks:** GitHub deliveries are de-duplicated on the body (GitHub
+  doesn't sign its delivery id).
+- **Push:** someone who learns a browser's push endpoint can't take it
+  over or unsubscribe it.
+- **Outbound fetch:** NAT64 (`64:ff9b::/96`) and IPv4-compatible IPv6
+  addresses are judged by the IPv4 address inside them.
+- **S3:** `upload_url(name, content_type=...)` signs the content type, so an
+  upload can't be stored as `text/html`.
+- **Request headers** are looked up case-insensitively everywhere (CSRF
+  token, `Last-Event-ID`, `traceparent`).
+- **WebSockets:** a ping flood closes the socket.
+- **Translations:** the `Plural-Forms` rule of a `.po` file may only be a
+  plural rule (no powers, shifts or huge numbers), so a hostile catalog
+  can't hang the server.
+- **Page cache:** copies are kept per host and per language, and cached
+  pages say `Vary: Cookie` (plus `Accept-Language` with translations) so a
+  CDN keeps them apart too.
+- **`<Image>`:** Pillow opens only the format a file's name says, and each
+  file has one cached copy per width however its path is spelled.
+- **Source maps** in `pyweb dev` hold the whole `.pyweb` file, server code
+  included: only the developer's own browser gets them (not share-link
+  guests or the LAN). `pyweb build` maps never contain source.
+- **CSV:** DataTable downloads also neutralize cells starting with a tab or
+  carriage return.
+- The VS Code extension uses `vscode-languageclient` 11; its build tools no
+  longer pull in vulnerable `@azure/msal-node` and `qs` versions.
+- **Dev tools:** `pyweb dev --share` treats a tunnel that rewrites `Host` to
+  localhost as a guest; detailed error pages go only to the developer;
+  `pyweb mcp --http` always needs a token (kept in `.pyweb/mcp-token`);
+  the compile cache is read only from a folder and files only you can
+  write.
+
+### Fixed (reliability)
+- **Dropped database connections recover.** A connection the server closed
+  (restart, failover, idle timeout) is replaced instead of failing every
+  request that later draws it from the pool; a read on one is retried once
+  on a fresh connection; a transaction pings a connection that sat idle.
+- **Redis live updates and rate limits** no longer turn themselves off for
+  good after one error: they work without Redis for 5 seconds and try
+  again. Two servers publishing to one channel at once can't make Redis
+  refuse a message anymore (number, store and announce are one atomic
+  script), and the shared rate limit can't be overshot by concurrent calls.
+  Redis clients get 2-second timeouts.
+- **Live queries** no longer miss a change when a page render picked up the
+  new rows before the watcher re-ran.
+- **`RedisCache`:** `clear()` deletes only the cache's own keys (it used to
+  empty the whole Redis database); `@cache(backend=RedisCache(...))` and
+  `swr()` work with it; tag sets expire with their keys.
+- **Jobs:** PyWeb's own jobs (webhooks, push) run in a worker that never
+  queued one; a job name a worker doesn't know is retried later (a deploy in
+  progress) instead of dying at once; a timed-out job keeps its slot until
+  its thread really returns.
+- **Overload and shutdown:** requests waiting for a thread beyond
+  `PYWEB_MAX_QUEUE` (256) get `503` with `Retry-After`; work still queued
+  when its time limit passes isn't started; `/healthz` is answered even with
+  every thread busy, and `/readyz` says 503 while draining; jobs and
+  requests wind down together within `PYWEB_SHUTDOWN_TIMEOUT` (25 s).
+- Streamed server functions run every step on one thread; a WebSocket
+  handshake that fails gives its slot back; the Redis job store's cleanup
+  reaches every job; failures in the live-data watcher are logged.
+
+### Added
+- **HTTP routes and middleware.** `@app.route("/api/items/{id:int}",
+  methods=[...])` (and `@app.get` / `@app.post`) answer anything that isn't a
+  page: JSON, text, CSV downloads (`pyweb.routes.csv`), redirects, with typed
+  path parameters, `login=`/`roles=`/`rate=` guards, API tokens
+  (`tokens=True`), CORS (`cors=[...]`) and a same-site check for writes.
+  `@app.middleware` runs around every request. Routes appear in
+  `pyweb openapi` and the MCP `pyweb_routes` tool. See
+  [Routes & middleware](docs/36-routes.md).
+- **Page caching.** Every page gets an `ETag` (and `304 Not Modified`);
+  pages that are the same for everyone may be kept by the browser
+  (`no-cache` instead of `no-store`). `@app.page(cache=300, vary=[...])` keeps
+  the rendered HTML for visitors who aren't signed in, dropped when a table
+  the page read changes, shared through Redis when configured. See
+  [Performance](docs/29-performance.md#caching-pages).
+- **Translations.** `_("...")` and `ngettext("{n} item", "{n} items", n)` in
+  Python and in markup, gettext `.po` catalogs in `locales/` (no extra
+  package), the language from a `lang` cookie or `Accept-Language`
+  (`App(locales=[...])`, `set_locale()`), `<html lang>` and `dir="rtl"`, the
+  page's strings sent to the browser (an optional `i18n.js`),
+  `number`/`currency`/`date` formatting, and `pyweb i18n extract | init |
+  check`. See [Translations](docs/37-i18n.md).
+- **`<ErrorBoundary fallback="...">`.** A part of the page that fails, on the
+  server or in the browser, shows its fallback instead of breaking the page.
+  Its browser code is a small module loaded only by pages that use it.
+- **Testing:** `response.find("li.done")` / `find_all(...)`,
+  `client.render("Component", **props)`, `client.a11y("/")` (accessibility
+  rules on the rendered page) and `assert_snapshot(value, name)`.
+- **Debugging:** `pyweb dev --debug` (attach VS Code or PyCharm through
+  debugpy); source maps from each page module to its `.pyweb` lines in
+  `pyweb dev`, and `pyweb build --sourcemaps`.
+- `/robots.txt` and `/sitemap.xml` (with `App(base_url=...)`), from the app's
+  public pages plus `@app.sitemap` generators; `App(robots=...)`.
+- Plugins work: `App(plugins=[...])` registers a plugin's routes, pages,
+  server functions and Models.
+- **CSV export:** `DataTable export="csv"` downloads the rows that match
+  the search; the admin has "Export CSV" per Model (fresh sign-in, logged).
+- **Uploads:** drop files on a `<FileInput>`, see what's chosen (image
+  previews, remove one), an upload progress bar, and several files in one
+  field (`photos: list[UploadedFile]`).
+- **`Stepper` / `Step`** (UI kit): a form in steps that checks each step's
+  fields before the next.
+- **`Image`** (UI kit): `srcset` of resized copies made by the server
+  (`/__pyweb/img/<width>/...`, with Pillow: `pyweb-stack[images]`), lazy
+  loading, no layout shift.
+- **Editor:** find references, rename (across the folder's `.pyweb` files
+  for components and server functions) and "did you mean" quick fixes.
+- `TestClient.put/patch/delete`; `pyweb.request.body` and `request.json()`.
+- `PYWEB_DB_POOL` (default 10) and `App(pool_size=...)`: database
+  connections per process.
+
+### Fixed
+- `from pyweb.browser import document` (and `Blob`, `URL`, ...) works in a
+  file that also runs on the server; browser code can construct `Date`,
+  `URL`, `URLSearchParams`, `Blob`, `FormData`, `Event`, `CustomEvent` and
+  `Promise` (`new` is added for you).
+- A server function with a `list[...]` parameter and no default gets `[]`
+  when the form sends none, instead of failing.
+
+### Changed (internals)
+- An option in `@app.page(...)`/`@app.layout(...)` that isn't written out as
+  a value (`login=NEEDS_LOGIN`) is a compile error; it used to be ignored,
+  which could leave a page public.
+- One definition of "came from another site" (`pyweb.security.cross_site`)
+  for server functions, forms, the auth kit and push; one cookie parser
+  (`pyweb.net.http.parse_cookies`).
+- The dev server moved to `pyweb.devserver`, the production checks to
+  `pyweb.checks`, project scaffolding to `pyweb.scaffold` and the page CSP to
+  `pyweb.csp` (the old import paths still work). The server runtime no longer
+  imports the AI helper: `pyweb dev` hooks into page errors instead.
+- `from pyweb import *` no longer brings in tooling modules (`sync`, `lsp`,
+  `deploy`, `build`, ...); `pyweb.lsp` and the others still import.
+- Every `PYWEB_*` setting is documented (a test keeps it that way).
+
+### Changed
+- `pyweb serve` and `pyweb.asgi.create_app()` refuse to start without
+  `PYWEB_AUTH_SECRET` (set `PYWEB_ENV=development` to run without one).
+  The development key is random per machine (kept in
+  `~/.cache/pyweb/dev-secret`) instead of derived from the project path.
+- Tenant tables on Postgres get a new row-level security policy
+  (`pyweb_tenant_v2`). Apps that create tables get it on start; with
+  migrations, run `pyweb db diff` and `pyweb db upgrade`. `pyweb upgrade`
+  explains both changes.
+- Forms rendered by 0.6.2 and submitted after the upgrade are refused once
+  with "reload the page".
+
+## [0.6.2]
+
+The dev loop. Saves update the open page in place with every page and
+component keeping its state, any element opens its own line in your
+editor, error pages fix themselves with AI (your assistant's model through
+MCP, or your own key), a timeline steps back through every change, and
+`pyweb dev --share` gives someone a link to try what you're building. All
+of it lives in `pyweb dev`: production output is unchanged and there is
+nothing to change in your apps. See [The dev loop](docs/35-dev-loop.md).
+
+### Added
+- **Hot reload without a page load.** A save swaps the page in place
+  through client navigation: no reload, no flash. Page variables,
+  component variables (each instance keeps its own), form fields, scroll,
+  focus and the selection stay. A stylesheet-only save swaps just that
+  stylesheet. When the page changed too much to swap, it reloads with the
+  same state, also after a compile error is fixed.
+- **Click to source.** Hold Alt to see where any element comes from;
+  Alt-click opens that line in your editor (`PYWEB_EDITOR`, else VS Code,
+  Cursor, Windsurf, Zed or Sublime Text, else a `vscode://` link) and
+  shows the **inspector**: the components around it with their live
+  variables, which you can edit.
+- **Fix with AI and Edit with AI.** Compile error pages and dev 500 pages
+  have Fix with AI; Alt+Shift-click any element to ask for a change. The
+  answer is a compiled diff of one app file: Apply writes it (refused if
+  the file changed since) and Undo puts it back (`.pyweb/history/`). It is
+  answered by the assistant connected through `pyweb mcp` when its app
+  supports MCP sampling, else `ANTHROPIC_API_KEY` or
+  `OPENAI_API_KEY`/`OPENAI_BASE_URL`, else the page offers the prompt to
+  copy. Credentials in what's sent are replaced by placeholders and put
+  back in the answer.
+- **Time-travel timeline.** The toolbar's Timeline tab records every change
+  to the page's variables with its cause (a click, typing, a server call);
+  a slider steps back through them with the page paused, and Resume
+  returns to now.
+- **`pyweb dev --share`**: a temporary public link (cloudflared, else
+  localhost.run) with a QR code. The link's token sets a cookie that every
+  request through the tunnel needs; guests get the app and hot reload, not
+  your tools.
+- **A better first five minutes.** `pyweb new` with no name asks for the
+  name, a starter and a colour preset (`--theme` without asking); `pyweb
+  dev` opens the browser, prints the network URL with a QR code for a phone
+  with `--host 0.0.0.0`, and shows a one-time Welcome panel with what to
+  try and how to connect your assistant.
+- **A faster first start.** Parse results and compiled code are cached on
+  disk (`~/.cache/pyweb`; `PYWEB_CACHE=0` turns it off): loading the saas
+  example in a fresh process went from about 340 to 210 ms.
+  `pyweb.bench --system` reports `cold_dev_ms`.
+- MCP: the `pyweb_assist_requests` tool and the `fix_errors` prompt;
+  `pyweb mcp` answers the page's AI requests through sampling.
+
+### Changed
+- `pyweb dev`'s toolbar and its `/__pyweb/dev/` endpoints answer only the
+  person running it: a request from this machine to a loopback address.
+  Visitors from the network (`--host 0.0.0.0`) or a share link get hot
+  reload only.
+- The runtime is 25 bytes bigger (gzip) for the dev hooks; nothing runs
+  in production.
+
 ## [0.6.1]
 
 Better error messages, `pyweb doctor`, a `pyweb dev` that keeps your place

{pyweb_stack-0.6.1/pyweb_stack.egg-info → pyweb_stack-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyweb-stack
-Version: 0.6.1
+Version: 0.6.3
 Summary: Full-stack web apps in one Python file: server-rendered pages, reactive browser UI, typed RPC.
 Author-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
 Maintainer-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
@@ -53,6 +53,8 @@ Provides-Extra: push
 Requires-Dist: cryptography>=42; extra == "push"
 Provides-Extra: desktop
 Requires-Dist: pywebview>=6; extra == "desktop"
+Provides-Extra: images
+Requires-Dist: Pillow>=10; extra == "images"
 Provides-Extra: all
 Requires-Dist: psycopg[binary]>=3.1; extra == "all"
 Requires-Dist: PyMySQL>=1.1; extra == "all"
@@ -63,6 +65,7 @@ Requires-Dist: argon2-cffi>=23.1; extra == "all"
 Requires-Dist: opentelemetry-sdk>=1.24; extra == "all"
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24; extra == "all"
 Requires-Dist: orjson>=3.10; extra == "all"
+Requires-Dist: Pillow>=10; extra == "all"
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
 Requires-Dist: playwright>=1.45; extra == "test"
@@ -70,6 +73,7 @@ Requires-Dist: mcp>=1.2; extra == "test"
 Requires-Dist: hypothesis>=6.100; extra == "test"
 Requires-Dist: pyyaml>=6; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.24; extra == "test"
+Requires-Dist: Pillow>=10; extra == "test"
 Dynamic: license-file
 
 <div align="center">
@@ -400,6 +404,17 @@ develop a toolbar on every page shows each request's queries and flags
 N+1 loops. [Scaling & deploying →](docs/25-scaling.md) ·
 [Logs, metrics & tracing →](docs/26-observability.md)
 
+### A dev loop that keeps up
+
+Save, and the open page changes in place: no reload, and every page and
+component keeps its state. Hold Alt and click any element to open its
+line in your editor; Alt+Shift-click to change it with AI, and error
+pages have **Fix with AI** (your assistant's model through MCP, or your
+own API key), with a diff to apply and Undo. The toolbar's timeline
+steps back through every change and what caused it, and
+`pyweb dev --share` gives someone a link to try what you're building.
+[The dev loop →](docs/35-dev-loop.md)
+
 ### Small, fast and boring to run
 
 - **Every page is server-rendered**: complete HTML on first paint, then
@@ -442,7 +457,7 @@ it runs the real PyWeb, server functions included, in your browser.
 pip install pyweb-stack
 pyweb new myapp --template saas      # saas | desktop | blank | counter | todo | blog | auth | chat | ai-chat
 cd myapp
-pyweb dev app.pyweb                  # edit app.pyweb; the page reloads on save
+pyweb dev app.pyweb                  # saves update the open page in place, state kept
 ```
 
 Then:
@@ -478,7 +493,7 @@ The [architecture overview](ARCHITECTURE.md) goes through each stage.
 
 ## Build it with AI
 
-PyWeb ships an MCP server with 30 tools, so AI assistants can do what
+PyWeb ships an MCP server with 31 tools, so AI assistants can do what
 you'd do: scaffold an app, search the docs, check each edit (errors come
 back as line numbers with fix hints), build with the UI kit and a theme,
 render pages and call server functions as any signed-in member, look at
@@ -566,7 +581,7 @@ Upgrade with `pip install -U pyweb-stack`.
 
 | Version | Highlights |
 |---|---|
-| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests |
+| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests; 0.6.2: the dev loop (hot reload in place with component state, Alt-click to source, Fix/Edit with AI, a time-travel timeline, `pyweb dev --share`, a guided `pyweb new`); 0.6.3: security and reliability fixes, HTTP routes and middleware, page caching and ETags, translations, `<ErrorBoundary>`, test helpers, source maps, CSV export, drag-and-drop uploads, `Stepper`, `<Image>`, editor rename |
 | 0.5 | Models with migrations, forms, auth kit with passkeys, OAuth and an admin, row-level live updates over WebSockets on PyWeb's own server, durable jobs and schedules, `pyweb deploy` for docker, compose, k8s, fly, render and railway, logs, metrics, tracing and a dev toolbar, data-aware editor and MCP tools, the `saas` template, `pyweb upgrade` |
 | 0.4 | npm packages without Node, layouts and client-side navigation, streaming server functions and `<Markdown>` for AI apps, live queries, page head tags, `.pyweb` error pages; 0.4.1: richer MCP tools; 0.4.2: VS Code run, new-app and MCP commands; 0.4.3: fixes, security hardening, gzip and caching; 0.4.4: key rotation, session revocation, typed arguments, Redis-shared limits, `check --production` |
 | 0.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |

{pyweb_stack-0.6.1 → pyweb_stack-0.6.3}/README.md

@@ -326,6 +326,17 @@ develop a toolbar on every page shows each request's queries and flags
 N+1 loops. [Scaling & deploying →](docs/25-scaling.md) ·
 [Logs, metrics & tracing →](docs/26-observability.md)
 
+### A dev loop that keeps up
+
+Save, and the open page changes in place: no reload, and every page and
+component keeps its state. Hold Alt and click any element to open its
+line in your editor; Alt+Shift-click to change it with AI, and error
+pages have **Fix with AI** (your assistant's model through MCP, or your
+own API key), with a diff to apply and Undo. The toolbar's timeline
+steps back through every change and what caused it, and
+`pyweb dev --share` gives someone a link to try what you're building.
+[The dev loop →](docs/35-dev-loop.md)
+
 ### Small, fast and boring to run
 
 - **Every page is server-rendered**: complete HTML on first paint, then
@@ -368,7 +379,7 @@ it runs the real PyWeb, server functions included, in your browser.
 pip install pyweb-stack
 pyweb new myapp --template saas      # saas | desktop | blank | counter | todo | blog | auth | chat | ai-chat
 cd myapp
-pyweb dev app.pyweb                  # edit app.pyweb; the page reloads on save
+pyweb dev app.pyweb                  # saves update the open page in place, state kept
 ```
 
 Then:
@@ -404,7 +415,7 @@ The [architecture overview](ARCHITECTURE.md) goes through each stage.
 
 ## Build it with AI
 
-PyWeb ships an MCP server with 30 tools, so AI assistants can do what
+PyWeb ships an MCP server with 31 tools, so AI assistants can do what
 you'd do: scaffold an app, search the docs, check each edit (errors come
 back as line numbers with fix hints), build with the UI kit and a theme,
 render pages and call server functions as any signed-in member, look at
@@ -492,7 +503,7 @@ Upgrade with `pip install -U pyweb-stack`.
 
 | Version | Highlights |
 |---|---|
-| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests |
+| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests; 0.6.2: the dev loop (hot reload in place with component state, Alt-click to source, Fix/Edit with AI, a time-travel timeline, `pyweb dev --share`, a guided `pyweb new`); 0.6.3: security and reliability fixes, HTTP routes and middleware, page caching and ETags, translations, `<ErrorBoundary>`, test helpers, source maps, CSV export, drag-and-drop uploads, `Stepper`, `<Image>`, editor rename |
 | 0.5 | Models with migrations, forms, auth kit with passkeys, OAuth and an admin, row-level live updates over WebSockets on PyWeb's own server, durable jobs and schedules, `pyweb deploy` for docker, compose, k8s, fly, render and railway, logs, metrics, tracing and a dev toolbar, data-aware editor and MCP tools, the `saas` template, `pyweb upgrade` |
 | 0.4 | npm packages without Node, layouts and client-side navigation, streaming server functions and `<Markdown>` for AI apps, live queries, page head tags, `.pyweb` error pages; 0.4.1: richer MCP tools; 0.4.2: VS Code run, new-app and MCP commands; 0.4.3: fixes, security hardening, gzip and caching; 0.4.4: key rotation, session revocation, typed arguments, Redis-shared limits, `check --production` |
 | 0.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |

{pyweb_stack-0.6.1 → pyweb_stack-0.6.3}/THREAT_MODEL.md

@@ -42,17 +42,23 @@ load balancer in front.
 |---|---|---|---|
 | S | Another site calls a server function with the visitor's cookies (CSRF) | RPCs are `POST` with a JSON content type only (a cross-site form can't send one), `Origin` and `Sec-Fetch-Site` are checked, cookies are `SameSite=Lax`; optional token check (`PYWEB_CSRF_SECRET`) | `test_request_hardening.py::test_cross_site_requests_are_refused`, `test_rpc_production.py::test_csrf_gate_blocks_cookie_calls_without_token` |
 | S | Another site posts a `<Form>` | A per-visitor CSRF token in every form (double-submit cookie) plus the `Origin` check | `test_forms_v5.py::test_csrf_and_cross_site_posts_are_refused` |
-| T | Arguments of the wrong shape reach a server function (an object where a string was expected, extra fields) | Arguments are checked against the type hints; unknown names are refused; Models only take their own non-readonly fields | `test_forms_v5.py::test_mass_assignment_is_ignored`, `test_fuzz_requests.py::test_rpc_arguments` |
+| T | Arguments of the wrong shape reach a server function (an object where a string was expected, extra fields) | Arguments are checked against the type hints; unknown names are refused; Models only take their own non-readonly fields; a `<Form>` only accepts the fields it rendered (a signed list travels with it) | `test_forms_v5.py::test_mass_assignment_is_ignored`, `test_forms_v5.py::test_fields_the_form_did_not_render_are_ignored`, `test_forms_v5.py::test_a_submit_without_the_signed_field_list_is_refused`, `test_fuzz_requests.py::test_rpc_arguments` |
+| E | A guarded server function runs unguarded because the app has no secret | Guards fail closed: without `PYWEB_AUTH_SECRET` a guarded call is refused, and `pyweb serve` / `create_app` won't start without one (unless `PYWEB_ENV=development`); the development key is random per machine, not derived from the project | `test_security_063.py::test_guarded_functions_fail_closed_in_production_without_a_secret`, `test_security_063.py::test_serve_refuses_to_start_without_a_secret`, `test_security_063.py::test_the_dev_key_is_random_and_private` |
 | T | Request smuggling past a proxy | Ambiguous lengths (`Content-Length` with `Transfer-Encoding`, repeated lengths, folded headers) are refused | `test_net.py::test_refuses_ambiguous_or_malformed_requests` |
 | I | Server-only code, imports or secrets end up in the page's JavaScript | The compiler places each name in the browser or on the server, and referencing a server-only name from browser code is a compile error; credential-like page variables are refused | `test_compiler.py::test_server_only_names_cannot_reach_the_browser`, `test_compiler.py::test_secret_never_goes_to_browser` |
-| I | Stack traces or internal errors reach the visitor | Error responses carry a message and a request id, never a traceback | `test_auth_security.py::test_error_responses_never_leak_tracebacks` |
+| I | Stack traces or internal errors reach the visitor | Error responses carry a message and a request id, never a traceback; in `pyweb dev` the detailed error pages go only to the developer's own browser | `test_auth_security.py::test_error_responses_never_leak_tracebacks`, `test_share.py::test_a_compile_error_page_for_guests_has_no_tools` |
 | I | Encrypted columns reach the browser through `to_dict()` | Encrypted and private fields are left out of `to_dict()` | `test_encrypted_fields.py::test_encrypted_values_stay_out_of_to_dict`, `test_data_layer.py::test_private_fields_stay_out_of_dicts` |
 | D | Huge, deeply nested or very wide bodies | 1 MiB body limit (413), 32 levels / 10,000 values for JSON, 1,000 fields / 100 files for forms, 16 KB of headers (431) | `test_request_hardening.py::test_deeply_nested_json_is_refused_not_a_crash`, `test_request_hardening.py::test_huge_headers_get_431`, `test_fuzz_requests.py::test_too_many_fields_are_refused` |
 | D | Slow clients hold connections (slowloris) | Request heads must arrive within 10 s, idle sockets close after 30 s, 10,000 connections per process | `test_request_hardening.py::test_slow_clients_are_disconnected` |
 | D | One client floods server functions | 120 calls a minute per address by default, per-function `@server(rate=...)`; `X-Forwarded-For` is ignored unless `PYWEB_TRUST_PROXY` says a proxy sets it | `test_rpc_production.py::test_rate_limit_is_per_client_address_and_ignores_spoofed_headers`, `test_rate_per_function.py` |
 | D | Malformed input crashes a handler | The RPC and form parsers are fuzzed: every answer is 2xx or 4xx | `test_fuzz_requests.py` (Hypothesis) |
+| S | Another site calls an HTTP route (`@app.route`) with the visitor's cookies | Unsafe methods (`POST`, `PUT`, `PATCH`, `DELETE`) authenticated by cookie must come from the site itself (`Origin` / `Sec-Fetch-Site`); a Bearer API token is exempt; CORS is off unless a route lists origins | `test_routes.py::test_methods_guards_and_csrf`, `test_routes.py::test_cors_and_preflight` |
+| I | A cached page (`@app.page(cache=...)`) shows one visitor's data to another | Requests with a session cookie or `Authorization` header never get or make a shared copy; a render that read the session, set a cookie, showed a toast or opened a live feed isn't stored; copies are kept per host and language, with `Vary: Cookie` for CDNs | `test_pagecache.py::test_vary_and_personal_pages`, `test_pagecache.py::test_translated_pages_are_cached_per_language_and_host` |
+| D | A translation file's `Plural-Forms` runs code or hangs the server | Only plural-rule syntax is accepted: `n`, small numbers, arithmetic without powers or shifts, comparisons and `?:` | `test_i18n.py::test_a_hostile_plural_rule_is_refused` |
+| D | Resized images (`/__pyweb/img/<w>/...`) used to burn CPU or memory | Only six fixed widths, only files under `static/`, never larger than the original, images over 50 megapixels sent as they are, copies kept in a 64 MB memory cache | `test_images.py::test_only_known_widths_and_static_files` |
+| I | A photo's metadata (camera, location) leaks through `<Image>` | Resized copies are written without EXIF; the original under `static/` is still served as uploaded | `test_images.py::test_resized_without_metadata` |
 | E | A visitor who isn't signed in reaches a protected page or function | `login=`, `roles=` and `fresh=` guards on pages, layouts and server functions | `test_authkit.py::test_instant_signup_and_guards`, `test_auth_security.py::test_required_page_guard_blocks_anonymous` |
-| E | A signed-in user reads or changes another user's rows | Row policies apply to every query and save made for a request | `test_authkit.py::test_row_policies_follow_the_signed_in_user` |
+| E | A signed-in user reads or changes another user's rows | Row policies apply to every query, save, bulk `update()` and `delete()` made for a request; a save checks the row as stored as well as the new values (so a row can't be moved out of someone else's hands). Raw SQL (`db.execute`) is not covered | `test_authkit.py::test_row_policies_follow_the_signed_in_user`, `test_authkit.py::test_write_rules_cover_bulk_changes_and_the_row_as_stored` |
 
 ## 2. Server to browser: what the page runs
 
@@ -60,6 +66,7 @@ load balancer in front.
 |---|---|---|---|
 | T | Data shown on a page injects markup or script (XSS) | Text and attributes are escaped on the server and set as text in the browser; Markdown escapes everything it doesn't build | `test_auth_security.py::test_escape_attr_neutralizes_quote_breakout`, `e2e/test_trusted_types_browser.py::test_pages_enforce_trusted_types_and_the_runtime_works_under_them` |
 | T | `javascript:` and `data:text/html` URLs in links | Replaced by `#` on the server and in the browser | `e2e/test_runtime_dom.py::test_javascript_urls_are_blocked` |
+| T | Spread attributes (`{**attrs}`) built from visitor data add an event handler or a script URL | Spread names must be valid attribute names; `on*` (any case) and `srcdoc` are dropped; URL attributes (`href`, `src`, `action`, `formaction`, `data`, `poster`, …) are checked whatever their case | `test_security_063.py::test_spread_attributes_cannot_inject_handlers_or_urls` |
 | T | Injected markup runs script anyway | Content-Security-Policy: scripts only from the site, no inline script; inline styles only by hash | `test_static_serving.py` (the header is sent), `test_trusted_types.py::test_default_policy_enforces_trusted_types_and_reports`, every browser test (a CSP violation is a console error, which fails the test) |
 | T | A bug passes visitor text to an HTML sink (`innerHTML`) | Trusted Types: the browser refuses strings in HTML and script sinks; the runtime's two sinks use private policies | `e2e/test_trusted_types_browser.py::test_strings_in_html_sinks_are_refused_and_reported`, `test_trusted_types.py::test_the_runtime_only_reaches_html_sinks_through_its_policies` |
 | S | The site is framed to trick clicks (clickjacking) | `frame-ancestors 'self'` and `X-Frame-Options` | `test_production_gaps.py::test_body_cap_and_head_and_security_headers`, ZAP rule 10020 in CI |
@@ -75,13 +82,16 @@ load balancer in front.
 | S | A stolen session keeps working | Sessions end 30 days after sign-in; a password change or reset signs out other devices; any one device can be signed out from `/account` | `test_authkit.py::test_password_reset_signs_out_other_devices`, `test_auth_sessions.py::test_account_lists_sessions_and_signs_one_out` |
 | S | Revocation silently stops working when the database is unwell | The check fails closed: if it can't run, the session is refused | `integration/test_authkit_backends.py::test_session_check_fails_closed_when_the_database_errors` |
 | S | Password guessing | Slowed down per account and per address (not a lockout, which would let anyone lock others out); breached passwords refused | `test_authkit.py::test_guessing_is_slowed_down_not_locked` |
-| S | Account enumeration through sign-in or sign-up | The same message and timing for unknown emails and wrong passwords | `test_authkit.py::test_signup_with_a_taken_email_looks_the_same` |
+| S | Account enumeration through sign-in or sign-up | The same message and timing for unknown emails and wrong passwords at sign-in; with email verification on, sign-up with a taken email looks the same as a new one. With `instant` sign-up (no verification) a taken email is reported, so that mode does reveal which emails have accounts | `test_authkit.py::test_signup_with_a_taken_email_looks_the_same` |
 | S | A replayed or cross-site passkey sign-in | WebAuthn challenges are single-use and bound to the site's origin and RP id | `test_authkit.py::test_a_captured_passkey_sign_in_cant_be_replayed`, `test_authkit.py::test_passkey_from_another_site_is_refused` |
 | S | Taking over an account through an OAuth provider with the same email | A provider sign-in links to an existing account only after signing in to it | `test_authkit.py::test_oauth_sign_up_link_and_no_silent_takeover` |
-| S | Emailed links pointing at an attacker's host | Links use `PYWEB_ORIGIN`, never the `Host` header, in production; each link works once | `test_authkit.py::test_emailed_links_never_trust_the_host_header_in_production`, `test_authkit.py::test_magic_links_need_a_click_and_work_once` |
+| S | Emailed links pointing at an attacker's host | Links use `PYWEB_ORIGIN`; production refuses to send them without it, and elsewhere only a localhost `Host` is used; each link works once | `test_authkit.py::test_emailed_links_never_trust_the_host_header_in_production`, `test_authkit.py::test_emailed_links_never_use_a_foreign_host_header_outside_production`, `test_authkit.py::test_magic_links_need_a_click_and_work_once` |
 | S/E | A leaked API token is used for everything, or for pages | Tokens are stored as hashes, scoped to named server functions, only work on server function calls, never count as a recent sign-in, can expire and be revoked | `test_api_tokens.py::test_scopes_limit_what_a_token_can_call`, `test_api_tokens.py::test_tokens_dont_open_pages_and_can_be_revoked`, `test_api_tokens.py::test_tokens_act_as_their_user_and_organization` |
 | I | A user's data can't be taken out or erased on request | `/account` exports everything that points at the user and deletes the account (organizations owned alone go with it; the audit log is pseudonymised) | `test_account_privacy.py::test_export_holds_the_account_and_rows_that_point_at_it`, `test_account_privacy.py::test_deleting_an_account` |
-| E | A stolen session changes the password or 2FA | Sensitive account changes need a sign-in within the last 10 minutes | `test_authkit.py::test_account_changes_need_a_recent_sign_in` |
+| E | A stolen session changes the password or 2FA | Sensitive account changes (password, 2FA, passkeys, email, signing out other devices) need a sign-in within the last 10 minutes | `test_authkit.py::test_account_changes_need_a_recent_sign_in`, `test_authkit.py::test_setting_a_password_without_one_or_signing_out_everywhere_needs_a_recent_sign_in` |
+| S | A shoulder-surfed or phished 2FA code used again | Each authenticator code works once: the last accepted time step is stored and older ones are refused | `test_authkit.py::test_two_step_sign_in` |
+| S | An OAuth provider's unverified email links an account | `email_verified` must be the boolean `true` (or the string `"true"`) | `test_authkit.py::test_oauth_email_verified_must_really_be_true` |
+| I | The admin's CSV export used to take a copy of a whole table | Admin only, a sign-in within the last 10 minutes, private and encrypted fields left out, 100,000 rows at most, each export written to the audit log | `test_authkit.py::test_admin_lists_edits_and_respects_private_fields` |
 | R | Disputed sign-ins and changes | The audit log (`auth_events`) records sign-ins, failures, resets, 2FA and role changes, with address and device | `test_authkit.py` |
 | T | Header injection through email fields | Mail refuses newlines in headers | `test_authkit_units.py::test_mail_refuses_header_injection` |
 
@@ -100,7 +110,7 @@ load balancer in front.
 |---|---|---|---|
 | T | SQL injection | Every value is a bound parameter; identifiers come from the Models; `pyweb check` flags SQL built from strings | `test_models_db.py::test_param_queries_not_interpolated`, `test_forms_security_obs.py::test_security_flags_sql_and_cmd` |
 | I | A leaked backup or read-only SQL injection exposes personal data | `Field(encrypted=True)`: AES-256-GCM per column under `PYWEB_DATA_KEY`, kept apart from the session secret | `test_encrypted_fields.py::test_values_are_encrypted_at_rest_and_read_back` |
-| T | Ciphertext copied into another column or row to make it show elsewhere | The table and column are the associated data; decryption fails | `test_encrypted_fields.py::test_a_ciphertext_moved_to_another_column_or_row_tamper_fails` |
+| T | Ciphertext copied into another column to make it show elsewhere | The table and column are the associated data; decryption fails. Not covered: someone who can write to the database can copy a value between rows of the same column (the row isn't part of the associated data) | `test_encrypted_fields.py::test_a_ciphertext_moved_to_another_column_or_row_tamper_fails` |
 | I | Key loss on rotation | Old keys stay readable from `PYWEB_DATA_KEY_PREVIOUS`; `pyweb db reencrypt` rewrites rows | `test_encrypted_fields.py::test_rotation_reads_old_rows_and_reencrypt_rewrites_them` |
 | E | Background jobs or admin bypass row policies | Jobs and `system()` blocks run without a user on purpose (they're server code); the admin requires the `admin` role and a recent sign-in, and never shows private fields | `test_authkit.py::test_admin_lists_edits_and_respects_private_fields` |
 
@@ -109,7 +119,7 @@ load balancer in front.
 | | Threat | Mitigation | Proof |
 |---|---|---|---|
 | I/E | A member of one organization reads or changes another's rows | Tenant Models are limited to the current organization on every query, save, bulk update and delete; a row of another organization answers 404 even if loaded some other way | `test_tenancy.py::test_rows_stay_inside_their_organization`, `test_tenancy.py::test_no_sequence_of_operations_crosses_organizations` (Hypothesis) |
-| I/E | Raw SQL (or SQL injection) skips the ORM's organization filter | On Postgres, forced row-level security on every tenant table, checked by the database with a per-statement setting | `integration/test_rls_postgres.py::test_raw_sql_is_limited_by_the_database` |
+| I/E | Raw SQL skips the ORM's organization filter | On Postgres, forced row-level security on every tenant table. The policy fails closed: a connection that never set the organization sees no rows, and PyWeb sets it again before every statement (so views and functions are covered too). It limits mistakes, not an attacker who can run arbitrary SQL as the app (who can change the setting within one statement) | `integration/test_rls_postgres.py::test_raw_sql_is_limited_by_the_database`, `integration/test_rls_postgres.py::test_the_policy_fails_closed` |
 | E | A background job reads every organization's data because no one is signed in | Jobs run for the organization that queued them | `test_tenancy.py::test_jobs_run_for_the_organization_that_queued_them` |
 | E | A viewer writes, an admin removes an owner, a member invites | Role checks on writes and on every management action; an organization keeps at least one owner | `test_org_pages.py::test_admins_cant_touch_owners_and_members_cant_manage`, `test_tenancy.py::test_switching_and_invitations` |
 | S | Someone else accepts a forwarded invitation, or reuses one | Invitations are for the invited email only, work once, expire after 7 days, and are stored as hashes | `test_org_pages.py::test_an_invitation_is_for_its_email_only`, `test_org_pages.py::test_the_whole_team_flow` |
@@ -129,7 +139,7 @@ load balancer in front.
 | | Threat | Mitigation | Proof |
 |---|---|---|---|
 | S | Forged webhook deliveries | Signatures checked in constant time for each scheme (GitHub, Stripe, Standard Webhooks); 401 otherwise | `test_webhooks.py::test_github_and_stripe_schemes`, `test_webhooks.py::test_standard_webhooks_reference_vector` |
-| T | A captured delivery replayed later, or a provider's retry running twice | Signed timestamps must be within 5 minutes; each event id runs once | `test_webhooks.py::test_receiving_runs_the_handler_once_as_a_job` |
+| T | A captured delivery replayed later, or a provider's retry running twice | Stripe and Standard Webhooks: signed timestamps must be within 5 minutes and each event id runs once. GitHub signs no timestamp or id, so its deliveries are de-duplicated on the body itself: the same body runs once | `test_webhooks.py::test_receiving_runs_the_handler_once_as_a_job` |
 | S/I | A customer's webhook endpoint pointing at the internal network | Outbound deliveries go through `pyweb.http.fetch` | `test_webhooks.py::test_endpoints_cant_point_at_the_internal_network` |
 | I | Old uploads (replaced avatars, deleted attachments) kept forever | Files no row refers to are deleted after a day | `test_filegc.py::test_unreferenced_files_go_after_the_grace_period` |
 
@@ -140,6 +150,7 @@ load balancer in front.
 | T/E | Injected script registering its own service worker (which would sit between the app and every later visit) | The worker URL must come from the `pyweb-sw` Trusted Types policy, which accepts `/sw.js` only; the worker is served by PyWeb from its own code | `test_pwa.py::test_registration_uses_a_trusted_types_policy`, `e2e/test_pwa_browser.py::test_installable_and_offline` |
 | I | A signed-in visitor's page kept offline and shown to the next person on a shared computer | Only pages rendered for visitors who aren't signed in are marked as keepable; server functions, forms, live updates and credentialed requests are never cached | `test_pwa.py::test_pages_are_only_marked_for_offline_when_signed_out`, `test_pwa.py::test_service_worker` |
 | S | A notification that opens another site | Notification links must be paths of the app, checked when sending and again in the worker | `test_push.py::test_message_rules` |
+| T | Someone who learns a browser's push endpoint takes it over or removes it | Re-registering an endpoint owned by another user needs that browser's `auth` key; unsubscribing needs the key or the owning user | `test_push.py::test_someone_who_knows_an_endpoint_cant_take_it_over`, `test_push.py::test_subscription_requests_are_checked` |
 | I/S | A visitor subscribing with an endpoint that makes the server send requests elsewhere | Endpoints must be https URLs of the browsers' push services (others only when named in `PYWEB_PUSH_HOSTS`); delivery through `pyweb.http.fetch` | `test_push.py::test_only_real_push_services`, `test_push.py::test_subscription_requests_are_checked` |
 | I | Notification content read by the push service | Payloads are encrypted for the receiving browser (RFC 8291) and requests signed with the app's VAPID key (RFC 8292) | `test_push.py::test_rfc8291_example`, `test_push.py::test_vapid_keys_and_jwt` |
 | T | Another site subscribing a visitor's browser | Subscription requests must be same-origin JSON | `test_push.py::test_subscription_requests_are_checked` |
@@ -172,11 +183,28 @@ websites in the user's browser.
 | | Threat | Mitigation | Proof |
 |---|---|---|---|
 | S/I | A website in the developer's browser calling `pyweb mcp --http` (DNS rebinding, cross-site requests) | Listens on 127.0.0.1; requests with a foreign `Origin` or `Host` are refused | `test_mcp_v6.py::test_http_sessions_streams_and_checks` |
-| S | Someone on the network calling the MCP server | Any address but loopback needs a bearer token | `test_mcp_v6.py::test_http_needs_a_token_beyond_this_machine` |
+| S | Someone on the network, or another user or program on this machine, calling the MCP server | `pyweb mcp --http` always needs a bearer token: `--token`, `PYWEB_MCP_TOKEN`, or one kept in `.pyweb/mcp-token` (mode 0600) | `test_mcp_v6.py::test_http_needs_a_token_beyond_this_machine`, `test_mcp_v6.py::test_http_keeps_a_private_token_when_none_is_given` |
+| T | Another local user planting compiled code in the disk cache | Cache entries are read only from a folder and files owned by you that no one else can write | `test_compile_cache.py::test_disk_cache_ignores_files_others_can_write` |
 | I | A web page or another local user reading the dev server's logs and errors | The agent endpoints need the token in `.pyweb/dev.json` (mode 0600, git-ignored) and answer only on loopback | `test_mcp_v6.py::test_dev_link_needs_its_token`, `test_mcp_v6.py::test_tools_see_a_running_pyweb_dev` |
 | T | An assistant's "read-only" SQL changing data | One statement, write keywords refused (even in a CTE), a read-only transaction that is rolled back; secrets redacted | `test_dx_v5.py::test_mcp_data_tools` |
 | T | Malformed tool arguments reaching app code | Arguments are checked against each tool's schema before it runs | `test_mcp_v6.py::test_arguments_are_checked_before_the_tool_runs` |
 
+## 7d. The dev loop: sharing, AI help, open in editor
+
+`pyweb dev` only. Its tools change files, open programs and show request data, so they are for the
+person running it, on that machine: a request must come from a loopback address and name a loopback
+`Host` (a tunnel's or the LAN's requests don't), and writes must be same-origin.
+
+| | Threat | Mitigation | Proof |
+|---|---|---|---|
+| S | Someone who learns the `--share` address (or guesses the tunnel name) using the app | Every request through the tunnel needs a cookie (`HttpOnly`, `Secure`, `SameSite=Lax`) set by the printed link's random token; forged cookies are refused. A tunnel that rewrites `Host` to localhost is still treated as a guest: only the exact `localhost:<port>` the developer opened counts as them | `test_share.py::test_the_link_sets_a_cookie_and_nothing_else_gets_in`, `test_share.py::test_pyweb_dev_share_end_to_end`, `test_share.py::test_a_tunnel_that_rewrites_host_is_still_a_guest` |
+| E/I | A share-link guest (or someone on the LAN) using the developer's tools: the toolbar's SQL and requests, the agent endpoints, AI fixes, opening files, saving the theme | Guests get the app and hot reload only; every `/__pyweb/dev/` endpoint but change polling answers 403 to them, and their pages carry no toolbar or tool scripts | `test_share.py::test_guests_get_the_app_and_hot_reload_only`, `test_share.py::test_you_still_get_everything_and_the_lan_gets_hot_reload`, `test_share.py::test_a_compile_error_page_for_guests_has_no_tools` |
+| T | A web page making "Fix with AI" or "Edit with AI" write to the app | Same-origin, loopback-only POSTs; the answer is compiled first, applied only on Apply, only to `.pyweb` files in the app, refused if the file changed since; the old version is kept for Undo | `test_assist.py::test_endpoints_refuse_other_sites_and_other_machines`, `test_assist.py::test_a_change_that_does_not_compile_is_refused`, `test_assist.py::test_apply_refuses_when_the_file_changed_since`, `test_assist.py::test_only_app_files_are_targets` |
+| I | A share-link guest or someone on the LAN reads the app's server code through source maps | Dev source maps (they hold the whole `.pyweb` file) go only to the developer's own browser; `pyweb build` maps hold no source | `test_share.py::test_source_maps_hold_server_code_so_only_the_developer_gets_them` |
+| I | Credentials in the app's source sent to a model | Known key formats and random-looking secret values are replaced by placeholders before sending and put back in the answer | `test_assist.py::test_secrets_are_replaced_before_sending_and_put_back`, `test_assist.py::test_the_connected_assistant_answers_through_mcp_sampling` |
+| E | Alt-click "open in editor" used to open arbitrary files or run commands | Only `.pyweb` files inside the app folder or the UI kit; the editor gets an argument list, never a shell; same-origin and loopback only | `test_devopen.py::test_only_app_and_kit_files_resolve`, `e2e/test_dev_inspect_browser.py::test_open_refuses_cross_site_and_outside_files` |
+| I | Dev-only markers or scripts in production pages | `data-pw-src` markers come from dev compiles only; the dev scripts are added by the dev server only | `test_devopen.py::test_other_builds_have_no_marks`, `test_trusted_types.py::test_dev_scripts_never_ship_in_built_pages` |
+
 ## 8. The release
 
 | | Threat | Mitigation | Proof |

{pyweb_stack-0.6.1 → pyweb_stack-0.6.3}/docs/01-introduction.md

@@ -43,6 +43,10 @@ Around that core, PyWeb has what a product needs, in the same file:
   ([Installable apps](31-pwa-push.md), [Desktop apps](32-desktop.md))
 - **Webhooks and files**: signed webhooks in and out, and unused uploads
   cleaned up. ([Webhooks & files](33-webhooks-files.md))
+- **A dev loop that keeps up**: saves update the open page in place with
+  its state kept; Alt-click opens any element's source; Fix with AI and
+  Edit with AI; a time-travel timeline; `pyweb dev --share`.
+  ([The dev loop](35-dev-loop.md))
 - **Shipping**: `pyweb deploy` writes Docker, Compose, Kubernetes, Fly,
   Render or Railway files; logs, metrics and traces come built in.
   ([Scaling & deploying](25-scaling.md))

{pyweb_stack-0.6.1 → pyweb_stack-0.6.3}/docs/02-quickstart.md

@@ -20,9 +20,14 @@ pip install "pyweb-stack[all]"     # optional: Postgres, MySQL, Redis, argon2, O
 ```bash
 pyweb new hello
 cd hello
-pyweb dev app.pyweb          # http://localhost:8000, reloads on save
+pyweb dev app.pyweb          # opens http://localhost:8000; saves update the page in place
 ```
 
+(`pyweb new` with no name asks for one, a starter and colours.) Save a
+change and the open page updates without losing its state; hold Alt and
+click anything to open its line in your editor. [The dev loop](35-dev-loop.md)
+has the rest: Fix with AI, time travel and sharing with `--share`.
+
 `pyweb new` writes `app.pyweb`, a starter test (`test_app.py`) and
 `AGENTS.md`/`CLAUDE.md` (instructions for AI coding agents). Add
 `--template saas` for a small product with teams, accounts, a database,
@@ -82,9 +87,14 @@ page Home("/") signals ['count'] rpc []
 ```bash
 pyweb check app.pyweb                          # compile, security and accessibility checks (CI-friendly)
 pyweb build app.pyweb --out dist --production  # hashed, minified, deployable dist/
+export PYWEB_AUTH_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
 pyweb serve dist                               # production server with /healthz
 ```
 
+`pyweb serve` needs `PYWEB_AUTH_SECRET` (it signs sessions, CSRF tokens and
+links) and won't start without it; `PYWEB_ENV=development pyweb serve dist`
+tries a build locally without one.
+
 `dist/` contains your app source, static assets and a `Dockerfile`; see
 [Deployment](12-deployment.md).
 
@@ -107,6 +117,7 @@ ships it. Then, depending on what you're building:
 - work that runs later or on a schedule: [Background jobs](24-jobs.md);
 - teams that share data: [Teams & organizations](30-teams.md);
 - components, a theme and animation: [UI kit & motion](34-ui-and-motion.md);
+- everything `pyweb dev` does for you: [The dev loop](35-dev-loop.md);
 - an app people install, or a desktop app: [Installable apps & push](31-pwa-push.md),
   [Desktop apps](32-desktop.md);
 - several pages with a shared header: [Layouts & navigation](19-layouts-navigation.md);

{pyweb_stack-0.6.1 → pyweb_stack-0.6.3}/docs/08-pages-routing-assets.md

@@ -151,6 +151,46 @@ def Broken(request_id):
   traceback for 500s; `pyweb serve` shows your page.
 - If an error page itself fails, the built-in page is used.
 
+### One broken part, not a broken page
+
+Wrap a part that may fail (a chart from a flaky service, a widget with complex logic) in
+`<ErrorBoundary>`:
+
+```pyweb
+from pyweb import App, ErrorBoundary
+
+app = App()
+
+
+def RevenueChart(data: list):
+    <ol class="chart">
+        for point in data:
+            <li style={{"--v": point["value"]}}>{point["label"]}</li>
+    </ol>
+
+
+def load_stats():
+    return {"revenue": [{"label": "May", "value": 12}, {"label": "June", "value": 15}]}
+
+
+@app.page("/dashboard")
+def Dashboard():
+    stats = load_stats()
+    <h1>Dashboard</h1>
+    <ErrorBoundary fallback="The revenue chart couldn't load.">
+        <RevenueChart data={stats["revenue"]} />
+    </ErrorBoundary>
+    <p>Orders and the rest of the page keep working if the chart fails.</p>
+```
+
+- On the server, if rendering what's inside raises, the page is sent with the fallback in its place
+  (and the error is reported like any page error).
+- In the browser, if code inside throws (while the page starts, or in a click or input handler and
+  what it changes), that part is replaced by the fallback and a Reload button; the rest of the page
+  keeps working.
+- `NotFound` and bad query parameters still answer for the whole page. The code that runs before the
+  markup (`stats = load_stats()` above) isn't inside the boundary: catch errors there yourself.
+
 ## Responses other than HTML
 
 Return `redirect(url)` from a page to send `303 See Other`. Raise