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/internal/token/token.go

@@ -0,0 +1,37 @@
+package token
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"strconv"
+)
+
+// Token derives one Reader's userscript credential from the deployment
+// secret, the Reader's Discord id and their token epoch.
+//
+// The credential is deterministic rather than stored random because the
+// server must be able to rebuild the install URL after a restart while the
+// database holds only hashes: a random token with no plaintext copy anywhere
+// would be unreconstructible, and keeping plaintext in memory would break
+// every install link on restart. HMAC output is high-entropy, indistinguishable
+// from random to anyone without the secret, and changes whenever the epoch
+// does — which is what rotation is. The stored form is Hash of this value,
+// so a database leak yields nothing but hashes of unguessable strings.
+func Token(key []byte, discordID string, epoch int64) string {
+	mac := hmac.New(sha256.New, key)
+	// The separator is unambiguous: discord ids are decimal snowflakes and
+	// epochs are plain integers, so no two (id, epoch) pairs can collide.
+	mac.Write([]byte(discordID))
+	mac.Write([]byte{0})
+	mac.Write([]byte(strconv.FormatInt(epoch, 10)))
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+// Hash is the SHA-256 of a credential — the only form that ever touches the
+// database (readers.token_sha256). SHA-256 rather than a password hash is
+// deliberate: these are unguessable values with nothing to brute-force, so a
+// slow hash would only add per-request cost.
+func Hash(cred string) [32]byte {
+	return sha256.Sum256([]byte(cred))
+}

backend/internal/token/token_test.go

@@ -0,0 +1,53 @@
+package token
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"testing"
+)
+
+func TestTokenDeterministicPerReaderAndEpoch(t *testing.T) {
+	key := []byte("deployment-secret")
+	a := Token(key, "reader-1", 0)
+	b := Token(key, "reader-1", 0)
+	if a != b {
+		t.Fatal("same (reader, epoch) derived different credentials")
+	}
+	if a == Token(key, "reader-2", 0) {
+		t.Fatal("different readers derived the same credential")
+	}
+	if a == Token(key, "reader-1", 1) {
+		t.Fatal("rotation epoch derived the same credential")
+	}
+}
+
+func TestTokenChangesWithSecret(t *testing.T) {
+	a := Token([]byte("key-1"), "reader-1", 0)
+	b := Token([]byte("key-2"), "reader-1", 0)
+	if a == b {
+		t.Fatal("different secrets derived the same credential")
+	}
+}
+
+func TestTokenFormat(t *testing.T) {
+	cred := Token([]byte("key"), "reader-1", 0)
+	// 32 bytes of HMAC-SHA256, hex-encoded: the length the install URL and
+	// the committed placeholder both assume.
+	if len(cred) != 64 {
+		t.Fatalf("credential length = %d, want 64", len(cred))
+	}
+	for _, c := range cred {
+		if !(c >= '0' && c <= '9' || c >= 'a' && c <= 'f') {
+			t.Fatalf("credential contains non-hex byte %q", c)
+		}
+	}
+}
+
+func TestHashIsSha256OfCredential(t *testing.T) {
+	cred := Token([]byte("key"), "reader-1", 0)
+	got := Hash(cred)
+	want := sha256.Sum256([]byte(cred))
+	if !bytes.Equal(got[:], want[:]) {
+		t.Fatal("Hash is not the SHA-256 of the credential")
+	}
+}