feat(socket-auth): authenticate the realtime socket with session socket tokens

[roncodes]

What

The console's realtime socket now authenticates with short-lived socket tokens minted from the console session. The socket service gives the SocketCluster client its own in-memory auth engine.

• Handshake. loadToken() runs on every connect and reconnect. While the session is authenticated it calls POST int/v1/socket/token and gets { token, expires_in, expires_at }. A cached token is reused while it has more than 60 s left, and concurrent loads share one request. saveToken and removeToken keep the token in memory only. It is never written to localStorage or put in the URL. Subscriptions queued before the handshake go out authenticated, so existing callers (listen(), instance().subscribe()) need no change.
• Anonymous fallback. With no session, a 404 (older server, or socket auth turned off), or any other mint failure, loadToken resolves null and the client connects anonymously as it does today.
• Refresh. A native timer (not the run loop, which would keep settled() waiting) fires at expires_in - 60 s (minimum 5 s). It mints a new token and calls socket.authenticate(). While disconnected, the token waits for the next handshake.
• Recovery.
  • Triggers: deauthenticate, a kickOut with a token reason, or a subscribeFail with an AuthError whose reason is no_token, token_expired, token_changed, deauthenticated or identity_changed.
  • What happens: the service gets a fresh token, authenticates, and resubscribes the lost channels by name. SocketCluster sends data by channel name, so existing for await loops on raw instance().subscribe() channels start receiving again.
  • Loop guards: each channel is retried once per token, there are at most 3 recoveries a minute, and deauthenticate caused by the service's own authenticate call is ignored. A token the server rejects is dropped.
  • Refusals for other reasons (the user may not see the channel) are not retried. They are left to the subscriber's subscribeFail handling.
• Session lifecycle. The service listens on the universe bus:
  • session.authenticated (login) and user.organization_switched re-key the socket with a new token.
  • user.loaded authenticates a socket that connected anonymously before the session was restored. An anonymous connect while signed in does the same.
  • user.deauthenticated (logout) clears the token, stops timers and retries, and disconnects. The next login reconnects.
• Client tag. The handshake query carries client=console/<app version>. It is not a secret; the server uses it to label its logs.

Why

Today any client can subscribe to any channel name. This is the console's part of the socket-auth work: the socket server can now check each subscription against the user's session (see the contract in the related PRs). This PR does not change channel names.

Notes for extension authors

The docs/ guides moved to fleetbase.io, so these notes are here for now:

• Keep subscribing the way you do now. You don't need to pass a token or call authenticate yourself.
• Once a server enforces socket auth, each subscription is checked on the server. A user can subscribe only to channels for records their organization owns, plus their own user.* and company.* channels.
• If a channel is refused for a reason other than its token, the service does not retry it. Listen for channel.listener('subscribeFail'): error.name === 'AuthError', and error.reason is a short snake_case code. Show or log the refusal instead of waiting.

Tests

• New tests/unit/services/socket-auth-test.js covers:
  • anonymous handshakes when signed out
  • minting, reuse and leeway, a shared in-flight request, and the 404 or malformed-response fallback
  • nothing stored outside memory, and a token arriving after logout being discarded
  • refresh timing and the minimum delay; refresh while connected and while disconnected
  • rejected or failed authentication
  • re-authentication on login, restore and organization switch; logout teardown
  • recovery from deauthenticate, kickOut and subscribeFail: resubscribe, batching, the follow-up run, the once-per-token rule and the per-minute cap
  • client event wiring and listener teardown
• tests/helpers/stub-socketcluster.js gains inertClientMethods(), createEventStream() and createRecordingClient(). The suite-wide stub, socket-test.js and socket-listen-test.js now provide the client methods the service calls.

Test plan

Verified by CI (lint, full suite, 100% coverage gate). No local builds or test runs.

Related PRs

Part of the authenticated realtime channels rollout (socket auth), one PR per repo:

• feat(socket-auth): authenticated realtime channels (tokens, authorizer, signed publish) core-api#290 — tokens, channel authorizer, signed HTTP publish (merge and tag first: fleetops and storefront require fleetbase/core-api ^1.6.69)
• feat(socket-auth): fleetops channel resolvers, driver socket tokens, per-customer tracking channel fleetops#358 — fleetops channel resolvers, driver socket tokens, per-customer tracking channel
• feat(socket-auth): storefront customer and checkout socket tokens, channel resolvers storefront#113 — customer and checkout socket tokens, storefront/checkout resolvers
• feat(socket-auth): Fleetbase socket server with JWT auth and signed internal publish fleetbase#704 — fleetbase/fleetbase-socket server, compose/helm/installer, console socket test page
• feat(socket-auth): authenticate the realtime socket with session socket tokens #97 — console socket service authenticates with session tokens
• feat(socket-auth): show channel authorization failures in the sockets viewer dev-engine#51 — sockets viewer shows authorization failures
• feat(socket-auth): authenticate realtime socket with driver socket tokens navigator-app#112 — driver app socket tokens
• feat(socket-auth): authenticate realtime socket with customer and checkout socket tokens storefront-app#65 — customer and checkout socket tokens
• feat(socket-auth): generate the socket auth key on install fleetbase-cli#11 — installer generates the socket auth key
• feat(socket-auth): add socket.token() to mint realtime socket tokens fleetbase-js#45, feat(socket-auth): add customer.socketToken() for realtime channels storefront-js#22, feat(socket-auth): add socket->token() to mint realtime socket tokens fleetbase-php#28 — SDK socket token helpers
• docs(socket-auth): authenticated realtime channels and migration guide fleetbase.io#120 — docs and migration guide

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (56af192) to head (4180647).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main       #97    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          168       168            
  Lines         5027      5229   +202     
  Branches      1362      1395    +33     
==========================================
+ Hits          5027      5229   +202     

Flag	Coverage Δ
ember-core	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.