11. User Management & Security

NkapBooks includes a full-featured role-based access control (RBAC) system that lets you control who can view, create, edit, delete, submit, and share every document type in the application. The security model is built on schema-based entities — Users, Roles, Role Permissions, Sessions, and Document Shares — all managed through the standard document interface.

11.0 Security Model Overview

NkapBooks implements a layered permission model that evaluates access at multiple levels:

┌─────────────────────────────────────────────────┐
│  1. Administrator Bypass                         │
│     If user has Administrator role → ALLOW ALL   │
├─────────────────────────────────────────────────┤
│  2. System Doctype Bypass                        │
│     Core settings doctypes → ALLOW ALL           │
├─────────────────────────────────────────────────┤
│  3. Role-Based Permissions                       │
│     Check RolePermission records for user's roles│
├─────────────────────────────────────────────────┤
│  4. Owner-Based Permissions (ifOwner)            │
│     Permission applies only if user owns the doc │
├─────────────────────────────────────────────────┤
│  5. Document Sharing                             │
│     Check DocShare records for specific documents │
├─────────────────────────────────────────────────┤
│  6. Default: DENY                                │
└─────────────────────────────────────────────────┘

Permission Types

The system supports 13 distinct permission types that can be independently toggled per doctype per role:

Standard Roles

NkapBooks ships with four system roles that cannot be deleted:

11.1 User Accounts

A User in NkapBooks represents an individual who can log in, perform actions, and own documents. Users are identified by their email address (which serves as the primary key) and have a rich profile including contact details, security settings, and role assignments.

User Schema

The User schema is organized into six sections:

Profile Section

Contact Section

Roles Section

Each row in the roles table is a UserRole record:

Security Section

Activity Section (read-only)

Settings Section

Email Section

Creating a User

1. Navigate to Setup → Users from the sidebar
2. Click + New User (or press Ctrl+N)
3. Enter the email address in the Name field — this is the user's login identifier
4. Fill in First Name and Last Name (Full Name is auto-computed)
5. Set a Password (only visible during creation; hidden after save)
6. Assign Roles in the Roles table — click Add Row and select a role
7. Click Save (Ctrl+S)

User Lifecycle

List View

The Users list view displays three columns by default:

Keyword search works across name, email, fullName, and username.

Quick Edit Fields

When viewing a user in quick edit mode, these fields are shown:

• Email, First Name, Last Name, Enabled, Phone

11.2 Roles

A Role defines a named set of permissions. Roles are assigned to users and determine what actions each user can perform across the application.

Role Schema

Built-in Roles

NkapBooks comes with several pre-configured roles:

Creating a Custom Role

1. Navigate to Setup → Roles from the sidebar
2. Click + New Role
3. Enter a Role Name (e.g., "Cashier", "Branch Manager")
4. Add a Description explaining the role's purpose
5. Configure Desk Access and Two-Factor Auth settings
6. Add Permissions in the permissions table (see Role Permissions)
7. Click Save

Role Properties

Role Lifecycle

Role Deletion Protection

When you try to delete a role:

1. System roles — Cannot be deleted. An error is shown: "Cannot delete system role: Administrator"
2. Assigned roles — Cannot be deleted while assigned to users. Error: "Cannot delete role 'Cashier' as it is assigned to 3 user(s). Please remove the role from all users first."
3. Custom unassigned roles — Can be deleted safely. Associated RolePermission child entries are deleted automatically.

List View

Clicking a role in the list opens the role form at /edit/Role/{name}.

11.3 Role Permissions

Role Permissions (RolePermission) define the granular access rights for each role on each document type. They are stored as a child table within the Role document.

RolePermission Schema

Table View Columns

When viewing permissions in the Role form, the table shows:

Additional permissions are accessible via the row quick edit (click a row to expand).

The ifOwner Flag

The ifOwner flag is a powerful feature that restricts a permission to only apply when the current user is the owner (creator) of the document:

This is useful for creating roles where users can manage their own documents but not others'. For example, a "Sales User" role might have:

• SalesInvoice → Read (ifOwner: false), Write (ifOwner: true), Create, Submit (ifOwner: true)
• This means: can view all invoices, but can only edit/submit their own

Setting Up Permissions

Via Role Form

1. Open a Role (e.g., Setup → Roles → Sales User)
2. Scroll to the Permissions section
3. Click Add Row
4. Select a Document Type from the dropdown
5. Toggle the permission checkboxes as needed
6. Enable If Owner if the permission should be owner-restricted
7. Save the role

Via Code (Programmatic)

The setRolePermission() function in src/utils/auth.ts provides programmatic permission management:

Permission Resolution

When checking if a user can perform an action, the system:

1. Gets all roles assigned to the user (including automatic roles like All)
2. For each role, checks the RolePermission entries for the target doctype
3. If any role grants the permission → ALLOW (union of all role permissions)
4. If the granting permission has ifOwner set → checks document ownership
5. If no role grants the permission → falls through to document sharing check

11.4 Document Sharing

Document Sharing (DocShare) lets you grant access to specific documents to users who may not have full doctype-level permissions. This is useful for collaboration scenarios where you want to share a particular invoice or report with a colleague without giving them access to all documents of that type.

DocShare Schema

Sharing a Document

Via the UI

