# ADR — Shared-wallet login/logout flow

**Date:** 2026-06-15 · **Status:** Accepted (frozen). The rationale behind this
lib's **faux login** (`accounts.ts`) and why it must never touch NextGraph.

## Starting constraint

NextGraph login **is not programmable**: it is a **web redirect** to the broker
page (`nextgraph.net`). The shared wallet cannot be opened silently — at least one
broker-redirect pass is required per device. The question is therefore not "how to
avoid the redirect" but "how to order and present it" so the UX stays coherent.

## Decision — technical gate first, application "Connexion" second

Two distinct auth layers, presented in this order:

1. **Real layer (technical, NOT perceived as login).** The broker redirect appears
   **immediately, before any app render**. Because it precedes the app, the user
   reads it as a **technical access barrier to the test environment** (a beta
   wall), **not** an application login. Same shared credentials for everyone
   (given in the invitation, "access code" style). Once per device, then
   persistent. **Never labelled "login."**
2. **Application layer (perceived as THE login).** A **"Connexion"** screen =
   **username only** (→ `localStorage`, the current principal). This is the login
   *in the user's perception*. **No password** → declarative connection (anyone
   takes any username — coherent with zero-security / friends). **"Déconnexion"**
   clears **only** the username and returns to "Connexion"; it **calls no NG
   function**.

The **real logout** (`ng.session_stop` / `user_disconnect` / `wallet_close`) stays
**hidden** (settings/debug), because it forces a new redirect.

## Why (vs the rejected option)

**Rejected** — faux login first, then a warning page "enter this username/password",
then a *Continue* button triggering the redirect. Rejected: strange workflow,
dissonant double-login, a warning page that **looks like a scam**, and the
redirect **resurfacing mid-use** on every session expiry.

**Chosen** because: the mental model stays coherent (the technical barrier not
being perceived as login, the app-level Connexion/Déconnexion pair is complete and
self-consistent); graceful degradation (a re-gate after a browser restart reads as
"reconnecting to the environment", not a bug); and **similarity to the target
infra** — the "broker redirect → app" shape is exactly the real multi-wallet flow.
At migration you **remove the username "Connexion" screen** and the **technical
barrier becomes the real per-user login** — the flow shape does not change.

## Verified technical facts (`nextgraph-rs`, 2026-06-15)

- **Session persistence: YES.** Wallet remembered iframe-side (`localStorage`
  long-term + `sessionStorage` for the active session); on reload `init()`
  recovers the session **without** re-triggering the redirect while the broker
  session exists (`sdk/js/web/src/index.ts`, `sdk/js/api-web/main.ts`). A full
  browser restart (losing `sessionStorage`) can re-trigger the gate.
- **Real logout exposed: YES.** `ng.session_stop()`, `ng.user_disconnect()`,
  `ng.wallet_close()` (`sdk/js/lib-wasm/src/lib.rs`); they stop the session /
  clear the wallet and **force a new redirect** afterwards — hence: do NOT call
  them in the app-level "Déconnexion," and hide the real logout.

## How this lib realizes it

`accounts.ts` `AccountStore.login()`/`logout()` only read/write the username in an
injected `AccountStorage`; they **never** call NG. See the faux login in
[`../simulation.md`](../simulation.md).