Configuring User Self-Service

This guide describes how to configure and customize the user self-service features in Framework M, including gating default profile routes, setting up verification pipelines, and overriding the default profile form UI.

---

1. Enabling and Gating Default Profile Routes

Framework M provides default self-service profile and password update endpoints out-of-the-box in Indie Mode. To manage these gates, use the following configuration in your framework_config.toml file under the [auth] section:

[auth]
# Toggles whether default API routes for profile editing are active
enable_default_profile_routes = true

# Toggle whether public users can register accounts
allow_signup = true

# Toggle credential authentication channels
enable_email_auth = true
enable_phone_auth = true

If enable_default_profile_routes is set to false, the default router will bypass registering profile endpoints entirely, letting downstream applications register their own custom profile management controllers.

If allow_signup is false, endpoints for registration return 403 Forbidden and UI sign-up forms are automatically hidden.

---

2. Configuring Verification Flows

Direct edits to user identifiers (email, phone_number) are blocked for self-service users in the controller layer to prevent account hijacking. Changes must go through verification pipelines.

Email Verification Configuration

Email updates are verification-driven:

1. When a user requests an email update (POST /api/v1/auth/request-email-update), the system generates a secure signed token.
2. The system queues a confirmation email via EmailQueueProtocol.
3. When the user visits the confirmation link (GET /api/v1/auth/confirm-email-update/{token}), the token is validated, and the email is safely updated on the LocalUser record under system context.

Ensure your SMTP or email adapter is configured in framework_config.toml to support the mail dispatch:

[email]
backend = "smtp"
smtp_host = "smtp.example.com"
smtp_port = 587

Phone (OTP) Verification Configuration

Phone registration and updates are backed by SMS OTP:

1. When requesting a code, ConsoleSMSGateway, TwilioSMSGateway, or AwsSnsSMSGateway dispatches a transient 6-digit verification code.
2. Upon verification (/api/v1/auth/confirm-phone-update or /api/v1/auth/otp/verify), the identifier is marked verified in the database.

---

3. UI Form Overrides

To customize the profile management page in the Desk frontend, developers can override the default form layout for LocalUser.

Create a custom component at src/overrides/LocalUser/FormView.tsx within your app project:

import React from "react";
import { FormViewProps } from "@framework-m/desk";
import { useFormController } from "@framework-m/desk";

export default function CustomUserFormView({ doctype, id }: FormViewProps) {
  const { doc, save, isSaving } = useFormController({
    doctype,
    id: "me", // "me" automatically resolves to the authenticated user's ID
    uiContext: "self_service" // automatically applies self-service metadata constraints
  });

  if (!doc) return <div>Loading profile...</div>;

  return (
    <div className="custom-profile-form">
      <h2>Welcome, {doc.full_name}</h2>
      
      {/* Custom form fields */}
      <input 
        type="text" 
        value={doc.full_name || ""} 
        onChange={(e) => doc.full_name = e.target.value}
      />
      
      <button onClick={save} disabled={isSaving}>
        {isSaving ? "Saving..." : "Save Changes"}
      </button>
    </div>
  );
}

The framework's registry will automatically detect the component inside the src/overrides directory structure at compile-time and swap out the default Desk layout with your custom view.