Skip to main content

User Management

This document explains how user management works in tududi from a user behavior perspective. For technical implementation details, see the backend code in /backend/modules/users/, /backend/modules/auth/, and /backend/modules/admin/.

Registration & Onboarding​

Registration Flow​

  1. Registration is controlled by admins

    • By default, registration is disabled
    • Admins can toggle registration on/off via the Admin panel
    • When disabled, only admins can create new user accounts

  2. Email verification is required

    • When a user registers, they receive a verification email
    • The email contains a unique link that expires in 24 hours (configurable)
    • Users cannot log in until they verify their email address
    • If email service is disabled, users must be verified manually by an admin

  3. The first user becomes an admin automatically

    • When no admin users exist in the system, the first user to register becomes an admin
    • This ensures someone can manage the system after initial setup
    • All subsequent users are created as regular users by default

  4. Registration validation rules:

    • Email must be valid format and unique
    • Password must be at least 6 characters long
    • Email is automatically normalized (trimmed and lowercased)

Authentication​

Login​

  1. Users log in with email and password

    • Email verification must be completed before login
    • Attempting to log in with an unverified email returns a specific error
    • Invalid credentials return a generic "Invalid credentials" error (security best practice)

  2. Session-based authentication

    • After successful login, a session is created and stored in a cookie
    • Sessions persist until logout or session expiry
    • Users can be logged in across multiple devices/browsers simultaneously

  3. API token authentication

    • Users can create personal API tokens for programmatic access
    • Tokens are prefixed with tt_ and are 64 characters long
    • Tokens can have optional expiration dates
    • Multiple tokens can be active simultaneously
    • Tokens can be revoked or deleted at any time

Logout​

  1. Logout destroys the session
    • The session is removed from the server
    • The user must log in again to access the system

User Roles & Permissions​

Role System​

  1. Two role types exist: Admin and User

    • Admin: Full system access, can manage users, toggle registration, access admin panel
    • User: Standard access to their own data and shared resources

  2. Role assignment:

    • First user is automatically assigned admin role
    • Admins can promote/demote other users to/from admin
    • Every user has exactly one role record
    • Roles are created automatically when a user account is created

  3. Admin capabilities:

    • Create, update, and delete user accounts
    • Promote/demote users to/from admin role
    • Toggle registration on/off
    • Cannot delete their own account (prevents lockout)

Resource Permissions​

Sharing & Access Control​

  1. Resources can be owned or shared

    • Users own resources they create (projects, tasks, notes)
    • Owners have full read-write access to their resources
    • Resources can be shared with other users with specific access levels

  2. Access levels:

    • none: No access
    • ro (read-only): Can view but not modify
    • rw (read-write): Can view and modify
    • admin: Full control (owners and admins have this level)

  3. Hierarchical permission inheritance:

    • Tasks inherit permissions from their parent project
    • Notes inherit permissions from their parent project
    • If a user has access to a project, they have the same access to its tasks and notes

  4. Admins bypass permission checks

    • Users with admin role have admin-level access to all resources
    • This enables admins to help users with issues or perform system maintenance

User Profile Management​

Profile Information​

  1. Users can update their profile details:

    • Name and surname (optional)
    • Email (must remain unique)
    • Password (requires current password confirmation)
    • Avatar image (upload/delete)

  2. User preferences stored in profile:

    • Appearance: Light or dark theme
    • Language: One of 24 supported languages
    • Timezone: User's timezone for date/time display
    • First day of week: 0 (Sunday) to 6 (Saturday)

  3. Feature toggles:

    • Task intelligence enabled/disabled
    • Auto-suggest next actions enabled/disabled
    • Pomodoro timer enabled/disabled
    • Productivity assistant enabled/disabled
    • Next task suggestion enabled/disabled

  4. Telegram integration settings:

    • Bot token for personal Telegram bot
    • Chat ID for receiving messages
    • Allowed users list (comma-separated usernames/IDs)
    • Task summary enabled/disabled
    • Task summary frequency (daily, weekdays, weekly, hourly intervals)

  5. Notification preferences:

    • Configure per notification type (due tasks, overdue tasks, due projects, etc.)
    • Configure per channel (in-app, email, push, Telegram)
    • Stored as JSON with defaults for new users

  6. UI settings:

    • Today page settings (show/hide sections, metrics, suggestions)
    • Sidebar settings (pinned views order)
    • Project detail settings (show/hide metrics)
    • Keyboard shortcuts (custom mappings)

Password Management​

Changing Password​

  1. Password change requires current password

    • User must provide their current password
    • New password must be at least 6 characters
    • Prevents unauthorized password changes if session is compromised

  2. Password storage is secure

    • Passwords are hashed using bcrypt (10 rounds)
    • Original passwords are never stored
    • Password field is virtual in the model (not persisted)
    • Only password_digest is stored in the database

Avatar Management​

Upload & Delete​

  1. Users can upload a profile avatar image

    • Uploaded files are stored in /uploads/avatars/
    • Avatar URL is stored in user profile
    • Uploading a new avatar replaces the old one (old file is deleted)

  2. Deleting avatar:

    • Removes the avatar file from the server
    • Sets avatar URL to null in the profile
    • User displays with default avatar after deletion

API Tokens (Personal Access Tokens)​

