Per-Reader userscript credential with UI install and rotation (#24) #32

2026-08-08T14:52:20+07:00

sulthan commented

2026-08-08 14:52:20 +07:00

Closes #24. Child of #18; based on current main (includes Postgres, Reader table, Discord OAuth).

What

Each Reader's userscript credential is derived from TOKEN_KEY, their Discord id and a token epoch (HMAC-SHA256, hex); only its SHA-256 sits in readers.token_sha256 (new token_epoch column, migration 0006). One credential authenticates the script download path and the API bearer header.

internal/token: derivation + hashing; the seed refreshes the owner's epoch-0 hash only before first rotation, so a restart can never resurrect a rotated-away credential
httpmw.Auth/ResolveReader: acting Reader resolved from the credential hash, stashed in request context; the retired global API_TOKEN resolves to the owner until API_TOKEN_GRACE_UNTIL (enforced in code, logged per use) on both the bearer and script-download paths
Userscript handler renders the bindmounted file with the resolved Reader's credential substituted for __API_TOKEN__; a legacy-path request during grace serves the derived credential, so installed devices self-migrate on their next update poll
Web UI: "Userscripts" panel — session-gated install endpoints render the script directly (credential never in markup, address bar, or a redirect), confirm-gated rotation with an atomic epoch bump + hash rewrite and a reinstall warning
Both userscripts carry __API_TOKEN__ placeholders; the committed global-token literal is removed

Design note

Credentials are derived rather than stored-random because the server must rebuild install URLs after restarts while the DB holds only hashes. HMAC output is high-entropy and unbrute-forceable; the AC's intent (unguessable, DB-leak-proof) is met.

Deploy (also in DEPLOY.md)

Add TOKEN_KEY (openssl rand -hex 32) — required; changing it later invalidates every credential.
Keep API_TOKEN + set API_TOKEN_GRACE_UNTIL for the 14-day window.
After deploy, sign in → Userscripts → reinstall both scripts on every device. This also retires the old global credential for real — its literal survives in git history (present since 0ef5286), so rotation is what kills it.

Verification

Full Go suite green against real Postgres per test; userscript JS suite 45/45
New router-level tests: per-Reader isolation (read/write/delete), grace expiry on bearer + script path, self-migrating legacy path, install serving, rotation (old cred 401/404, new cred works, install renders new credential), app page leaks no credential
Store tests: hash lookup, token info, atomic rotation with stale-epoch rejection, rotation survives restart
Live smoke of the built binary: grace acceptance logged, derived auth, substitution, restart resilience, stored hash = SHA-256 of derived credential

Closes #24. Child of #18; based on current main (includes Postgres, Reader table, Discord OAuth). ## What Each Reader's userscript credential is derived from `TOKEN_KEY`, their Discord id and a token epoch (HMAC-SHA256, hex); only its SHA-256 sits in `readers.token_sha256` (new `token_epoch` column, migration 0006). One credential authenticates the script download path and the API bearer header. - `internal/token`: derivation + hashing; the seed refreshes the owner's epoch-0 hash only before first rotation, so a restart can never resurrect a rotated-away credential - `httpmw.Auth`/`ResolveReader`: acting Reader resolved from the credential hash, stashed in request context; the retired global `API_TOKEN` resolves to the owner until `API_TOKEN_GRACE_UNTIL` (enforced in code, logged per use) on both the bearer and script-download paths - Userscript handler renders the bindmounted file with the resolved Reader's credential substituted for `__API_TOKEN__`; a legacy-path request during grace serves the derived credential, so installed devices self-migrate on their next update poll - Web UI: "Userscripts" panel — session-gated install endpoints render the script directly (credential never in markup, address bar, or a redirect), confirm-gated rotation with an atomic epoch bump + hash rewrite and a reinstall warning - Both userscripts carry `__API_TOKEN__` placeholders; the committed global-token literal is removed ## Design note Credentials are derived rather than stored-random because the server must rebuild install URLs after restarts while the DB holds only hashes. HMAC output is high-entropy and unbrute-forceable; the AC's intent (unguessable, DB-leak-proof) is met. ## Deploy (also in DEPLOY.md) 1. Add `TOKEN_KEY` (`openssl rand -hex 32`) — required; changing it later invalidates every credential. 2. Keep `API_TOKEN` + set `API_TOKEN_GRACE_UNTIL` for the 14-day window. 3. After deploy, sign in → Userscripts → reinstall both scripts on every device. This also retires the old global credential for real — its literal survives in git history (present since 0ef5286), so rotation is what kills it. ## Verification - Full Go suite green against real Postgres per test; userscript JS suite 45/45 - New router-level tests: per-Reader isolation (read/write/delete), grace expiry on bearer + script path, self-migrating legacy path, install serving, rotation (old cred 401/404, new cred works, install renders new credential), app page leaks no credential - Store tests: hash lookup, token info, atomic rotation with stale-epoch rejection, rotation survives restart - Live smoke of the built binary: grace acceptance logged, derived auth, substitution, restart resilience, stored hash = SHA-256 of derived credential

sulthan added 1 commit 2026-08-08 14:52:21 +07:00

feat(backend): per-Reader userscript credential with UI install and rotation (#24 ) 8f752ed86b

Each Reader's userscript credential is derived from TOKEN_KEY, their
Discord id and a token epoch (HMAC-SHA256, hex); only its SHA-256 sits in
readers.token_sha256, so install URLs survive restarts while a database
leak yields nothing but hashes. One credential authenticates the script
download path and the API bearer header.

- internal/token: derivation + hashing; migration 0006 adds token_epoch
- seed refreshes the owner's epoch-0 hash only before first rotation
- httpmw.Auth resolves the acting Reader from the credential hash and
  stashes it in the request context; the retired API_TOKEN resolves to
  the owner until API_TOKEN_GRACE_UNTIL, logged per use, on both the
  bearer and script-download paths
- userscript handler renders the bindmounted file with the resolved
  Reader's credential substituted for __API_TOKEN__; a legacy-path
  request during grace serves the derived credential, so devices
  self-migrate on their next update poll
- web UI: Userscripts panel with session-gated install endpoints that
  render the script directly (credential never in markup, address bar
  or a redirect) and confirm-gated rotation; atomic epoch bump + hash
  rewrite in the store
- both userscripts carry __API_TOKEN__ placeholders; the committed
  global-token literal is removed (rotating at deploy retires it for
  real — it survives in git history)
- env: TOKEN_KEY required, API_TOKEN/API_TOKEN_GRACE_UNTIL retire the
  legacy credential; docs and compose updated

sulthan merged commit 27cf0955de into main

2026-08-08 14:54:04 +07:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sulthan/mangaBookmark#32