Toju/agents-docs/user-stories/silent-cross-signal-server-auth.md

User Story: Silent cross–signal-server account auth

Status: Open (research complete — not fixed)
Priority / Severity: Critical
Area: authentication, realtime, server-directory
Last researched: 2026-08-12
Related docs: features/authentication.md, toju-app/src/app/domains/authentication/

---

User story

As a signed-in Toju user
I want the app to automatically create (or reuse) my account on any additional signal server as soon as I need that server
So that I never see a login / authorize prompt again after my initial home-server login, and chat / presence / joins keep working across the whole multi-server network.

---

Problem statement

The product supports multiple signaling servers. A user registers/logs in once on a home signal server. When they later interact with a foreign signal server (join/create a room hosted there, open an invite, activate another endpoint, etc.), the client is supposed to silently provision a linked account on that server using a local provision secret, store a per-server session credential, and continue — without interrupting the UI.

In practice, the login / authorize screen keeps appearing (/login?mode=authorize&serverId=…) even though the user is already authenticated locally. That breaks the “one login, whole app” contract and feels like the session is constantly dying.

---

Desired behavior (acceptance criteria)

1. After a successful home login or register, the user is never prompted for credentials again solely because they touched another signal server.
2. The first time the user has business with signal server N (N ≠ home):
   • The client ensures a valid per-URL credential exists (register-or-login with the provision secret).
   • WebSocket identify and protected REST calls use that credential’s actor user id + token.
   • The home NgRx / local profile stays unchanged.
3. If the preferred username is already taken on the foreign server, the client silently uses the designed suffix strategy (alice-<homeUserIdPrefix>) and optional display-name disambiguation — still without opening /login.
4. Transient auth_required (message raced ahead of identify) never opens login and never tears down the home session while a valid local credential exists.
5. Rejected foreign tokens trigger re-provision (or credential refresh), not a home logout and not a blocking authorize form when silent provision is possible.
6. Offline / unreachable / incompatible endpoints never open /login?mode=authorize.
7. Session restore after app restart still silently provisions foreign servers (provision secret and credentials survive restart on desktop).
8. Settings → Network may show Authorized / Needs sign-in for diagnostics, but “Needs sign-in” must not become the default path for a normal logged-in user who simply joined a room on another host.

Explicit non-goals (for this story)

• Changing the home-server password / register UX for first-time users.
• Merging foreign actor ids into a single global server-side identity (home id ≠ foreign provisioned id is expected).
• Removing the authorize UI entirely — it may remain as a last resort (e.g. true username collision exhaustion, or user-initiated “Sign in” from Network settings).

---

Current intended architecture (as designed)

Concept	Role
Home session	Local profile + credential for homeSignalServerUrl
Provision secret	Per-install secret generated on home login/register; used as the password when auto-registering/logging into foreign servers
Per-signal credential store	metoyou.signalServerCredentials — token + actor userId per normalized server URL
Legacy token store	metoyou.authTokens — still used for REST interceptor / session restore fallback
ensureProvisioned	Register-or-login on a foreign URL using the provision secret
ensureCredentialForServerUrl	Gate before foreign room connect / invite / join — provision first; only then optionally navigate to authorize
authorize login mode	Manual login that only upserts a foreign credential (authorizeSignalServer) without resetting home state

Primary call sites that demand a foreign credential:

• Room signaling connect (room-signaling-connection.ts)
• Invite / server-browser join flows
• Active endpoint health → opportunistic ensureProvisioned
• provisionActiveSignalServers$ after loadCurrentUserSuccess

Authorize navigation is gated by shouldNavigateToAuthorizeSignalServer:

• Endpoint must look online
• Provision result is collision or skipped with reason no-provision-secret

---

Research findings — likely causes

These are code-backed hypotheses ranked by how directly they produce a login prompt while the user still has a home session.

Cause A — Missing provision secret → authorize login (primary)

Mechanism

1. SignalServerAuthService.ensureProvisioned returns { kind: 'skipped', reason: 'no-provision-secret' } when ProvisionSecretStoreService.getSecret(homeUser.id) is null.
2. SignalServerAuthorizeService.ensureCredentialForServerUrl then calls navigateToAuthorize → /login?mode=authorize.
3. Login’s authorize mode does not auto-redirect away when currentUser is set (the leave-login effect explicitly returns early in authorize mode), so the prompt stays on screen.

Why the secret is often missing

• Secret is created only in prepareAuthenticatedUserStorage via ensureHomeProvisionSecret, and only when both user.homeSignalServerUrl and loginResponse are present.
• Session restore (loadCurrentUserSuccess → provisionActiveSignalServers$) calls ensureProvisioned but never calls ensureHomeProvisionSecret to create a missing secret.
• Web / non-Electron fallback stores the secret in sessionStorage (metoyou.provisionSecret.<userId>), which dies when the tab/session ends.
• Accounts created before this feature, wiped Electron userData/provision-secrets/, or logins that never received a loginResponse + home URL pair never get a secret.

Evidence in code

• signal-server-authorize.rules.ts — no-provision-secret ⇒ navigate to authorize
• signal-server-authorize.service.spec.ts — “still provisions foreign servers and navigates to authorize when the secret is missing”
• users.effects.ts — ensureHomeProvisionSecret only inside prepareAuthenticatedUserStorage with loginResponse

Cause B — Username collision exhaustion → authorize login

Mechanism

SignalServerProvisionerService tries preferred username, then suffixed candidates. If every register returns 409 and every login with the provision secret returns 401, it throws ProvisionUsernameCollisionError → kind: 'collision' → authorize UI.

