Files

T

Sylvain Duchesne bea9f51d91 docs: own the current-NextGraph-state knowledge + boundary (lib side)

This library presents a mature-NextGraph SDK face to consumers while
compensating for the current SDK's gaps via a shared-wallet simulation. It
therefore OWNS all current-state + simulation knowledge — moved here out of the
Festipod app repo, which must treat this library as a finished SDK.

New docs/:
- nextgraph-current-state.md — what the current SDK/broker do and don't expose
  (5 store types, document=repo, per-document ReadCap, inbox not exposed, iframe
  RPC proxy, mono-user/no-global-data, wallet import constraint). Keeps the
  nextgraph-rs source pointers.
- simulation.md — how the lib emulates the mature behaviour on one shared wallet
  (shim, store!=document two axes, docCreate→private store, RepoNotFound scope
  rule, @ng-org double-proxy DataCloneError, emulated ReadCap/inbox/curator).
- decisions/ — the current-SDK ADRs (private-store-nuri-scope, sparql-delete,
  shared-wallet-login, discovery mechanism).
- fork-inbox-fallback.md — the Rust-patch/self-host route not taken.
- migration-guide.md — the checklist for when real NextGraph matures.

README: boundary framing from the lib's side + docs/ index; replaced the stale
"scaffold/stubbed" status with the actually-implemented mechanisms per source.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-03 23:23:23 +02:00

3.5 KiB

Raw Blame History

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:

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."
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.

3.5 KiB Raw Blame History