test(stalker): enforce portal auth in the mock and cover the full-portal flow (#1324)

* test(stalker): enforce portal auth in the mock and cover the full-portal flow

The mock server implemented neither get_profile nor get_events and
validated no auth at all, and the e2e suite imported the portal through
/portal.php — which the app classifies as a *simple* portal. The entire
authenticated branch (handshake, token, watchdog, re-auth) therefore had
zero coverage, right before a series of PRs that reworks exactly that.

Mock server:
- serve the canonical /stalker_portal/server/load.php endpoint, which
  enforces the Bearer token and the Infomir MAC format like the real
  middleware; /portal.php stays tolerant so the existing suite keeps
  covering the simple-portal branch
- auth-store.ts models the parts of Stalker 4.9.35 a client can get
  wrong: plain-text auth failures with HTTP 200, a handshake that is not
  yet a session, idempotent token re-presentation, and permanent
  device_id pinning (including the blank-after-pinned lockout)
- add get_profile (status 0/1/2, device conflict, block_msg) and the
  get_events watchdog; profile advertises watchdog_timeout/timeslot
- new login-required scenario MAC and POST /invalidate-session so tests
  can force a mid-session token loss
- the /stalker proxy route now forwards the token as a Bearer header and
  wraps auth failures in the { payload } envelope, matching web-backend

Also moves extractMac into request-mac.ts: importing it from the
categories handler dragged the whole data generator into any consumer,
which broke unit tests on the workspace alias.

E2E: new stalker-auth.e2e.ts asserts handshake precedes get_profile
precedes content, that content requests carry the token while the
handshake does not, that the plain-text failure body is never rendered,
and that the client re-authenticates after the portal drops the session.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(mock): address CodeQL findings in the new portal auth code

Two genuine defects in the code this PR added:
- readBearerToken's /Bearer\s+(.*)$/ backtracks polynomially on
  "bearer" followed by a long run of spaces; require the token to start
  with a non-space character instead
- the /stalker proxy route read query params as strings without
  narrowing, so a repeated key (?url=a&url=b) arrives as an array and
  String.prototype.includes silently changes meaning

The remaining three alerts (missing rate limiting x2, sensitive data in
a GET query) are web-service hygiene rules aimed at internet-facing
services. The mock servers bind to localhost, serve fabricated data,
ship in no artifact, and deliberately mirror the real backend proxy's
token-in-query contract; a rate limiter would break the E2E suite that
hammers them. Exclude only those two apps from analysis via a documented
CodeQL config; every shipped path keeps full coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(mock): tighten portal-auth fidelity per review

Review follow-up on #1324 (Greptile 2xP1, Codex 3xP2), all valid:

- adoptToken only accepts tokens the mock actually issued (or the
  already-bound one). The stock server pins any presented Bearer —
  handshake is stateless there — but a fixture that does the same
  cannot catch a client with a broken token pipeline; documented as a
  deliberate strictness divergence.
- /invalidate-session clears tokens but keeps pinned device identity:
  losing a token never unpins device_id on a real portal, so changed
  identity after re-auth must still hit the device-conflict branch.
- The login-required scenario gates on actual do_auth completion
  instead of auth_second_step: the app sends auth_second_step=1 on its
  very first get_profile, so the parameter check was trivially
  bypassed and the status-2 flow never exercised. do_auth is now the
  faithful boolean step (non-empty credentials -> {js:true}, recorded;
  empty -> {js:false}).
- /server/load.php — the second URL shape isFullStalkerPortal
  recognizes — is now served and enforced, directly and through the
  /stalker proxy predicate, so full-portal tests cannot silently fall
  into the tolerant branch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(stalker): prove content actually reloads after re-authentication

Review follow-up on #1324 (Codex P2, valid — the "passes for the wrong
reason" class): the re-auth test only polled for a fresh handshake and
a negative body-text assertion, both of which pass even if the original
content request is never replayed or stays unauthorized. Capture the
content token from the initial import, then assert a post-invalidation
CONTENT request goes out under a DIFFERENT token and that the ITV
categories actually render — the mock only answers content for an
adopted token, so this proves the new token round-tripped through
get_profile. Verified against a live mock that the token genuinely
rotates (old token -> "Authorization failed.", new token -> content).

Also documents the second Codex P2: the mock is deliberately strict on
/server/load.php (a real portal enforces auth there); the import dialog
vs session predicate divergence is a separate app bug the strict
endpoint will let a later PR cover.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(stalker): serialize the portal specs and bind mocks to loopback

Review follow-up on #1324 (Codex, 4xP2):

- Parallel-reset race: under the workspace `fullyParallel` preset the new
  auth file ran concurrently with stalker.e2e.ts against one shared mock
  process, and each `beforeEach` wiped global state (sessions, favorites)
  mid-assertion in the other. Reproduced locally: both suites green in
  isolation, two failures when run together. Merged the auth tests into
  stalker.e2e.ts and pinned the file to `mode: 'serial'`, which also
  removes the pre-existing race between that file's own tests. 19/19
  green across three consecutive runs.
- Watchdog was recorded but never asserted, so the suite would stay green
  if the full-portal workflow stopped pinging or dropped its token —
  `sendWatchdogPing` swallows failures. Now polls for an authenticated
  `get_events`.
- Both mock servers listened on every interface (stalker: `listen(PORT)`
  with no host; xtream: an explicit `0.0.0.0` default), which made the
  CodeQL exclusion's "binds to localhost" rationale untrue. Both now
  default to `127.0.0.1` with a `HOST` opt-in, and the config comment
  states plainly what the directory-wide ignore trades away.
- Documented that the login-required scenario is HTTP-level only for now:
  the client's `do_auth` path is dormant and sends empty credentials, so
  the fixture is waiting on that client-side work rather than claiming
  end-to-end coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(stalker): force a real auth failure before asserting it stays hidden

Review follow-up on #1324 (Codex 2xP2 + 1xP3), all valid:

- The "never surfaces the plain-text auth failure" test only performed a
  successful import, so its negative body assertions were vacuous. It now
  imports with a MAC outside the Infomir OUI: the strict endpoint answers
  get_profile with a bare {status:1}, no token is ever adopted, and every
  content request keeps returning "Authorization failed." Unlike an
  invalidated session this cannot be repaired by the client retry, so the
  failure is genuinely observed (asserted directly against the proxy) and
  only then checked for not leaking into the UI.
- docs/architecture/xtream-mock-server.md still documented the wildcard
  bind that 4b31f7167 replaced with a loopback default; it now states the
  new default and the HOST=0.0.0.0 opt-in needed for phone/STB/container.
- Removed a dangling "Known app-side gap: the" fragment left in the
  stalker mock README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(mock): scope /reset by MAC so parallel specs stop wiping each other

The re-authentication test passed locally but failed all three CI
attempts: no request carried a token, because self-hosted.e2e.ts issues
a GLOBAL `POST /reset` against the same mock from a parallel Playwright
worker, destroying the session mid-import. Running only stalker.e2e.ts
locally never triggered it.

Serializing within one file (4b31f7167) could not fix this — the
interference is between files. Mock state is per-MAC, so `/reset` now
accepts `?macAddress=` and clears only that MAC's data, favorites,
session and watchdog counters; the unscoped form is kept for callers
that own the whole server. Both spec files now reset only the MACs they
own, so no worker can disturb another.

Verified: a scoped reset of one MAC leaves another MAC's session intact
(and its own dies), and stalker.e2e.ts + self-hosted.e2e.ts run together
23/23 green — the combination that reproduced the CI failure.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(e2e): scope the last global Stalker reset in sources-pwa helpers

Completes 3a93fef0f: that commit scoped self-hosted.e2e.ts but missed
resetPwaMockServers, which still wiped the whole Stalker fixture from a
third spec file. Scope it to the two MACs this suite owns.

The auth tests use dedicated MACs no sibling touches, so portal sessions
— the fragile state — can no longer be cleared by a parallel worker.
Content MACs still overlap between files, which is harmless: that data is
regenerated deterministically from the same seed.

Verified with the full interfering set running together:
stalker.e2e.ts + self-hosted.e2e.ts + sources-pwa.e2e.ts, 26/26 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(stalker): await the first authenticated content request

The re-auth test kept failing on CI (3/3 attempts) with an undefined
token while passing locally. My earlier diagnosis — a sibling spec's
global /reset — was wrong: the failure survived the scoped-reset fix.

Real cause is a race in the test itself. `addFullStalkerPortal` only
awaits the route change, so on a slower runner the first authenticated
content request has not been recorded yet when the token is read; the
sibling test that passes happens to await `.category-item` first. Poll
for a content request carrying a token before capturing it.

The scoped-reset work stands on its own merits (cross-file resets were
a real hazard), it just was not what broke this test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(stalker): drop serial mode, batch resets, cover the auth handlers

Review round on a44f8135f plus a stability regression I introduced.

Codex, both valid:
- The proxy route stripped `token` from the forwarded query, so
  `handshake` never saw a presented token and the idempotent-handshake
  behaviour I documented was unreachable through the PWA path. The real
  backend forwards every param except `targetId` *and* sets the header;
  match it. Verified through the proxy: re-handshake now returns the
  same token with not_valid 0.
- The login-required scenario had no committed test, so the README claim
  was unbacked. Added auth-handlers.spec.ts (status 2 -> do_auth ->
  profile, MAC-format rejection, device conflict, idempotent handshake,
  watchdog). Handlers are called directly because the dispatcher pulls in
  the faker-based generator, which this project's Jest cannot transform.
- Sibling suites now own disjoint MACs (00:1A:79:5F:*) instead of
  sharing the Stalker suite's, so no reset can reach another suite's
  state at all.

Stability: a baseline run of master passed 23/23 first try while this
branch failed a different test each run, so the flakiness was mine.
`mode: 'serial'` was a stand-in for isolation that per-MAC scoping now
provides properly, and it amplified every flake by aborting the rest of
the file; removed. `beforeEach` also fired seven sequential resets — the
endpoint now accepts repeated `macAddress` params so a suite clears all
of its MACs in one request. Added a retrying POST helper after an
ECONNRESET on a control call.

Verified: three consecutive runs of stalker + self-hosted + sources-pwa,
26/26 each; 28 mock unit tests; lint clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(stalker): restore serial mode for the shared-scenario file

Review follow-up (Codex P2), valid: the previous commit removed
`mode: 'serial'` while every `beforeEach` still resets all OWNED_MACS,
so under fullyParallel one test in this file could clear another's data
or session mid-run.

Of the two suggested fixes, serialize rather than give each test its own
MAC: the tests here are written against scenario fixtures (default,
minimal, embedded-series) whose shapes the assertions encode, so a MAC
per test would mean inventing a scenario per test and rewriting
pre-existing assertions. Cross-file isolation stays with the disjoint
sibling MAC range, which is what serial was wrongly standing in for
before.

The header now states both levels explicitly so the next reader does not
undo one of them.

Verified: three consecutive runs of stalker + self-hosted + sources-pwa,
26/26 each.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

docs/architecture/stalker-mock-server.md

@@ -37,7 +37,67 @@ Stalker portals use MAC address as the primary credential. The mock server follo
 
 ### In-Memory Only
 
-No files or databases are written. All state (generated content + favorites) lives in process memory and resets on server restart. This is intentional — tests should not share state across runs.
+No files or databases are written. All state (generated content + favorites + portal sessions) lives in process memory and resets on server restart. This is intentional — tests should not share state across runs.
+
+### Two Endpoints With Different Strictness
+
+The app decides how to talk to a portal from the shape of its URL: a URL
+containing `/stalker_portal` is imported as a **full portal** (handshake,
+`Authorization: Bearer`, watchdog), anything else as a **simple portal** with no
+authentication at all. The mock therefore serves the same action set at two
+paths:
+
+| Path | Router | Behaviour |
+|---|---|---|
+| `/portal.php` | `createPortalRouter(false)` | Tolerant: ignores the token and the MAC format, like most reseller panels |
+| `/stalker_portal/server/load.php` | `createPortalRouter(true)` | Strict: enforces both, like the real middleware |
+| `/server/load.php` | `createPortalRouter(true)` | Strict: the second URL shape `isFullStalkerPortal` recognizes |
+
+The `/stalker` proxy route applies the same rule through
+`isFullPortalUrlShape()` — every URL the client would authenticate against is
+enforced, so tests cannot silently fall into the tolerant branch.
+
+Keeping the tolerant path is what lets the pre-existing e2e suite (which imports
+`portal.php`) stay meaningful — it covers the simple-portal branch — while the
+strict path finally covers the authenticated branch that had no coverage at all.
+
+The strict behaviours mirror the plaintext Stalker 4.9.35 middleware
+(`server/lib/stb.class.php`), the last openly readable ancestor of the encoded
+5.x core:
+
+- **Plain-text auth failures.** `Authorization failed.` / `Unauthorized request.`
+  are returned with **HTTP 200** and a `text/html` body, because the real server
+  `exit`s before the JSON envelope is built. A client checking only status codes
+  sees "success" and renders nothing. The `/stalker` proxy route still wraps the
+  body in the `{ payload }` envelope, matching what `apps/web-backend` does.
+- **A handshake is not a session.** The token only authorizes requests once
+  `get_profile` has adopted it for that MAC. Adoption is deliberately
+  *stricter* than the stock server: 4.9.35 issues handshake tokens statelessly
+  and pins whatever Bearer `get_profile` presents, so a forged token would
+  become a session on a real portal — the mock only adopts tokens it actually
+  issued, so a client with a broken token pipeline fails loudly in tests.
+- **Idempotent handshake.** Presenting the MAC's current token returns that same
+  token, which is what allows real clients to persist tokens across restarts.
+- **Device-id pinning.** `device_id`/`device_id2` are stored on first non-empty
+  value; any later change — including reverting to empty — is a permanent
+  `device conflict` carrying the "Your STB is damaged." block message. This is
+  the only identity check the stock server actually enforces.
+- **`signature`, `metrics`, `prehash` are ignored**, exactly as upstream ignores
+  them; they exist for portals with a custom `access_filter.php`.
+- **MAC format validation.** Non-Infomir MACs (`00:1A:79:XX:XX:XX`) get a bare
+  `{ status: 1 }` from `get_profile`.
+
+- **`do_auth` is a boolean login step.** Non-empty credentials answer
+  `{js:true}` and are recorded; the `login-required` scenario's `get_profile`
+  keeps answering `status: 2` until that record exists, because the app sends
+  `auth_second_step=1` on its very first profile request and a parameter check
+  alone would be trivially bypassed.
+
+Session state lives in `src/app/auth-store.ts` and is cleared by `/reset`.
+`POST /invalidate-session?macAddress=<mac>` drops a single MAC's tokens so
+tests can assert the client re-handshakes and retries instead of surfacing an
+error; pinned device identity survives invalidation, as it does on a real
+portal.
 
 ## Data Generation Pipeline
 
@@ -308,6 +368,6 @@ test('browse VOD categories', async ({ page }) => {
 
 - **New content types**: Add a new generator function in `data-generator.ts` and a new handler in `handlers/`.
 - **New scenarios**: Add to `SCENARIOS` in `scenarios.ts`.
-- **Stateful session tokens**: `handshake.handler.ts` generates a token from the MAC — extend this to track token expiry for testing re-auth flows.
-- **Error simulation**: Add a special MAC or query param to trigger error responses (e.g. 401, 500) for testing error handling in the Stalker store.
+- **Session behaviour**: `auth-store.ts` owns tokens and device pinning. Add TTLs or a "token replaced by another device" mode there rather than in the handlers.
+- **Error simulation**: Add a special MAC or query param to trigger error responses for testing error handling in the Stalker store. Note that portal-level auth errors are *not* HTTP errors — see [Two Endpoints With Different Strictness](#two-endpoints-with-different-strictness).
 - **Slow responses**: Add a `MOCK_DELAY_MS` env var and apply it in middleware for testing loading states.

docs/architecture/xtream-mock-server.md

@@ -116,10 +116,12 @@ The control plane is absent by default. It is mounted only when
 `IPTVNATOR_XTREAM_MOCK_CONTROL_TOKEN` and a literal loopback `HOST`
 (`127.0.0.1` or `::1`). Every `/__control/*` request must carry that exact value
 in `x-iptvnator-performance-token`, including `OPTIONS` preflight requests.
-Configuration is validated before the HTTP listener opens. Normal development
-mode preserves the legacy wildcard bind when `HOST` is unset; control mode
-instead defaults to `127.0.0.1` and rejects an explicitly configured
-non-loopback host. The Nx serve targets do not pin `PORT`, so an explicit shell
+Configuration is validated before the HTTP listener opens. Both modes now
+default to `127.0.0.1` when `HOST` is unset — the fixture serves fabricated but
+unauthenticated content, so it should not be reachable from other hosts by
+accident. Set `HOST=0.0.0.0` explicitly to expose it, which is what you need
+when driving the mock from a phone, an STB, a container, or another machine.
+Control mode additionally *rejects* an explicitly configured non-loopback host. The Nx serve targets do not pin `PORT`, so an explicit shell
 value reaches the parser; its no-value default remains `3211`.
 
 Use a dedicated port rather than the normal `3211` E2E server: