Psono Documentation

# Webclient Development

If you want to start to develop own features for the clients, then follow the following steps to setup your own development environment.

# Preamble

This whole guide is based on Ubuntu 22.04 LTS. Other Ubuntu and Debian based systems should be similar if not even identical.

We assume that you already have somewhere a Psono server running. If not follow the guide to setup a Psono server.

# Installation

  1. Install some generic stuff

    sudo apt-get update
sudo apt-get install -y git

  2. Clone git repository

    git clone https://gitlab.com/esaqa/psono/psono-client.git ~/psono-client

  3. Checkout new branch

    cd ~/psono-client
git fetch
git checkout develop
git checkout -b [name_of_your_new_branch]

  4. Install requirements

    This step will install node and npm and all the npm packages.

    sudo var/prep-build.sh

# Run the dev server

From this point on forward, you can develop it like any web application.

To start the dev server with the web client run the following command:

num run dev

# Build everything

To build the webclient and browser extensions, use the following three command:

npm run buildchrome
npm run buildfirefox
npm run buildwebclient

# Run Unit Tests

Issue the following command:

npm test

# Development Best Practices

# Code Quality & Testing

  • Test Coverage: Write tests for new components and services, especially security-critical functionality
  • Test Critical Paths: Always test authentication, encryption/decryption, and data handling logic
  • Mock External Dependencies: Use proper mocking for API calls and browser-specific functionality

# Security-Critical Areas

  • Cryptographic Operations: Located in src/js/services/crypto-library.js - uses NaCl/libsodium, never implement custom crypto
  • Authentication Service: src/js/services/user.js handles login/logout and session management
  • Data Storage: Client-side encryption handled in src/js/services/datastore.js and related files
  • API Communications: All server communication goes through src/js/services/api-client.js

# React/Redux Architecture

  • State Management: Uses Redux for global state, prefer immutable updates
  • Component Structure: Keep components in src/js/components/ with proper separation of concerns
  • Service Layer: Business logic belongs in src/js/services/, not in components
  • Actions/Reducers: Follow existing patterns in src/js/actions/ and src/js/reducers/

# Development Environment

# Start development server with hot reload
npm run dev

# Build specific targets
npm run buildwebclient    # Web application
npm run buildchrome       # Chrome extension  
npm run buildfirefox      # Firefox extension
npm run buildelectron     # Desktop application

# Run tests with watch mode during development
npm test -- --watch

# Code Review Focus Areas

  • Input Sanitization: All user inputs must be properly validated and sanitized
  • XSS Prevention: Use React's built-in protections, avoid dangerouslySetInnerHTML unless necessary
  • Content Security Policy: Ensure compliance with CSP headers for extensions
  • Secret Management: Never hardcode API endpoints, keys, or sensitive configuration
  • Cross-Platform Compatibility: Test changes across web, Chrome, Firefox, and Electron builds

# Extension-Specific Considerations

  • Manifest Validation: Changes to src/chrome/manifest.json or src/firefox/manifest.json require careful review
  • Content Script Security: Scripts in src/*/data/js/ run in different security contexts
  • Permission Management: Extension permissions should follow principle of least privilege

← Browser Extension →