feat(allanime): Implement dynamic per-epoch key derivation for AllAnime API

- Introduced a new key derivation mechanism that fetches the epoch and partB from the referer page, and derives the AES key using a mask from the entry bundle.
- Updated the AllAnimeClient to use the derived keys for both the aaReq token and decrypting the `tobeparsed` blob.
- Refactored tests to ensure proper key fetching and caching behavior, including regression tests for the new key derivation process.
- Adjusted transport methods to utilize the new key management, ensuring compatibility with the updated AllAnime API.
- Added comprehensive tests to validate the key derivation process and ensure no network calls are made when a valid cached key is available.
- Updated documentation and comments to reflect the changes in key management and API interaction.

Author: alvarorichard

internal/scraper/providers/allanime/aareq_test.go

@@ -30,11 +30,10 @@ import (
 // aaReqPayload mirrors the JSON the token wraps, so the test can assert each
 // field the server checks.
 type aaReqPayload struct {
-	V       int    `json:"v"`
-	TS      int64  `json:"ts"`
-	Epoch   int    `json:"epoch"`
-	BuildID string `json:"buildId"`
-	QH      string `json:"qh"`
+	V     int    `json:"v"`
+	TS    int64  `json:"ts"`
+	Epoch int    `json:"epoch"`
+	QH    string `json:"qh"`
 }
 
 // decryptAAReqAsServer performs the exact validation an AllAnime edge does:
@@ -70,26 +69,25 @@ func TestBuildAAReq_ServerCanValidateEntireContract(t *testing.T) {
 	const qh = allAnimePersistedQueryHash
 	const now = int64(1751990400000) // fixed wall clock (ms)
 
-	token, err := buildAAReqAt(qh, now)
+	token, err := buildAAReqAt(qh, allAnimeKey, testAAEpoch, now)
 	require.NoError(t, err)
 
 	payload, iv := decryptAAReqAsServer(t, token)
 
 	// Payload fields the server checks.
 	assert.Equal(t, 1, payload.V, "protocol version field")
-	assert.Equal(t, 4128, payload.Epoch, "epoch must be the fixed 4128 constant")
-	assert.Equal(t, "9", payload.BuildID, "buildId must be the fixed \"9\" constant")
+	assert.Equal(t, 4128, payload.Epoch, "epoch must be the per-epoch value bound into the token")
 	assert.Equal(t, qh, payload.QH, "qh must be the persisted-query hash")
 
 	// Timestamp must be floored to the 5-minute window.
 	wantTS := (now / aaReqWindowMillis) * aaReqWindowMillis
 	assert.Equal(t, wantTS, payload.TS, "ts must be floored to the 5-minute bucket")
 
-	// The IV on the wire must equal SHA-256("4128:9:<qh>:<ts>")[:12] — the
+	// The IV on the wire must equal SHA-256("<epoch>:<qh>:<ts>")[:12] — the
 	// server re-derives it from the decrypted payload and compares.
-	seed := fmt.Sprintf("4128:9:%s:%d", qh, payload.TS)
+	seed := fmt.Sprintf("%s:%s:%d", testAAEpoch, qh, payload.TS)
 	sum := sha256.Sum256([]byte(seed))
-	assert.Equal(t, sum[:12], iv, "IV must be the first 12 bytes of SHA-256 over the fixed seed")
+	assert.Equal(t, sum[:12], iv, "IV must be the first 12 bytes of SHA-256 over the epoch:qh:ts seed")
 }
 
 func TestBuildAAReq_DeterministicWithinWindow(t *testing.T) {
@@ -100,9 +98,9 @@ func TestBuildAAReq_DeterministicWithinWindow(t *testing.T) {
 	// Two calls in the same 5-minute bucket must produce byte-identical tokens
 	// (GCM with a fixed key+iv+plaintext is deterministic). This is what lets
 	// the server cache/verify without clock skew within the window.
-	a, err := buildAAReqAt(qh, base+1000)
+	a, err := buildAAReqAt(qh, allAnimeKey, testAAEpoch, base+1000)
 	require.NoError(t, err)
-	b, err := buildAAReqAt(qh, base+aaReqWindowMillis-1)
+	b, err := buildAAReqAt(qh, allAnimeKey, testAAEpoch, base+aaReqWindowMillis-1)
 	require.NoError(t, err)
 	assert.Equal(t, a, b, "same 5-minute window ⇒ identical token")
 }
@@ -115,9 +113,9 @@ func TestBuildAAReq_ChangesAcrossWindows(t *testing.T) {
 	// Crossing into the next window changes ts, which changes both the payload
 	// and the derived IV, so the token must differ — a stale token would be
 	// rejected by the server.
-	a, err := buildAAReqAt(qh, base)
+	a, err := buildAAReqAt(qh, allAnimeKey, testAAEpoch, base)
 	require.NoError(t, err)
-	b, err := buildAAReqAt(qh, base+aaReqWindowMillis)
+	b, err := buildAAReqAt(qh, allAnimeKey, testAAEpoch, base+aaReqWindowMillis)
 	require.NoError(t, err)
 	assert.NotEqual(t, a, b, "next 5-minute window ⇒ different token")
 }
@@ -129,9 +127,9 @@ func TestBuildAAReq_BoundToQueryHash(t *testing.T) {
 	// The qh is bound into both the payload and the IV seed, so two different
 	// hashes must yield different tokens — the token cannot be replayed for a
 	// different query.
-	a, err := buildAAReqAt("d405d0edd690624b66baba3068e0edc3ac90f1597d898a1ec8db4e5c43c00fec", now)
+	a, err := buildAAReqAt("d405d0edd690624b66baba3068e0edc3ac90f1597d898a1ec8db4e5c43c00fec", allAnimeKey, testAAEpoch, now)
 	require.NoError(t, err)
-	b, err := buildAAReqAt("0000000000000000000000000000000000000000000000000000000000000000", now)
+	b, err := buildAAReqAt("0000000000000000000000000000000000000000000000000000000000000000", allAnimeKey, testAAEpoch, now)
 	require.NoError(t, err)
 	assert.NotEqual(t, a, b, "token must be bound to the query hash")
 }
@@ -141,7 +139,7 @@ func TestBuildAAReq_ProductionUsesLiveClock(t *testing.T) {
 	// The exported wrapper must produce a currently-valid token (non-empty,
 	// server-decryptable) using the real clock — guards against the wrapper
 	// being accidentally short-circuited.
-	token, err := buildAAReq(allAnimePersistedQueryHash)
+	token, err := buildAAReq(allAnimePersistedQueryHash, &aaKeys{key: allAnimeKey, epoch: testAAEpoch})
 	require.NoError(t, err)
 	require.NotEmpty(t, token)
 	payload, _ := decryptAAReqAsServer(t, token)

internal/scraper/providers/allanime/client.go

@@ -2,41 +2,36 @@
 package allanime
 
 import (
+	"bytes"
 	"net/http"
 	"regexp"
 	"sync"
+	"time"
 
 	"github.com/alvarorichard/Goanime/internal/scraper/netx"
 	"github.com/alvarorichard/Goanime/internal/util"
 )
 
 const (
 	// AllAnimeReferer is the Referer/Origin AllAnime binds its API to. Rotated
-	// 2026-07-08 to youtu-chan.com (ani-cli PR #1772); requests carrying the old
-	// allmanga.to referer now receive a stripped response.
-	AllAnimeReferer = "https://youtu-chan.com"
-	AllAnimeBase    = "allanime.day"
-	AllAnimeAPI     = "https://api.allanime.day/api"
-
-	// allAnimeKeyHex is the AES-256 key (32 bytes, hex) used for BOTH the
-	// aaReq request-signing token and the `tobeparsed` response decryption.
-	// Rotated 2026-07-08 (ani-cli PR #1772); the old SHA-256("Xot36i3lK3:v1")
-	// derivation no longer matches, so the key is now carried literally.
-	allAnimeKeyHex = "22196fa6afca95309fdabe9a3534b87cd2454e50efeabfcbdbdfd3de678b3982"
+	// 2026-07-22 to mkissa.to (ani-cli PR #1779); requests carrying the old
+	// youtu-chan.com referer now receive a stripped response.
+	AllAnimeReferer = "https://mkissa.to"
+	// AllAnimeBase is the host that internal ("--"-encoded) source URLs resolve
+	// to (e.g. the /clock.json embeds). Unchanged by the mkissa migration.
+	AllAnimeBase = "allanime.day"
+	// AllAnimeAPI is the GraphQL endpoint. Moved off api.allanime.day to the
+	// mkissa mirror 2026-07-22 (ani-cli PR #1779).
+	AllAnimeAPI = "https://api.mkissa.net/api"
 
 	// allAnimePersistedQueryHash is the Apollo persistedQuery sha256 for the
 	// `episode { sourceUrls / tobeparsed }` query, and doubles as the `qh`
-	// field bound into the aaReq token.
-	allAnimePersistedQueryHash = "d405d0edd690624b66baba3068e0edc3ac90f1597d898a1ec8db4e5c43c00fec"
+	// field bound into the aaReq token. Rotated 2026-07-22 (ani-cli PR #1779).
+	allAnimePersistedQueryHash = "f4662f4b7510b26795dd53ef824a0bf1740fbbc5d1273fab18222ac831bca8d0"
 
 	// allAnimePersistedQueryOrigin is the Origin the GET path must send.
 	// AllAnime returns a stripped (no `tobeparsed`) response for any other Origin.
-	allAnimePersistedQueryOrigin = "https://youtu-chan.com"
-
-	// allAnimeAAReqEpoch and allAnimeAAReqBuildID are fixed protocol constants
-	// bound into the aaReq token's payload and IV derivation (ani-cli PR #1772).
-	allAnimeAAReqEpoch   = "4128"
-	allAnimeAAReqBuildID = "9"
+	allAnimePersistedQueryOrigin = "https://mkissa.to"
 )
 
 // Pre-compiled regexes for AllAnime scraper (avoid per-call compilation)
@@ -52,6 +47,12 @@ type AllAnimeClient struct {
 	referer   string
 	apiBase   string
 	userAgent string
+
+	// keyMu guards the cached per-epoch AES material (keys/keysExp). The key is
+	// scraped from the mkissa CDN bundle (fetchAAKeys) and reused until keysExp.
+	keyMu   sync.Mutex
+	keys    *aaKeys
+	keysExp time.Time
 }
 
 // allAnimeClientInstance is a singleton for connection reuse
@@ -74,12 +75,15 @@ func NewAllAnimeClient() *AllAnimeClient {
 }
 
 // NewClientForTest returns a client whose API base points at a test server.
-// Only for tests.
+// Only for tests. A fixed fixture key is injected so the client never scrapes
+// the live mkissa key bundle over the network during tests.
 func NewClientForTest(serverURL string) *AllAnimeClient {
 	return &AllAnimeClient{
 		client:    util.GetFastClient(),
 		referer:   AllAnimeReferer,
 		apiBase:   serverURL,
 		userAgent: netx.UserAgent,
+		keys:      &aaKeys{key: bytes.Repeat([]byte{0x2a}, 32), epoch: "0"},
+		keysExp:   time.Now().Add(time.Hour),
 	}
 }

internal/scraper/providers/allanime/client_test.go

@@ -29,13 +29,33 @@ import (
 // Test helpers
 // ---------------------------------------------------------------------------
 
-// newTestClient builds an AllAnimeClient pointed at the given httptest server.
+// allAnimeKey / allAnimeKeyHex are a FIXED fixture key for the offline crypto
+// round-trip tests. Production derives the real key dynamically per epoch (see
+// fetchAAKeys); these only need to be a valid 32-byte AES-256 key shared by the
+// encrypt and decrypt sides of the tests.
+const allAnimeKeyHex = "22196fa6afca95309fdabe9a3534b87cd2454e50efeabfcbdbdfd3de678b3982"
+
+var allAnimeKey = func() []byte {
+	k, err := hex.DecodeString(allAnimeKeyHex)
+	if err != nil || len(k) != 32 {
+		panic("allanime test: bad fixture key")
+	}
+	return k
+}()
+
+// testAAEpoch is the fixture epoch the injected key is paired with.
+const testAAEpoch = "4128"
+
+// newTestClient builds an AllAnimeClient pointed at the given httptest server,
+// with the fixture key injected so getAAKeys never scrapes the live bundle.
 func newTestClient(serverURL string) *AllAnimeClient {
 	return &AllAnimeClient{
 		client:    util.GetFastClient(),
 		referer:   AllAnimeReferer,
 		apiBase:   serverURL,
 		userAgent: netx.UserAgent,
+		keys:      &aaKeys{key: allAnimeKey, epoch: testAAEpoch},
+		keysExp:   time.Now().Add(time.Hour),
 	}
 }
 
@@ -262,8 +282,8 @@ func TestAllAnimeGetLinksClassifiesHTMLBodyAsSourceUnavailable(t *testing.T) {
 
 func TestAllAnimeKeyMatchesOpenSSL(t *testing.T) {
 	t.Parallel()
-	// Literal 32-byte hex key, rotated 2026-07-08 (ani-cli PR #1772). It is no
-	// longer derived from a passphrase; it must equal the constant verbatim.
+	// The production key is now derived per epoch (fetchAAKeys); this pins the
+	// offline test fixture key as a valid 32-byte AES-256 key.
 	assert.Equal(t, allAnimeKeyHex, hex.EncodeToString(allAnimeKey))
 }
 
@@ -393,7 +413,7 @@ func TestDecodeToBeParsedRoundTrip(t *testing.T) {
 	plaintext := `{"data":{"episode":{"sourceUrls":[{"sourceUrl":"--504c4c484b021717","sourceName":"TestProvider"}]}}}`
 	blob := encryptToBeParsed(t, plaintext)
 
-	sources, err := decodeToBeParsed(blob)
+	sources, err := decodeToBeParsed(blob, allAnimeKey)
 	require.NoError(t, err)
 	require.Len(t, sources, 1)
 	assert.Equal(t, "TestProvider", sources[0].sourceName)
@@ -409,7 +429,7 @@ func TestDecodeToBeParsedMultipleSources(t *testing.T) {
 	]}}}`
 	blob := encryptToBeParsed(t, plaintext)
 
-	sources, err := decodeToBeParsed(blob)
+	sources, err := decodeToBeParsed(blob, allAnimeKey)
 	require.NoError(t, err)
 	require.Len(t, sources, 3)
 	assert.Equal(t, "Provider1", sources[0].sourceName)
@@ -421,14 +441,14 @@ func TestDecodeToBeParsedMultipleSources(t *testing.T) {
 func TestDecodeToBeParsedTooShort(t *testing.T) {
 	t.Parallel()
 	blob := base64.StdEncoding.EncodeToString([]byte("short"))
-	_, err := decodeToBeParsed(blob)
+	_, err := decodeToBeParsed(blob, allAnimeKey)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "too short")
 }
 
 func TestDecodeToBeParsedBadBase64(t *testing.T) {
 	t.Parallel()
-	_, err := decodeToBeParsed("!!!not-base64!!!")
+	_, err := decodeToBeParsed("!!!not-base64!!!", allAnimeKey)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "base64")
 }
@@ -437,7 +457,7 @@ func TestDecodeToBeParsedExactly12BytesNoCiphertext(t *testing.T) {
 	t.Parallel()
 	// 12 bytes < 29 (GCM minimum: 1 version + 12 nonce + 16 tag) → too short
 	blob := base64.StdEncoding.EncodeToString(make([]byte, 12))
-	_, err := decodeToBeParsed(blob)
+	_, err := decodeToBeParsed(blob, allAnimeKey)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "too short")
 }
@@ -446,7 +466,7 @@ func TestDecodeToBeParsedExactly13BytesMinimal(t *testing.T) {
 	t.Parallel()
 	// 13 bytes < 29 → too short
 	blob := base64.StdEncoding.EncodeToString(make([]byte, 13))
-	_, err := decodeToBeParsed(blob)
+	_, err := decodeToBeParsed(blob, allAnimeKey)
 	assert.Error(t, err)
 	assert.Contains(t, err.Error(), "too short")
 }
@@ -456,7 +476,7 @@ func TestDecodeToBeParsedExactly28BytesTooShort(t *testing.T) {
 	// GCM minimum is 29 bytes (1 version + 12 nonce + 16 tag + 0 plaintext).
 	// 28 bytes trips the length guard before any crypto runs.
 	blob := base64.StdEncoding.EncodeToString(make([]byte, 28))
-	_, err := decodeToBeParsed(blob)
+	_, err := decodeToBeParsed(blob, allAnimeKey)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "too short")
 }
@@ -466,7 +486,7 @@ func TestDecodeToBeParsedAllZeroBytesFailsAuth(t *testing.T) {
 	// A 29-byte all-zero blob passes the length guard but is not a valid GCM
 	// message (the zero tag won't authenticate), so Open rejects it.
 	blob := base64.StdEncoding.EncodeToString(make([]byte, 29))
-	_, err := decodeToBeParsed(blob)
+	_, err := decodeToBeParsed(blob, allAnimeKey)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "GCM decrypt failed")
 }
@@ -487,7 +507,7 @@ func TestDecodeToBeParsedCorruptedCiphertext(t *testing.T) {
 	}
 	corruptBlob := base64.StdEncoding.EncodeToString(raw)
 
-	_, err = decodeToBeParsed(corruptBlob)
+	_, err = decodeToBeParsed(corruptBlob, allAnimeKey)
 	require.Error(t, err, "tampered ciphertext must not produce a usable result")
 	assert.Contains(t, err.Error(), "GCM decrypt failed",
 		"GCM authenticates — tampering must be rejected at the cipher layer")
@@ -503,7 +523,7 @@ func TestDecodeToBeParsedTruncatedCiphertext(t *testing.T) {
 	// 16 bytes < 29 minimum → "too short" before GCM is even attempted
 	truncated := base64.StdEncoding.EncodeToString(raw[:16])
 
-	_, err = decodeToBeParsed(truncated)
+	_, err = decodeToBeParsed(truncated, allAnimeKey)
 	assert.Error(t, err, "truncated blob should fail")
 }
 
@@ -513,7 +533,7 @@ func TestDecodeToBeParsedRegexFallbackSourceUrlBeforeSourceName(t *testing.T) {
 	plaintext := `[{"sourceUrl":"--5959","sourceName":"Fallback1"}]`
 	blob := encryptToBeParsed(t, plaintext)
 
-	sources, err := decodeToBeParsed(blob)
+	sources, err := decodeToBeParsed(blob, allAnimeKey)
 	require.NoError(t, err)
 	require.Len(t, sources, 1)
 	assert.Equal(t, "Fallback1", sources[0].sourceName)
@@ -526,7 +546,7 @@ func TestDecodeToBeParsedRegexFallbackReversedFieldOrder(t *testing.T) {
 	plaintext := `[{"sourceName":"Reversed","sourceUrl":"--0a0b"}]`
 	blob := encryptToBeParsed(t, plaintext)
 
-	sources, err := decodeToBeParsed(blob)
+	sources, err := decodeToBeParsed(blob, allAnimeKey)
 	require.NoError(t, err)
 	require.Len(t, sources, 1)
 	assert.Equal(t, "Reversed", sources[0].sourceName)
@@ -542,7 +562,7 @@ func TestDecodeToBeParsedDeterministicWithFixedNonce(t *testing.T) {
 	blob2 := encryptToBeParsedWithNonce(t, plaintext, nonce)
 	assert.Equal(t, blob1, blob2, "same nonce + plaintext must produce same blob")
 
-	sources, err := decodeToBeParsed(blob1)
+	sources, err := decodeToBeParsed(blob1, allAnimeKey)
 	require.NoError(t, err)
 	require.Len(t, sources, 1)
 	assert.Equal(t, "Det", sources[0].sourceName)
@@ -558,7 +578,7 @@ func TestDecodeToBeParsedLargePayload(t *testing.T) {
 	plaintext := `{"data":{"episode":{"sourceUrls":[` + strings.Join(entries, ",") + `]}}}`
 	blob := encryptToBeParsed(t, plaintext)
 
-	sources, err := decodeToBeParsed(blob)
+	sources, err := decodeToBeParsed(blob, allAnimeKey)
 	require.NoError(t, err)
 	assert.Len(t, sources, 100)
 }
@@ -573,7 +593,7 @@ func TestExtractSourceURLsHandlesToBeParsed(t *testing.T) {
 	blob := encryptToBeParsed(t, plaintext)
 	response := buildToBeParsedResponse(blob)
 
-	urls := NewAllAnimeClient().extractSourceURLs(response)
+	urls := newTestClient("").extractSourceURLs(response)
 	require.Len(t, urls, 1)
 	assert.Equal(t, "https://allanime.day/clock.json", urls[0])
 }
@@ -614,7 +634,7 @@ func TestExtractSourceURLsToBeParsedFallsBackToStandard(t *testing.T) {
 	// Response has "tobeparsed" but with garbage blob; should fall back to sourceUrls
 	response := `{"data":{"episode":{"tobeparsed":"not-valid-base64","sourceUrls":[{"sourceUrl":"--0809","sourceName":"Fallback"}]}}}`
 
-	urls := NewAllAnimeClient().extractSourceURLs(response)
+	urls := newTestClient("").extractSourceURLs(response)
 	require.Len(t, urls, 1)
 	assert.Equal(t, "01", urls[0])
 }
@@ -1868,7 +1888,7 @@ func TestDecodeToBeParsedCrossValidateWithOpenSSL(t *testing.T) {
 	blob := base64.StdEncoding.EncodeToString(payload)
 
 	// Decrypt using production code
-	sources, err := decodeToBeParsed(blob)
+	sources, err := decodeToBeParsed(blob, allAnimeKey)
 	require.NoError(t, err)
 	require.Len(t, sources, 1)
 	assert.Equal(t, "TestProvider", sources[0].sourceName)
@@ -1970,7 +1990,7 @@ func TestDecodeToBeParsedNoPanicOnMalformed(t *testing.T) {
 		t.Run(fmt.Sprintf("input_%d", i), func(t *testing.T) {
 			t.Parallel()
 			// Must not panic
-			_, _ = decodeToBeParsed(input)
+			_, _ = decodeToBeParsed(input, allAnimeKey)
 		})
 	}
 }