Authentication & sessions

Portal is a Next.js application with its own signed session envelope backed by a real Frappe session. It does not use Frappe Desk as the customer UI.

Login flow

The Portal cookie is signed, HTTP-only and secure in production. Client components never receive the Frappe sid.

Request authentication

lib/session.ts creates, verifies and clears the signed cookie. Protected routes resolve the user before calling Core. Mivama Core also confirms Portal login eligibility through mivama_core.auth.validate_customer_portal_login.

Calls are split into user-session calls, trusted Portal calls authenticated with the Portal/Core secret and narrow public calls such as password-token validation.

Password setup and welcome

New customer users receive a branded Portal welcome message with a Portal password-setup URL, not the default Helpdesk or Desk link. The Frappe User after_insert hook schedules it. Templates and the white Mivama layout live in Mivama Core and are previewable in the Desk workspace.

Forgot-password routes proxy through Portal and force the return URL back to Portal. The token is validated before a new password is accepted.

WordPress single sign-on

Portal can create a short-lived WordPress handoff for an owned service. Its return route validates the handoff and restores Portal context. This is separate from the Studio launch code.

Logout and revocation

Logout clears the signed Portal cookie and abandons the Frappe session where applicable. Studio sessions are independently revocable; Portal logout does not cancel hosting or delete Studio data.

Source map

• lib/session.ts and lib/portal-auth.ts
• app/api/auth/login, logout, me and set-password
• mivama_core/auth.py
• mivama_core/user_events.py