# webapp

DO-backed fluent web client factory: site-agnostic. Deploy once; instances
are attenuated handles whose **ids are bearer capabilities** — anyone
holding the id string can drive the instance; nobody without it can.
TODO: this proxy-page flow (see [diigo-cache CONTRIBUTING](../diigo-cache/CONTRIBUTING.md)) vs running webapp as
the primary worker (`wrangler dev -c ../webapp/wrangler.jsonc -c ../diigo-cache/wrangler.jsonc`)
so its own port serves the mint form directly; reconsider when the UI
grows past a form or two.

## HTTP surface

- `GET /` — the mint form. Prefill via query string: `?url=…&headers=<urlencoded JSON>&msPerCall=…&title=…`; secret header keys (cookie, authorization, proxy-authorization) render **blank** — paste them at mint time; never echoed back. A dedicated `cookie` field is sugar for the `cookie` header (if the JSON also has one, they must agree).
- `GET /form?render=1&…` — the same form for a proxying worker (diigo-cache's `/_connect`): the action is left as an `ACTION` placeholder for the proxy to point at its own relay.
- `POST /` — mint. Form-encoded (that page) or JSON `{url, headers, msPerCall}` (service-style). Responds `{id, storeId}` (and `x-webapp-id`, `x-webapp-store-id`). Neither id is logged: possession is authority.
- `POST /at/<id>` — drive an instance by capability: JSON `{path?, query?, method?, body?}` → the fluent chain → `{status, text}` (or `{error}`; messages carry no header/param values).
- `PUT /store/<storeId>/<key>` — set a header-store entry (JSON value body), e.g. `PUT /store/<storeId>/cookie` with `"session=…"` rotates the cookie; `DELETE` removes it. → `{ok: true}` (or `{error}`; messages carry no keys or values).

## RPC surface (same-account workers; binding `entrypoint: "WebAppFactory"`)

- `fetch(request)` — the HTTP surface above, over the binding
- `newWebApp({url, headers?, msPerCall?})` → `{id, storeId, app}` — the fluent stub;
  promise pipelining makes a whole `pathjoin().query().get()` chain a
  single round trip
- `at(id)` — the fluent stub for a previously-minted instance
- on a stub, `postForm(fields?, echoCookies?)` → `{status, contentType,
  contentDisposition?, location?, body}`: a multipart/form-data POST.
  `echoCookies` maps a form field to a cookie name; the cookie's value
  (header store included) fills the field at send, so a double-submit
  CSRF token goes out without the holder seeing it. Redirects are not
  followed and a non-OK status is a reply, not an Error (a 3xx to a login
  page is how many sites say "session expired"). `location` comes back
  query-stripped; `set-cookie` never comes back. `body` is bytes: the
  caller knows its charset.
- `store(storeId)` — a header store, with full authority:
  `set("cookie", …)` rotates the cookie under every handle already out

## The header store: two ids, two authorities

Mint makes two things: the instance, and a header store (a `MapStoreDo`
from [the capsite lib](../lib/src/store-do.ts), shaped
`("cookie", { keyShape: "cookie", valueShape: M.string() })`). A `cookie`
header goes into the store, not the instance's `init`; the instance reads
the store's read-only view at every send.

- the **instance id** is authority to *use* the cookie: it goes to the
  cache's wiring.
- the **store id** is authority to *choose* it: it stays with the account
  owner, who can rotate it (log in again, `PUT`) or revoke it (`DELETE`,
  or log out).

Kept apart because whoever can choose the cookie can swap in another
account's session: if the cache's id could rotate, a leaked instance id
would let Mallory fill the cache (and its public page) with her own
bookmarks, and the owner's logout would not stop it.

Instances minted before header stores keep their cookie in
`init.headers`, unchanged; they work as before and cannot rotate.

## Run

    pnpm test          # header store + rotation (vitest, workerd pool)
    npx wrangler dev   # → its own ready line (usually :8787 with the
                       # two-config diigo-cache run; standalone, :8788)

Status: mint + drive exercised end-to-end in the combined dev run
(through diigo-cache's create flow, 2026-10-07); not yet deployed. See
../capsite-checklist.md — the single source for run/connect/deploy
instructions.