tessl/npm-parse-dashboard

A standalone dashboard for managing Parse Server apps with web interface and Express middleware integration

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Authentication

Name: tessl/npm-parse-dashboard
Author: tessl

Parse Dashboard provides a comprehensive authentication system supporting multiple users, multi-factor authentication (TOTP), read-only access controls, and per-app access restrictions.

Capabilities

User Configuration

Configuration for dashboard users and their access permissions:

interface UserConfig {
  /**
   * Username for login
   */
  user: string;
  
  /**
   * Password (plain text or bcrypt hash)
   * Use bcrypt hash when useEncryptedPasswords is true
   */
  pass: string;
  
  /**
   * Read-only access flag (optional)
   * When true, user cannot modify data
   */
  readOnly?: boolean;
  
  /**
   * App-specific access restrictions (optional)
   * If specified, user can only access these apps
   */
  apps?: UserAppConfig[];
  
  /**
   * MFA secret (optional)
   * Base32-encoded TOTP secret for two-factor authentication
   */
  mfa?: string;
  
  /**
   * MFA algorithm (optional)
   * TOTP algorithm: SHA1, SHA256, SHA512
   * Default: SHA1
   */
  mfaAlgorithm?: string;
  
  /**
   * MFA digits (optional)
   * Number of digits in TOTP code
   * Default: 6
   */
  mfaDigits?: number;
  
  /**
   * MFA period (optional)
   * TOTP period in seconds
   * Default: 30
   */
  mfaPeriod?: number;
}

interface UserAppConfig {
  /**
   * App ID the user can access
   */
  appId: string;
  
  /**
   * Read-only access for this specific app
   */
  readOnly?: boolean;
}

Authentication Class

Core authentication functionality (internal use):

class Authentication {
  /**
   * Creates authentication instance
   * @param validUsers - Array of valid user configurations
   * @param useEncryptedPasswords - Whether passwords are bcrypt hashed
   * @param mountPath - Dashboard mount path for redirects
   */
  constructor(validUsers: UserConfig[], useEncryptedPasswords: boolean, mountPath: string);
  
  /**
   * Initialize authentication middleware
   * @param app - Express application instance
   * @param options - Authentication options
   */
  initialize(app: Express.Application, options: AuthOptions): void;
  
  /**
   * Authenticate user credentials
   * @param userToTest - User credentials to verify
   * @param usernameOnly - Whether to check username only
   * @returns Authentication result
   */
  authenticate(userToTest: any, usernameOnly?: boolean): Promise<AuthResult>;
}

interface AuthOptions {
  cookieSessionSecret?: string;
  cookieSessionMaxAge?: number;
  mountPath?: string;
}

interface AuthResult {
  isAuthenticated: boolean;
  matchingUsername: string;
  otpMissingLength: number | false;
  otpValid: boolean;
  appsUserHasAccessTo: string[] | null;
  isReadOnly: boolean;
}

CLI Authentication Helpers

Interactive utilities for managing users and MFA:

interface CLIHelper {
  /**
   * Interactive user creation utility
   * Prompts for username, password, and generates bcrypt hash
   */
  createUser(): Promise<void>;
  
  /**
   * Interactive MFA setup utility
   * Generates TOTP secret and displays QR code
   */
  createMFA(): Promise<void>;
}

Authentication Examples:

// Basic user authentication
const dashboardWithAuth = new ParseDashboard({
  apps: [{ /* app config */ }],
  users: [
    {
      user: 'admin',
      pass: 'securePassword123'
    },
    {
      user: 'viewer',
      pass: 'viewerPassword',
      readOnly: true
    }
  ]
});

// Multi-factor authentication setup
const dashboardWithMFA = new ParseDashboard({
  apps: [{ /* app config */ }],
  users: [
    {
      user: 'admin',
      pass: 'password123',
      mfa: 'JBSWY3DPEHPK3PXP',  // Base32 secret
      mfaAlgorithm: 'SHA1',
      mfaDigits: 6,
      mfaPeriod: 30
    }
  ],
  useEncryptedPasswords: false
});

