Users API (Pending)

Migration Pending

This API is pending migration to Cloudflare Workers.

The Users API provides user management, role assignment, and access control.

Planned Procedures

Procedure	Type	Description
users.getAll	Query	Get all users (admin only)
users.getById	Query	Get user by ID
users.create	Mutation	Create new user
users.update	Mutation	Update user profile
users.delete	Mutation	Delete user
users.updateRole	Mutation	Change user role
users.resetPassword	Mutation	Reset user password
users.getActivity	Query	Get user activity log

Data Model

User

interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  role: UserRole;
  phone?: string;
  avatar?: string;
  department?: string;
  isActive: boolean;
  lastLogin?: Date;
  createdAt: Date;
  updatedAt: Date;
}

User Role

enum UserRole {
  ADMIN = "ADMIN",           // Full system access
  OPERATOR = "OPERATOR",     // Monitor & manage operations
  ANALYST = "ANALYST",       // View reports & analytics
  FIELD = "FIELD",           // Field operations
  VIEWER = "VIEWER"          // Read-only access
}

Role Permissions

Permission	Admin	Operator	Analyst	Field	Viewer
View Dashboard	Yes	Yes	Yes	Yes	Yes
Manage Sensors	Yes	Yes	No	No	No
View Reports	Yes	Yes	Yes	No	Yes
Generate Reports	Yes	Yes	Yes	No	No
Manage Incidents	Yes	Yes	No	Yes	No
Manage Users	Yes	No	No	No	No
System Settings	Yes	No	No	No	No

Planned Input Schemas

Create User

{
  email: string;               // Required, valid email
  password: string;            // Required, min 8 chars
  firstName: string;           // Required
  lastName: string;            // Required
  role: UserRole;              // Default: VIEWER
  phone?: string;
  department?: string;
}

Update User

{
  id: string;                  // Required
  firstName?: string;
  lastName?: string;
  phone?: string;
  department?: string;
  avatar?: string;             // URL or base64
  isActive?: boolean;
}

Query Users

{
  skip?: number;
  take?: number;
  search?: string;             // Search email, name
  role?: UserRole;
  department?: string;
  isActive?: boolean;
  sortBy?: "firstName" | "email" | "role" | "lastLogin" | "createdAt";
  sortOrder?: "asc" | "desc";
}

Reset Password

{
  userId: string;              // Required
  newPassword?: string;        // If not provided, generates random
  sendEmail?: boolean;         // Send password reset email
}

Expected Responses

Get All Users

{
  "users": [
    {
      "id": "user-001",
      "email": "admin@itms.solutions",
      "firstName": "System",
      "lastName": "Administrator",
      "role": "ADMIN",
      "department": "IT",
      "isActive": true,
      "lastLogin": "2024-11-15T14:30:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "user-002",
      "email": "operator@itms.solutions",
      "firstName": "John",
      "lastName": "Operator",
      "role": "OPERATOR",
      "department": "Operations",
      "isActive": true,
      "lastLogin": "2024-11-15T12:00:00.000Z",
      "createdAt": "2024-03-15T00:00:00.000Z"
    }
  ],
  "total": 25,
  "pageCount": 3
}

Get User Activity

{
  "userId": "user-001",
  "activities": [
    {
      "action": "LOGIN",
      "timestamp": "2024-11-15T14:30:00.000Z",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0..."
    },
    {
      "action": "SENSOR_CREATE",
      "timestamp": "2024-11-15T14:35:00.000Z",
      "details": { "sensorId": "sensor-005" }
    },
    {
      "action": "REPORT_GENERATE",
      "timestamp": "2024-11-15T15:00:00.000Z",
      "details": { "reportType": "WEEKLY" }
    }
  ],
  "totalActivities": 150
}

Security Considerations

Password Requirements

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Password Storage

• Hashed using bcrypt
• Salt rounds: 10
• Never stored in plain text

Session Management

• JWT tokens expire after 24 hours
• Refresh tokens for extended sessions
• Token blacklist for logout

Audit Log

All user actions are logged:

interface AuditLog {
  id: string;
  userId: string;
  action: string;
  resource: string;
  resourceId?: string;
  details?: Record<string, any>;
  ipAddress: string;
  userAgent: string;
  timestamp: Date;
}

D1 Schema

-- Users table already exists from auth migration

-- Activity log
CREATE TABLE user_activity (
  id TEXT PRIMARY KEY,
  userId TEXT NOT NULL,
  action TEXT NOT NULL,
  resource TEXT,
  resourceId TEXT,
  details TEXT,
  ipAddress TEXT,
  userAgent TEXT,
  createdAt TEXT NOT NULL,
  FOREIGN KEY (userId) REFERENCES User(id)
);

CREATE INDEX idx_activity_user ON user_activity(userId);
CREATE INDEX idx_activity_created ON user_activity(createdAt);
CREATE INDEX idx_activity_action ON user_activity(action);

Related APIs

• Authentication - Login and token management
• Incidents - User assignments
• Reports - Report ownership