When it shows up

Another user already owns those usernames on the foreign server with different passwords (not our provisioned accounts). Silent recovery is impossible without a different identity strategy or manual credentials.

Cause C — Home session false expiry → full /login (not just authorize)

Mechanism

signalServerAuthFailed$ clears the credential for the failing URL, then:

• expire-home-session if the failure is classified as the home server → clearStoredCurrentUserId + SESSION_EXPIRED → redirectOnSessionExpired$ → /login
• provision-foreign otherwise → silent ensureProvisioned (no login UI by itself)

False home classification risks

• Missing / stale homeSignalServerUrl on the restored user → foreign failures compared with empty home URL → isSameSignalServerUrl is false, so this path usually prefers foreign provision; but home failures with no resolvable credential after retries still expire the session.
• Exhausted re-identify retry budget on home while credential lookup fails (empty credential store + broken legacy fallback) → auth_required / auth_error treated as unrecoverable home expiry.
• Past regressions (see lessons): identifying only from the new credential store, or treating auth_required as logout — partially mitigated, but restore edge cases still matter.

Cause D — Credential present locally but identify never runs / races

Mechanism

Without a resolvable token for the foreign URL, the socket sends non-identify traffic → server auth_required. If the client then cannot re-identify or re-provision (Cause A), user-facing flows that gate on ensureCredentialForServerUrl open authorize login. Presence/chat then look “broken” even though the home profile still shows logged in.

Related lesson: identify must fall back to legacy AuthTokenStoreService for home; foreign servers cannot be reconstructed from the legacy store (actor id differs) — so foreign URLs must be provisioned, not guessed.

Cause E — Opportunistic provision fails quietly; later gate opens login

Mechanism

provisionActiveSignalServers$ and server health ensureProvisioned(...).catch(() => undefined) swallow errors. A later user action (join room) hits ensureCredentialForServerUrl with the same missing secret / collision and then navigates to authorize — so login appears mid-flow rather than at startup.

---

User-visible scenarios

Happy path (required)

1. Alice registers on Signal Server 1.
2. Alice browses/joins a community hosted on Signal Server 2.
3. Client silently registers alice (or alice-<prefix>) on Server 2 with the provision secret.
4. Alice lands in the room; no login modal/page; peers see her presence under the Server 2 actor id.

Failure path today (bug)

1. Alice is logged in (user bar / local profile show her).
2. Alice opens an invite or room whose sourceUrl is Signal Server 2.
3. Client cannot provision (no secret / collision).
4. App navigates to /login?mode=authorize&serverId=…&returnUrl=….
5. Alice believes she was logged out; re-entering home credentials may even bind the wrong server if she is not careful with the server picker.

Restart path (required)

1. Alice fully quits the desktop app and reopens.
2. Home session restores from local DB + token stores.
3. Touching Server 2 again still silent-provisions or reuses the stored foreign credential — no authorize prompt.

---

Proof of done (when implementing)

Prefer behavior-level proof over mocks shaped like the provisioner:

1. Integration / focused effect+service tests
   • Missing secret on restore → secret is ensured, then foreign provision succeeds, and Router.navigate(['/login']) is never called.
   • Foreign auth_error with home session intact → re-provision + re-identify; no SESSION_EXPIRED.
   • Online foreign endpoint + successful provision → ensureCredentialForServerUrl returns true.
2. Manual / E2E
   • Two live signal servers; register on #1; join room on #2 without typing a password again; reload app; rejoin still silent.
3. Negative
   • Offline foreign endpoint must not open authorize login.

---

Likely fix directions (for a later interview — not approved yet)

Option	Idea	Tradeoff
A (recommended)	On session restore / before any foreign ensureProvisioned, call ensureHomeProvisionSecret so a missing secret is generated once and persisted; keep authorize UI only for true collision / user-initiated sign-in	New secret cannot unlock accounts previously provisioned with an old lost secret — may need re-register with suffix or collision path
B	Stop navigating to authorize on no-provision-secret; surface a non-blocking Network badge / toast and retry when secret becomes available	User may join without credential and hit silent presence failures
C	Derive a stable provision secret from a durable local key (not sessionStorage) on web so restarts keep the same secret	Crypto/key-storage design; still need migration for existing installs
D	For collisions, auto-pick a stronger unique username (e.g. always include fuller home user id) before opening authorize	Reduces but does not eliminate collision UX

---

Key files

• toju-app/src/app/domains/authentication/application/services/signal-server-authorize.service.ts
• toju-app/src/app/domains/authentication/application/services/signal-server-auth.service.ts
• toju-app/src/app/domains/authentication/application/services/signal-server-provisioner.service.ts
• toju-app/src/app/domains/authentication/application/services/provision-secret-store.service.ts
• toju-app/src/app/domains/authentication/domain/logic/signal-server-authorize.rules.ts
• toju-app/src/app/domains/authentication/domain/logic/signal-server-auth-failure.rules.ts
• toju-app/src/app/store/users/users.effects.ts (signalServerAuthFailed$, provisionActiveSignalServers$, redirectOnSessionExpired$, prepareAuthenticatedUserStorage)
• toju-app/src/app/store/rooms/room-signaling-connection.ts
• electron/api/provision-secret-store.ts
• agents-docs/features/authentication.md

---

Lessons already adjacent

• Identify must fall back to the legacy session token (home restore).
• Keep per-signal-URL identify credentials resolvable from the store.
• Persisted local user state still requires a session token.
• Do not open authorize login for offline endpoints.
• Distinguish auth_required vs auth_error so home session is not falsely expired.