// Bcrypt encrypted passwords
const dashboardWithEncryption = new ParseDashboard({
  apps: [{ /* app config */ }],
  users: [
    {
      user: 'admin',
      pass: '$2b$10$xyz...'  // bcrypt hash
    }
  ],
  useEncryptedPasswords: true
});

// App-specific user access
const dashboardWithAppAccess = new ParseDashboard({
  apps: [
    { appId: 'prod-app', /* ... */ },
    { appId: 'dev-app', /* ... */ },
    { appId: 'test-app', /* ... */ }
  ],
  users: [
    {
      user: 'admin',
      pass: 'adminPass'
      // Admin has access to all apps
    },
    {
      user: 'developer',
      pass: 'devPass',
      apps: [
        { appId: 'dev-app' },
        { appId: 'test-app', readOnly: true }
      ]
    },
    {
      user: 'viewer',
      pass: 'viewPass',
      readOnly: true,
      apps: [
        { appId: 'prod-app', readOnly: true }
      ]
    }
  ]
});

// Combined MFA and app restrictions
const advancedAuth = new ParseDashboard({
  apps: [
    { appId: 'critical-app', /* ... */ },
    { appId: 'normal-app', /* ... */ }
  ],
  users: [
    {
      user: 'security-admin',
      pass: '$2b$10$hashedPassword...',
      mfa: 'JBSWY3DPEHPK3PXP',
      apps: [
        { appId: 'critical-app' }
      ]
    },
    {
      user: 'regular-user',
      pass: '$2b$10$anotherHash...',
      readOnly: true,
      apps: [
        { appId: 'normal-app', readOnly: true }
      ]
    }
  ],
  useEncryptedPasswords: true
});

Interactive User Management

Creating Users via CLI

# Generate user with bcrypt password
parse-dashboard --createUser

# This will prompt for:
# - Username
# - Password  
# - Confirm password
# And output bcrypt hash for configuration

Setting up MFA

# Generate MFA secret and QR code
parse-dashboard --createMFA

# This will:
# - Generate a random base32 secret
# - Display QR code for scanning with authenticator app
# - Show the secret for manual entry
# - Provide configuration example

Session Management

Session Configuration

const dashboard = new ParseDashboard(config, {
  cookieSessionSecret: 'your-secret-key-change-in-production',
  cookieSessionMaxAge: 7200000  // 2 hours in milliseconds
});

Environment Variables for Sessions

PARSE_DASHBOARD_COOKIE_SESSION_SECRET=your-secret-key
PARSE_DASHBOARD_COOKIE_SESSION_MAX_AGE=7200000

Security Considerations

Password Security

// Recommended: Use bcrypt for password hashing
const config = {
  users: [
    {
      user: 'admin',
      pass: '$2b$10$N9qo8uLOickgx2ZMRZoMye.Uo3vfx2u4UqOJNcYOCMy0LvP9KN.2u'
    }
  ],
  useEncryptedPasswords: true
};

// Not recommended: Plain text passwords
const insecureConfig = {
  users: [
    {
      user: 'admin',
      pass: 'plainTextPassword'  // Avoid in production
    }
  ],
  useEncryptedPasswords: false
};

Access Control Patterns

// Role-based access control
const roleBasedConfig = {
  apps: [
    { appId: 'prod', appName: 'Production' },
    { appId: 'staging', appName: 'Staging' },
    { appId: 'dev', appName: 'Development' }
  ],
  users: [
    // Super admin - full access
    {
      user: 'superadmin',
      pass: '$2b$10$...',
      mfa: 'MFA_SECRET'
    },
    // Production admin - prod + staging read
    {
      user: 'prodadmin', 
      pass: '$2b$10$...',
      apps: [
        { appId: 'prod' },
        { appId: 'staging', readOnly: true }
      ]
    },
    // Developer - dev full, staging read
    {
      user: 'developer',
      pass: '$2b$10$...',
      apps: [
        { appId: 'dev' },
        { appId: 'staging', readOnly: true }
      ]
    },
    // Viewer - read-only access to specific app
    {
      user: 'viewer',
      pass: '$2b$10$...',
      readOnly: true,
      apps: [
        { appId: 'prod', readOnly: true }
      ]
    }
  ],
  useEncryptedPasswords: true
};

Install with Tessl CLI