Token Management​

  1. Users can create multiple API tokens

    • Each token has a name/label for identification
    • Tokens are displayed with a prefix (first 12 characters) for identification
    • Full token value is only shown once upon creation
    • Tokens are hashed before storage (bcrypt, 12 rounds)

  2. Token properties:

    • Name: User-defined label for the token
    • Token prefix: First 12 characters for identification (e.g., tt_ab12cd34)
    • Created at: When the token was created
    • Last used at: When the token was last used for authentication
    • Expires at: Optional expiration date (null = never expires)
    • Revoked at: When the token was revoked (null = active)

  3. Token operations:

    • Create: Generates new token, returns full value once
    • List: Shows all tokens with metadata (not the full value)
    • Revoke: Marks token as revoked (soft delete, keeps history)
    • Delete: Permanently removes token from database

  4. Token authentication:

    • Tokens are used with Authorization: Bearer tt_... header
    • System finds tokens by prefix, then validates hash
    • Expired or revoked tokens are rejected
    • Last used timestamp is updated on successful authentication

Admin User Management​

User CRUD Operations​

  1. Admins can create new users directly

    • Bypasses registration flow and email verification
    • Created users can log in immediately
    • Requires: email, password
    • Optional: name, surname, role (admin or user)

  2. Admins can list all users

    • Shows email, name, surname, role, creation date
    • Includes role information (admin or user)

  3. Admins can update any user's details

    • Can change: email, password, name, surname, role
    • Email must remain unique across all users
    • Password change doesn't require current password (admin privilege)

  4. Admins can delete users

    • Cannot delete their own account (prevents lockout)
    • Deleting a user also deletes their data:
      • Tasks are deleted (cascades to subtasks, attachments, etc.)
      • Projects are deleted (cascades to tasks within)
      • Notes are deleted
      • Permissions granted by/to the user are removed
      • API tokens are deleted
      • Shared resources are unshared

  5. Admin bootstrapping:

    • When no admin roles exist, the system is in "bootstrap mode"
    • In bootstrap mode, any authenticated user can set admin roles
    • After at least one admin exists, only admins can manage roles

Settings & Preferences​

Today Page Settings​

  1. Today page is highly customizable:

    • Show/hide metrics panel
    • Show/hide productivity assistant
    • Show/hide next task suggestion
    • Show/hide AI suggestions section
    • Show/hide tasks due today
    • Show/hide completed tasks
    • Show/hide progress bar
    • Show/hide daily quote

  2. Settings are stored per user:

    • Defaults are applied for new users
    • Changes are saved immediately
    • Settings sync across devices/sessions
  1. Sidebar view pinning:
    • Users can pin saved views to the sidebar
    • Pinned views can be reordered
    • Order is stored in sidebar_settings.pinnedViewsOrder array

Task Summary Settings​

  1. Telegram task summaries can be scheduled:
    • Enable/disable toggle
    • Frequency options: daily, weekdays, weekly, 1h, 2h, 4h, 8h, 12h
    • Last run and next run timestamps are tracked
    • "Send now" option for immediate summary

User Lifecycle​

Account Creation to Deletion​

  1. User creation flow:

    Registration → Email Verification → First Login → Profile Setup → Active User
    • Or: Admin creates user → Active user (no verification needed)

  2. User deletion flow:

    Admin deletes user → Cascade delete resources → Remove permissions → Remove sessions
    • User cannot log in after deletion
    • All owned data is removed
    • Shared access is revoked

Security Considerations​

Password Security​

  1. Passwords are protected:

    • Hashed with bcrypt (10 rounds for user passwords, 12 for tokens)
    • Never transmitted in API responses
    • Virtual field prevents accidental persistence

  2. Email normalization:

    • Emails are trimmed and lowercased before storage
    • Prevents duplicate accounts with different casing

Session Security​

  1. Session management:
    • Sessions are stored server-side
    • Session cookies are HTTP-only (prevents XSS)
    • Sessions expire after inactivity
    • Logout properly destroys sessions

API Token Security​

  1. Token security:
    • Tokens are cryptographically random (32 bytes = 256 bits)
    • Tokens are prefixed (tt_) for easy identification
    • Tokens are hashed before storage (bcrypt, 12 rounds)
    • Expired and revoked tokens are rejected

Key Concepts​

User Identity​

A user account is identified by:

  • ID: Internal database ID (integer)
  • UID: External unique identifier (string, used in URLs)
  • Email: Unique, normalized email address

Role Record​

Every user has exactly one role record that determines admin status. Created automatically when the user account is created.

Permission Record​

Grants access to a specific resource (project, task, note) with a specific access level (ro, rw). Multiple permission records enable sharing resources across users.

API Token​

A personal access token that enables programmatic API access. Tokens are long-lived credentials that should be treated like passwords.

Bootstrap Mode​

Special state when no admin users exist. Allows the first authenticated user to set admin roles, preventing system lockout after initial setup.

Technical Implementation Files:

  • User model: /backend/models/user.js
  • Role model: /backend/models/role.js
  • Permission model: /backend/models/permission.js
  • User service: /backend/modules/users/service.js
  • Auth service: /backend/modules/auth/service.js
  • Admin service: /backend/modules/admin/service.js
  • Permissions service: /backend/services/permissionsService.js
  • Registration service: /backend/modules/auth/registrationService.js
  • API token service: /backend/modules/users/apiTokenService.js

Document Version: 1.0.0 Last Updated: 2026-03-15 Audience: Developers, AI assistants, and end users