mangaBookmark/docs/superpowers/specs/2026-07-25-web-ui-design.md

# Web UI Design — browser-accessible bookmark list

Date: 2026-07-25
Branch: `feat/web-ui`
Status: approved

## 1. Problem

The bookmark list is reachable only from inside the userscript, which means it
exists only on pages of asurascans.com and demonicscans.org. There is no way to
open the list on its own — from a desktop, from a phone home screen, or when
neither manga site is loaded.

This adds a website, served by the existing Go backend, that renders the same
list with the same actions.

## 2. Scope

In scope:

- Password-gated website showing all bookmarks, ordered by `updated_at DESC`.
- All / Favourites tabs.
- A "Continue reading" strip of the five most recent series.
- Per-series actions: continue reading, toggle favourite, manually override the
  read chapter, delete.
- Client-side title search.

Out of scope:

- A chapter-level reading-event log. The list order already answers "what did I
  read last". A `reading_events` table is a separate future spec.
- Any change to `GET /bookmarks`, `PUT /bookmarks/{key}`,
  `DELETE /bookmarks/{key}`, or to the userscript. Those stay exactly as they
  are, so the website cannot regress phone reading.
- Offline support. The userscript keeps its `localStorage` cache; the website is
  server-rendered and requires connectivity.

## 3. Architecture

One binary, one container, one SQLite file. The website is added to the running
service rather than deployed alongside it.

```
Bromite userscript ──bearer──> /bookmarks*  ─┐
                                             ├─> Store ──> SQLite
Browser (phone/desktop) ──cookie──> / , /ui/*┘
```

New files under `backend/`:

| File | Purpose |
| --- | --- |
| `web.go` | Page and HTML-fragment handlers |
| `session.go` | Cookie signing/verification, login rate limit |
| `templates/*.html` | `go:embed`-ed templates |
| `static/*` | `go:embed`-ed `style.css`, `htmx.min.js`, `filter.js` |

Templates and static assets are embedded, so the image stays a single static
binary on distroless and `CGO_ENABLED=0` still holds.

### 3.1 Routes

| Route | Auth | Response |
| --- | --- | --- |
| `GET /` | session | List page; login page when no valid session |
| `POST /login` | none | Sets cookie, `303` to `/` |
| `POST /logout` | session | Clears cookie, `303` to `/` |
| `GET /static/{path...}` | none | Embedded asset, long-lived cache header |
| `GET /ui/list?tab=all\|fav` | session | List fragment |
| `POST /ui/bookmarks/{key}/favorite` | session | Re-rendered card |
| `POST /ui/bookmarks/{key}/chapter` | session | Re-rendered card |
| `DELETE /ui/bookmarks/{key}` | session | `200` with empty body |

`GET /` returns the login page with status `200` rather than redirecting to a
separate login URL. One page, no redirect loop to reason about.

`/ui/*` returns HTML fragments, not JSON, and is authenticated by cookie. It is
kept separate from `/bookmarks*` deliberately: that API is JSON, authenticated
by bearer token, and consumed by the userscript. Sharing one route for two
representations and two auth schemes would couple the website's needs to the
userscript's contract.

Middleware layering is unchanged at the top: `withCORS` stays outermost.
`/bookmarks*` keeps `withAuth` (bearer). `/` and `/ui/*` are wrapped in a new
`withSession`. Web routes are same-origin, so CORS is a no-op for them.

### 3.2 Store change

`Store` gains one method:

```go
func (s *Store) Get(key string) (Bookmark, bool, error)
```

Every UI mutation is read-modify-write: load the row, change the single field,
call the existing `Upsert`, then render the row `Upsert` returns. This reuses
the conditional-`updated_at` rule rather than reimplementing it — favouriting
does not reorder the list, a chapter override does. Rendering the returned row
(not the request payload) is the same contract `PUT /bookmarks/{key}` already
follows.

Not adding `Get` and instead patching columns directly would duplicate the
`updated_at` decision in a second place. That rule has already caused one bug;
it lives in exactly one function.

## 4. Session authentication

### 4.1 Configuration

New environment variable `WEB_PASSWORD`. When it is empty the web routes are not
registered at all and `/` returns `404`. Fail-closed: a deployment that forgets
the variable exposes nothing.

The password is stored in plaintext in `.env`, alongside `API_TOKEN`. This is a
single-user deployment with no user table, and anyone who can read `.env`
already holds the API token, so hashing it protects nothing that is not already
lost. `.env` is gitignored and the repository is private and self-hosted.

### 4.2 Cookie

Name `mangabm_session`. Value:

```
<expiry_unix_ms> "." base64url(HMAC-SHA256(<expiry_unix_ms>, key))
key = SHA256(API_TOKEN || 0x00 || WEB_PASSWORD || "mangabm-web-session-v1")
```

Stateless: no session table, sessions survive restarts, and rotating either
`API_TOKEN` or `WEB_PASSWORD` invalidates every session at once. Both secrets
are bound in so that changing the password actually logs existing browsers out;
the `0x00` separates the two variable-length secrets so no pair of different
inputs can concatenate to the same string.

