Anonymous sessions & sign-in promotion

A visitor should be able to start chatting before they sign in — and, when they do sign in, keep the conversation they already have. DioscHub treats anonymous sessions as first-class and promotes them in place on sign-in, so nothing is lost.

Bind anonymously to start

To let a visitor chat without an account, bind the connection with no identity — send identity: null (or omit it) on POST /auth/bind. That produces an anonymous binding. DioscHub resolves the anonymous Role’s feature flags for the connection and hands them to the widget when it signals ready.

Note

authArtifacts is still required on an anonymous bind — send authArtifacts: { headers: {} } when there is nothing to forward. An anonymous visitor typically has no user credential, so the Assistant runs with whatever the anonymous Role allows and no forwarded auth.

The widget waits to be told its identity — including the anonymous one — before it starts a Session. Feature gating follows from this: the widget holds features closed until the bind delivers them, so an anonymous visitor sees exactly what the anonymous Role grants, never a signed-in default.

Promote in place when the user signs in

When the visitor signs in, re-bind the same connection with a real identity. DioscHub recognizes that the connection’s session is anonymous and promotes it rather than starting a new one:

• The conversation continues on the same session id — the message history is intact.
• The session’s owner becomes the signed-in user (identity.userId).
• The Assistant’s tool scope is re-resolved to the user’s Role, so the promoted session gets the signed-in user’s tools and features — not the anonymous set it started with.
• The widget receives a fresh session token and continues without reloading the conversation.

To trigger this from the frontend after your app completes sign-in, call diosc('reauth'). The widget re-runs the bind on its live connection; your bind endpoint now sees an authenticated user and passes a real identity, and DioscHub promotes the session.

Tip

Promotion is one-way and only applies to a session that is still anonymously owned. A session already owned by a signed-in user is never re-owned by a different user through this path — sign-in upgrades an anonymous session, it does not transfer an authenticated one.

The sequence end to end

1. Page loads, widget connects, your bind endpoint returns an anonymous bind (identity: null).
2. The visitor chats; the Assistant runs with the anonymous Role’s tools and features.
3. The visitor signs in through your app.
4. Your app calls diosc('reauth'); the widget re-binds with the signed-in user’s identity.
5. DioscHub promotes the session in place; the same conversation continues, now as the signed-in user with their Role’s tools.

---

Next: return to MCP server development to expose the tools a signed-in user can now reach, or configure Roles and Assistants in the admin portal.