PrivateBin/.github/copilot-instructions.md

Copilot Coding Agent Onboarding for PrivateBin

Repository Overview

PrivateBin is a minimalist, open-source online pastebin where the server has zero knowledge of the pasted data. All data is encrypted/decrypted in the browser via 256-bit AES (Galois Counter Mode). The project is a refactored fork of ZeroBin focused on extensibility and additional features.

• Main Use Case: Secure, ephemeral sharing of text/code, with encryption happening exclusively client-side.
• Languages: PHP (~48%), JavaScript (~35%), CSS (~17%), with some legacy browser support (see legacy.js).
• Type: Web application (pastebin), with both server (PHP) and client (JavaScript) components.

Build & Validation Instructions

Prerequisites

• PHP: 7.4+ (recommended: latest stable 7.x or 8.x)
• Composer: For dependency management (composer install)
• Node.js & npm: Only required for running JavaScript unit tests. Main JS logic must remain browser-compatible!
• Recommended Environment: Unix-like OS (Linux, macOS) with Apache or Nginx for full demo.

Bootstrap & Install

1. Clone the repository and enter its root directory.

2. Install PHP dependencies:

   composer install
   

   • Always run this before building or testing PHP code.
   • If you receive permission errors, verify vendor/ is writable.

3. Install JS dependencies (for test only):

   cd ./js
   npm install
   

   • Only required for running JS tests. Not needed for building or running the app.

Build

• No explicit build step for PHP. The web app is served directly from source.
  • This means composer directory need to be comitted (except of big optional dependences like Google Cloud like GCS support or similar!)
• For JavaScript: There is no webpack/bundler step for release; browser JS is written in compatible ES6+ syntax, except in legacy.js (which must be designed to run cleanly even on ancient IE4 or Netscape to display the error message that a browser upgrade is necessary). We are trying to avoid jQuery in any new code and would like to eventually drop use of jQuery. We are considering modularizing the JS logic, but need to ensure to do so in a way that will work both in the browser as well as for node JS driven unit tests.

Run

• PHP Server Mode: Use Apache/Nginx with PHP, pointing the web root to the repo root.
• Demo: Open index.php in a browser (via your web server).

Test

• PHP Unit Tests:

  vendor/bin/phpunit
  

  • Always run after code changes to backend logic.
  • If vendor/bin/phpunit does not exist, ensure composer install completed without errors.

  cd ./js
  npm run test
  

  • Runs Jasmine-based tests in Node.js context.
  • Note: Production JS must not use Node-only APIs. Test code may use Node.js features, but main JS logic must remain browser-compatible.
  • If you encounter ReferenceError for browser features, ensure only test code uses Node.js APIs.

Lint

• PHP: Run (if phpcs.xml or similar config exists):

  vendor/bin/phpcs
  

• JavaScript: If eslint is present:

  npm run lint
  

  • Check for configuration in .eslintrc.* files.

Validation / CI

• GitHub Actions: CI runs composer install, phpunit, and JS tests on PRs and pushes.
• Pre-commit: Always run both PHP and JS tests before submitting PRs. Fix any warnings or errors.

Project Layout & Structure

• Root files:

  • README.md: Project overview (view full).
  • composer.json, composer.lock: PHP dependencies.
  • package.json: JS test/lint dependencies (not for production JS).
  • .github/workflows/: CI configuration.
  • cfg/: Default configuration files.
  • js/: Main client logic (browser JS), including:
    • legacy.js: Must remain compatible with legacy browsers (ES3). Do not use modern JS here.
    • privatebin.js: Core encryption and paste interface logic.
  • tpl/: HTML templates.
  • css/: Stylesheets.

• Testing & Validation:

  • tst/: Contains PHP unit tests.

  • js/test: Contains JS unit tests.

  • phpunit.xml: PHPUnit config.

  • JS test files may use Node.js features; browser JS must not.

  • Encryption: Only client-side in JS with WebCrypto.

  • Backend: Serves encrypted blobs, never sees plaintext.

  • Legacy Support: js/legacy.js must remain ES3 for feature detection in old browsers.

  • Configuration: See cfg/conf.php and wiki for available options.

Automated Checks

• GitHub CI: On PRs, runs composer install, phpunit, and JS tests.
• Validation Steps: PRs failing tests will be blocked. Always ensure a clean test run before submitting.

Guidance for Copilot Agent

• Trust these instructions. Only perform a search if information is missing or appears incorrect.
• Do NOT use Node.js APIs in production JS code. Only test code may do so.
• Never modernize legacy.js. It must work in very old browsers.
• Always run composer install before PHP tests, and npm install before JS tests.
• Validate all changes by running both PHP and JS tests.
• Review .github/workflows/ for the latest validation pipeline steps.