Attributes: `HttpOnly`, `SameSite=Lax`, `Path=/`, `Max-Age` 60 days so the phone
stays logged in across long gaps. `Secure` is set when `r.TLS != nil` or
`X-Forwarded-Proto: https`, and omitted otherwise so `http://localhost`
development can still log in.

Verification order is fixed: split on `.`, parse the expiry, reject if it is in
the past, and only then `subtle.ConstantTimeCompare` the HMAC. Comparing before
validating the shape leaks structure through error timing.

The password comparison at login is also constant-time.

### 4.3 CSRF

All mutations are `POST` or `DELETE` and carry a `SameSite=Lax` cookie, which a
cross-site form post does not send. No separate CSRF token.

### 4.4 Login rate limit

In-memory, no persistence. Ten failed attempts within a rolling 20-minute window
for one client IP return `429` with a `Retry-After` header. Entries expire on
their own; there is no permanent ban and no unlock step. A successful login
clears that IP's counter.

Client IP is the **rightmost** entry of `X-Forwarded-For`. Traefik appends the
peer address it observed to whatever the client sent, so the leftmost entry is
attacker-controlled and the rightmost is not. `r.RemoteAddr` is unusable here —
behind Traefik it is always the proxy's container address, which would turn a
per-IP limit into a global one.

Known and accepted limitation: behind carrier-grade NAT the limit is shared with
every other subscriber on the same public address, so a stranger exhausting the
budget can lock the owner out for up to 20 minutes. The window self-heals and
ten attempts is generous for a mistyped password, so this is preferred over
removing the limit.

## 5. Interface

Mobile-first. Dark by default, honouring `prefers-color-scheme`. Tap targets at
least 44px. At viewports 900px and wider the card list becomes a 2–3 column
grid.

### 5.1 Login page

A centered card with a single password field (`type="password"`,
`autocomplete="current-password"`) and a submit button. Failed attempts render
an inline error. A rate-limited attempt renders how long to wait.

### 5.2 List page

```
┌──────────────────────────┐
│ mangaBookmark    [logout]│
│ [ search…              ] │
│ ( All ) ( Favourites )   │
├──────────────────────────┤
│ Continue reading         │
│ [card][card][card] →     │
├──────────────────────────┤
│ ┌────┬───────────────┐   │
│ │cvr │ Title    ASURA│   │
│ │    │ Ch 45 · NEW 47│   │
│ │    │ [Continue]★✎🗑│   │
│ └────┴───────────────┘   │
└──────────────────────────┘
```

- The main list is ordered `updated_at DESC`. That ordering is the reading
  history; no separate history view exists.
- "Continue reading" shows the top five of the same ordering in a horizontally
  scrolling strip.
- A `NEW` badge appears when `latest_chapter_num` is present and greater than
  `last_chapter_num`.
- **Continue** opens `last_chapter_url` in a new tab; it falls back to
  `series_url` when no chapter URL is stored.
- The favourite control is an htmx `POST`; the swapped-in card shows the new
  state. The list does not reorder.
- The chapter override expands an inline number input on the card. Submitting
  forces `last_chapter` and `last_chapter_num` to the entered value, which does
  move `updated_at` and therefore does reorder the list.
- Delete asks for confirmation, then htmx removes the card from the DOM.
- Search filters cards by title in the browser with roughly fifteen lines of
  JavaScript. No request is made.
- The empty list renders a short message pointing at the userscript.

### 5.3 Tabs

Switching tabs issues `GET /ui/list?tab=…` and swaps the list container,
pushing the URL so the back button works. Favourites is the same list filtered
to `favorite = true`, in the same order.

## 6. Testing

`session_test.go`:

- A signed cookie round-trips and verifies.
- An expired cookie is rejected.
- A cookie with a tampered HMAC is rejected.
- A cookie with a tampered expiry is rejected.
- A correct password logs in; a wrong one does not.
- Ten failures trip the limiter; the eleventh attempt returns `429`.
- A successful login clears the counter.
- The rightmost `X-Forwarded-For` entry is the one keyed on.

`web_test.go`:

- `GET /` without a cookie returns `200` and the login page.
- `/ui/*` without a cookie returns `401`.
- `/ui/list` with a cookie returns the list fragment; `?tab=fav` returns only
  favourites.
- Toggling favourite leaves `updated_at` unchanged.
- A chapter override changes `updated_at`.
- Deleting removes the row.
- With `WEB_PASSWORD` empty, `/` returns `404`.

Templates are parsed once at startup so a broken template fails the process
immediately rather than the first request.

## 7. Deployment

- `.env` and `.env.example` gain `WEB_PASSWORD`.
- `docker-compose.prod.yml` gains a second Traefik router label for
  `manga.violetcrown.my.id` pointing at the same service on port 8080. Both
  routers share one container; no second service, no second certificate
  resolver.
- A DNS `A`/`AAAA` record for `manga.violetcrown.my.id`.
- `DEPLOY.md` gains a section covering the DNS record, the new variable, and
  generating a password.

`ALLOWED_ORIGINS` is untouched. The website is same-origin and never triggers
CORS; only the userscript's cross-origin calls do.