1. Navigate to Setup → Document Shares from the sidebar
2. Click + New Document Share
3. Select the User to share with
4. Enter the Document Type (e.g., SalesInvoice)
5. Enter the Document Name (e.g., SINV-00042)
6. Configure access levels (Read, Write, Share, Submit)
7. Save

Via the Permission Manager (Programmatic)

The shareDocument() method is available on both the AuthService and PermissionManager:

Share with Everyone

Setting the everyone flag to true makes the document accessible to all authenticated users without specifying individual users. This is checked during permission evaluation — if any DocShare record exists with everyone: true and the matching doctype/name, the permission is granted.

Share Permission Checking

When the role-based permission check denies access, the system performs a secondary check:

1. Look for DocShare records matching { shareDocType, shareName, user } (direct share)
2. Look for DocShare records matching { shareDocType, shareName, everyone: true } (everyone share)
3. Check the access field (readAccess, writeAccess, shareAccess, submitAccess) corresponding to the requested permission
4. If either check finds a match → ALLOW

Managing Shares

11.5 Session Management

NkapBooks tracks user sessions to provide security monitoring, multi-device support, and automatic session cleanup.

Session Schema

Session Lifecycle

Login Request
    │
    ▼
┌──────────────┐     ┌──────────────┐
│ Authenticate │────►│ Create       │
│ Credentials  │     │ Session      │
└──────────────┘     └──────┬───────┘
                            │
                            ▼
                    ┌──────────────┐
                    │ Active       │◄──── Refresh / Activity
                    │ Session      │
                    └──────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
              ▼             ▼             ▼
      ┌──────────┐  ┌──────────┐  ┌──────────┐
      │ Logout   │  │ Timeout  │  │ Lock     │
      │ (Manual) │  │ (Auto)   │  │ (Idle)   │
      └──────────┘  └──────────┘  └──────┬───┘
                                          │
                                          ▼
                                  ┌──────────────┐
                                  │ Unlock       │
                                  │ (Password)   │
                                  └──────────────┘

Session Operations

Viewing Sessions

Navigate to Setup → Sessions to see all active sessions. The list view shows:

Session Security Features

11.6 Authentication

Authentication in NkapBooks is controlled by the AuthSettings schema (accessible via Settings → Authentication tab) and the AuthService class.

AuthSettings Schema

The AuthSettings is a singleton document organized into six sections:

General Section

Password Section

Session Section

Two-Factor Section

Security Section

API Section

Registration Section

Login Flow

User enters email/username + password
    │
    ▼
┌──────────────────────┐
│ AuthDemux.login()    │──── Tauri backend command
└──────────┬───────────┘
           │
           ▼
   ┌───────────────┐     ┌──────────────────┐
   │ Credentials   │─NO─►│ Return error     │
   │ Valid?        │     │ (increment fails) │
   └───────┬───────┘     └──────────────────┘
           │ YES
           ▼
   ┌───────────────┐     ┌──────────────────┐
   │ Account       │─YES►│ Return lockout   │
   │ Locked?       │     │ error            │
   └───────┬───────┘     └──────────────────┘
           │ NO
           ▼
   ┌───────────────┐     ┌──────────────────┐
   │ 2FA           │─YES►│ Return 2FA       │
   │ Required?     │     │ challenge        │
   └───────┬───────┘     └──────────────────┘
           │ NO
           ▼
   ┌───────────────┐
   │ Create Session│──── Session token stored
   │ Return Success│     via Tauri Stronghold
   └───────────────┘

Password Management

NkapBooks provides several password management operations:

API Key Management

When allowApiKeys is enabled in AuthSettings, users can generate API keys for programmatic access:

User Registration

When allowPublicRegistration is enabled, new users can register through the application:

1. The system creates a new User document with the provided details
2. Assigns the default role configured in AuthSettings
3. If requireEmailVerification is enabled, sends a verification email
4. Sets the user's password through the secure Tauri backend

11.7 Permission System Architecture

The PermissionManager (fyo/core/permissionManager.ts) is the central engine that evaluates all permission checks in NkapBooks. It is accessed through fyo.perm and provides both simple boolean checks and detailed permission results.

Permission Check Flow

Every permission check follows this decision tree:

Bypass Doctypes

The following core system doctypes always bypass permission checks — they are essential for the application to function:

Additionally, auth-related doctypes (User, Role, UserRole, RolePermission, Session, DocShare) bypass permission checks during initial setup before permissions are configured.

Permission Caching

The PermissionManager uses a two-level cache for performance:

The cache is automatically cleared when:

• A User document is modified → clears that user's cached roles and permissions
• A Role document is modified → clears the entire permission cache
• clearCache() is called explicitly

Key API Methods

Simple Permission Checks

Detailed Permission Checks

The PermissionCheckResult object contains:

Document-Level Checks

Discovery Methods

Validation Methods

Vue Composables

NkapBooks provides Vue composables for permission-aware UI development:

useAuth()

Returns reactive references for the current authentication state:

usePermissions()

Returns permission-checking helpers:

useRolePermissions()

Returns comprehensive role permission utilities for UI components.

Route-Level Protection

NkapBooks uses Vue Router meta fields to enforce permissions at the route level:

Example route definitions:

11.8 Best Practices

Role Design

Security Configuration

Document Sharing