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

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

Reviewed-on: #32
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>

backend/main.go

@@ -2,7 +2,6 @@ package main
 
 import (
 	"context"
-	"crypto/sha256"
 	"errors"
 	"log"
 	"net/http"
@@ -17,13 +16,25 @@ import (
 	"bookmarkmanager/backend/internal/httpmw"
 	"bookmarkmanager/backend/internal/latest"
 	"bookmarkmanager/backend/internal/store"
+	"bookmarkmanager/backend/internal/token"
 	"bookmarkmanager/backend/internal/userscript"
 	"bookmarkmanager/backend/internal/web"
 )
 
 // Config holds all runtime settings, sourced from environment variables.
 type Config struct {
-	Token          string
+	// Token is the retired global API token, kept only for the cutover grace
+	// window: while GraceUntil has not passed, it resolves to the owner
+	// Reader so already-installed scripts keep working. Unset after the
+	// window closes.
+	Token string
+	// TokenKey derives every Reader's userscript credential (internal/token).
+	// Required: without it no install URL can ever be built.
+	TokenKey string
+	// GraceUntil is the moment the retired global token stops resolving to
+	// the owner Reader. Zero means the token is already dead. Enforced in
+	// code on every request, not by a runbook note.
+	GraceUntil     time.Time
 	AllowedOrigins []string
 	// DatabaseURL is the Postgres connection URL; required, no default,
 	// because a wrong guess would silently start on an empty database.
@@ -147,9 +158,29 @@ func loadLatestPoll() LatestPoll {
 	return p
 }
 
+// parseGraceUntil reads the retired-token deadline. Both a bare date and a
+// full RFC3339 timestamp are accepted; an unparseable value is a
+// configuration bug, not a gracefully-degraded feature — the whole point is
+// that the window's end is enforced, so fail loud.
+func parseGraceUntil(raw string) time.Time {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return time.Time{}
+	}
+	for _, layout := range []string{time.RFC3339, "2006-01-02"} {
+		if t, err := time.Parse(layout, raw); err == nil {
+			return t
+		}
+	}
+	log.Fatalf("config: API_TOKEN_GRACE_UNTIL=%q is not a date (YYYY-MM-DD) or RFC3339 timestamp", raw)
+	return time.Time{}
+}
+
 func loadConfig() Config {
 	c := Config{
 		Token:               os.Getenv("API_TOKEN"),
+		TokenKey:            os.Getenv("TOKEN_KEY"),
+		GraceUntil:          parseGraceUntil(os.Getenv("API_TOKEN_GRACE_UNTIL")),
 		DatabaseURL:         os.Getenv("DATABASE_URL"),
 		Port:                envOr("PORT", "8080"),
 		OwnerDiscordID:      os.Getenv("OWNER_DISCORD_ID"),
@@ -183,23 +214,28 @@ func newRouter(s *store.Store, cfg Config) http.Handler {
 
 	// Outside httpmw.Auth (the updater sends no Authorization header) and
 	// outside the web UI's Discord auth (the script must be installable
-	// without a browser session). The path segment carries the token instead.
-	mux.HandleFunc("GET /u/{token}/manga-bookmark.user.js", userscript.Handler(cfg.Token, cfg.UserscriptPath))
-	mux.HandleFunc("GET /u/{token}/novel-bookmark.user.js", userscript.Handler(cfg.Token, cfg.NovelUserscriptPath))
+	// without a browser session). The path segment carries the credential
+	// instead, and the script is rendered with the resolved Reader's
+	// credential substituted in.
+	mux.HandleFunc("GET /u/{token}/manga-bookmark.user.js",
+		userscript.Handler(s, []byte(cfg.TokenKey), cfg.Token, cfg.GraceUntil, cfg.UserscriptPath))
+	mux.HandleFunc("GET /u/{token}/novel-bookmark.user.js",
+		userscript.Handler(s, []byte(cfg.TokenKey), cfg.Token, cfg.GraceUntil, cfg.NovelUserscriptPath))
 
-	h := &api.Handler{Store: s, ReaderID: s.OwnerID()}
+	h := &api.Handler{Store: s}
 	protected := http.NewServeMux()
 	protected.HandleFunc("GET /bookmarks", h.List)
 	protected.HandleFunc("PUT /bookmarks/{key}", h.Put)
 	protected.HandleFunc("DELETE /bookmarks/{key}", h.Delete)
 
-	auth := httpmw.Auth(cfg.Token, protected)
+	auth := httpmw.Auth(s, cfg.Token, cfg.GraceUntil, protected)
 	mux.Handle("/bookmarks", auth)
 	mux.Handle("/bookmarks/", auth)
 
 	// The browser UI is always registered; signing in is Discord OAuth, so
 	// there is no password to forget and no gate to leave unset.
-	wh, err := web.New(s, s.OwnerID(), cfg.Discord)
+	wh, err := web.New(s, s.OwnerID(), cfg.Discord, []byte(cfg.TokenKey),
+		cfg.UserscriptPath, cfg.NovelUserscriptPath)
 	if err != nil {
 		log.Fatalf("web handler: %v", err)
 	}
@@ -225,8 +261,8 @@ func guardEmptyUserscriptToken(next http.Handler) http.Handler {
 
 func main() {
 	cfg := loadConfig()
-	if cfg.Token == "" {
-		log.Fatal("API_TOKEN is required")
+	if cfg.TokenKey == "" {
+		log.Fatal("TOKEN_KEY is required")
 	}
 	if cfg.OwnerDiscordID == "" {
 		log.Fatal("OWNER_DISCORD_ID is required")
@@ -246,10 +282,20 @@ func main() {
 			log.Fatalf("%s is required", key)
 		}
 	}
+	if cfg.Token == "" && !cfg.GraceUntil.IsZero() {
+		log.Fatal("API_TOKEN_GRACE_UNTIL is set but API_TOKEN is not")
+	}
+	if cfg.Token != "" && cfg.GraceUntil.IsZero() {
+		log.Printf("API_TOKEN is set without API_TOKEN_GRACE_UNTIL: the retired token is dead on arrival")
+	}
 
-	// The owner's userscript token is the global API token today (issue #22);
-	// the readers row carries its SHA-256, not the token itself.
-	owner := store.Owner{DiscordID: cfg.OwnerDiscordID, TokenHash: sha256.Sum256([]byte(cfg.Token))}
+	// The owner's userscript credential is derived from TOKEN_KEY at epoch 0
+	// (internal/token); the readers row carries its SHA-256, not the
+	// credential itself.
+	owner := store.Owner{
+		DiscordID: cfg.OwnerDiscordID,
+		TokenHash: token.Hash(token.Token([]byte(cfg.TokenKey), cfg.OwnerDiscordID, 0)),
+	}
 
 	s, err := store.Open(cfg.DatabaseURL, owner)
 	if err != nil {