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/store/store.go

@@ -171,12 +171,12 @@ const seriesColumns = `s.site, s.series_id, s.title, s.series_url, s.cover,
 
 // Owner is the person running the service: the first Reader, and the only one
 // until registration exists. The seed makes sure exactly one readers row
-// matches their Discord ID, carrying the SHA-256 of their userscript token —
-// which today is the global API token.
+// matches their Discord ID, carrying the SHA-256 of their epoch-0 userscript
+// credential (derived by internal/token, not the retired global token).
 type Owner struct {
 	DiscordID string
-	// TokenHash is the SHA-256 of the userscript token; the array shape makes
-	// it a compile error to store anything that is not a hash.
+	// TokenHash is the SHA-256 of the epoch-0 credential; the array shape
+	// makes it a compile error to store anything that is not a hash.
 	TokenHash [32]byte
 }
 
@@ -189,10 +189,69 @@ type Store struct {
 	ownerID int64
 }
 
-// OwnerID returns the seeded owner Reader's id — the Reader every request
-// acts as while the global token is still the only credential.
+// OwnerID returns the seeded owner Reader's id — the Reader the retired
+// global token resolves to during the grace window, and the only Reader while
+// registration is closed.
 func (s *Store) OwnerID() int64 { return s.ownerID }
 
+// ReaderIDForTokenHash resolves the Reader whose stored credential hash
+// matches, reporting absence with ok=false. The comparison is an equality on
+// the 32-byte SHA-256 of the presented credential — never on the credential
+// itself — and the indexed lookup reveals only whether some Reader matches,
+// which the 401/200 split has to reveal anyway. An attacker's probe is the
+// hash of their guess, so even the index's prefix comparisons leak nothing
+// about the real credential.
+func (s *Store) ReaderIDForTokenHash(hash [32]byte) (int64, bool, error) {
+	var id int64
+	err := s.db.QueryRow(
+		`SELECT id FROM readers WHERE token_sha256 = $1`, hash[:]).Scan(&id)
+	if errors.Is(err, sql.ErrNoRows) {
+		return 0, false, nil
+	}
+	if err != nil {
+		return 0, false, fmt.Errorf("reader by token hash: %w", err)
+	}
+	return id, true, nil
+}
+
+// ReaderTokenInfo returns the identity halves a Reader's credential is
+// derived from (internal/token.Token): their Discord id and token epoch. The
+// web UI needs these to rebuild the install URL — the only place a credential
+// is ever produced in plaintext.
+func (s *Store) ReaderTokenInfo(readerID int64) (string, int64, error) {
+	var (
+		discordID string
+		epoch     int64
+	)
+	err := s.db.QueryRow(
+		`SELECT discord_id, token_epoch FROM readers WHERE id = $1`, readerID).
+		Scan(&discordID, &epoch)
+	if err != nil {
+		return "", 0, fmt.Errorf("reader %d token info: %w", readerID, err)
+	}
+	return discordID, epoch, nil
+}
+
+// RotateToken bumps a Reader's token epoch and rewrites the stored hash in
+// one statement, so the new hash always matches the new epoch. expectedEpoch
+// is the epoch the caller derived newHash for (ReaderTokenInfo + 1); a
+// concurrent rotation — or an unknown reader — leaves the row untouched and
+// is reported as an error rather than silently succeeding.
+func (s *Store) RotateToken(readerID, expectedEpoch int64, newHash [32]byte) error {
+	var epoch int64
+	err := s.db.QueryRow(`
+		UPDATE readers SET token_epoch = token_epoch + 1, token_sha256 = $3
+		WHERE id = $1 AND token_epoch = $2
+		RETURNING token_epoch`, readerID, expectedEpoch, newHash[:]).Scan(&epoch)
+	if errors.Is(err, sql.ErrNoRows) {
+		return fmt.Errorf("rotate token for reader %d: concurrent rotation or unknown reader", readerID)
+	}
+	if err != nil {
+		return fmt.Errorf("rotate token for reader %d: %w", readerID, err)
+	}
+	return nil
+}
+
 // readersMigration is the version that creates the readers table. The owner
 // seed runs between two migrate passes, so that the run-once migration which
 // attaches existing bookmarks (0004) finds the owner row.
@@ -217,6 +276,10 @@ func Open(url string, owner Owner) (*Store, error) {
 		db.Close()
 		return nil, fmt.Errorf("migrate schema: %w", err)
 	}
+	// The owner row must exist before 0004 attaches the existing bookmarks to
+	// it. The hash refresh is a separate statement after all migrations: the
+	// token_epoch column 0006 adds does not exist yet at this point, and the
+	// refresh only ever concerns rows that have never been rotated.
 	if err := seedOwner(db, owner); err != nil {
 		db.Close()
 		return nil, fmt.Errorf("seed owner: %w", err)
@@ -225,6 +288,10 @@ func Open(url string, owner Owner) (*Store, error) {
 		db.Close()
 		return nil, fmt.Errorf("migrate: %w", err)
 	}
+	if err := refreshOwnerToken(db, owner); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("refresh owner token: %w", err)
+	}
 	var ownerID int64
 	if err := db.QueryRow(
 		`SELECT id FROM readers WHERE discord_id = $1`, owner.DiscordID).Scan(&ownerID); err != nil {
@@ -234,19 +301,36 @@ func Open(url string, owner Owner) (*Store, error) {
 	return &Store{db: db, ownerID: ownerID}, nil
 }
 
-// seedOwner makes sure the configured owner exists as exactly one readers row,
-// and keeps its token hash current on every start: rotating the userscript
-// token must refresh the hash, or the stored credential goes stale.
+// seedOwner makes sure the configured owner exists as exactly one readers row.
+// The hash is only ever written here for a brand-new row; existing rows keep
+// what they have until refreshOwnerToken decides otherwise, so the seed can
+// never clobber a rotation.
 func seedOwner(db *sql.DB, o Owner) error {
 	if _, err := db.Exec(`
 		INSERT INTO readers (discord_id, token_sha256) VALUES ($1, $2)
-		ON CONFLICT (discord_id) DO UPDATE SET token_sha256 = EXCLUDED.token_sha256`,
+		ON CONFLICT (discord_id) DO NOTHING`,
 		o.DiscordID, o.TokenHash[:]); err != nil {
 		return fmt.Errorf("seed owner: %w", err)
 	}
 	return nil
 }
 
+// refreshOwnerToken brings a never-rotated owner row's hash current with the
+// configured credential. That is the cutover path: a database seeded under
+// the retired global token still carries its hash at epoch 0, and the
+// epoch-0 derivation is the caller's TokenHash. A rotated row (epoch > 0) is
+// left alone — a restart must not resurrect the old credential by
+// overwriting the hash a rotation wrote.
+func refreshOwnerToken(db *sql.DB, o Owner) error {
+	if _, err := db.Exec(`
+		UPDATE readers SET token_sha256 = $2
+		WHERE discord_id = $1 AND token_epoch = 0`,
+		o.DiscordID, o.TokenHash[:]); err != nil {
+		return fmt.Errorf("refresh owner token: %w", err)
+	}
+	return nil
+}
+
 // migrate applies every embedded migration this database has not recorded, in
 // filename order, each in its own transaction. upto caps the highest version
 // applied; 0 means all. Files are named "<version>_<name>.sql" and are