From 207c79057b753b2cba35d7ebdbaab188f329144c Mon Sep 17 00:00:00 2001 From: rugk Date: Thu, 30 Oct 2025 13:18:30 +0100 Subject: [PATCH 1/7] Add GitHub Copilot instructions As per discussion in https://github.com/orgs/PrivateBin/discussions/1696 here are some instructions generated by Copilot itself. I used this prompt (in chat not agent mode, but well... should be enough) as suggested by GitHub: https://docs.github.com/copilot/how-tos/configure-custom-instructions/add-repository-instructions#anweisen-von-copilot-programmier-agent-zum-generieren-einer-copilot-instructionsmd-datei Also added the feedback from the discussion. --- .github/copilot-instructions.md | 118 ++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..00dd1928 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,118 @@ +# 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.0+ (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:** + ```sh + 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):** + ```sh + 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. +- **For JavaScript:** There is no webpack/bundler step for release; browser JS is written in compatible ES5+ syntax except in `legacy.js` (ES3). + +### Run + +- **PHP Server Mode:** Use Apache/Nginx with PHP, pointing the web root to the repo root or the `public/` directory (if present). +- **Demo:** Open `index.php` in a browser (via your web server). + +### Test + +- **PHP Unit Tests:** + ```sh + vendor/bin/phpunit + ``` + - Always run after code changes to backend logic. + - If `vendor/bin/phpunit` does not exist, ensure `composer install` completed without errors. + +- **JavaScript Unit Tests:** + ```sh + npm 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): + ```sh + vendor/bin/phpcs + ``` +- **JavaScript:** If `eslint` is present: + ```sh + 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:** + - `index.php`: Main server entry point. + - `README.md`: Project overview ([view full](https://github.com/PrivateBin/PrivateBin/blob/9d7508f44fac95dfadf4aad4fb3d3be128633336/README.md)). + - `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.** + - `main.js`: Core encryption and paste interface logic. + - `tpl/`: HTML templates. + - `css/`: Stylesheets. + +- **Testing & Validation:** + - `test/`: Contains PHP and JS unit tests. + - `phpunit.xml`: PHPUnit config. + - JS test files may use Node.js features; browser JS must not. + +- **Key architectural notes:** + - **Encryption:** Only client-side in JS. + - **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.** From 55fcca0f8dead4dccc7a4a229ca8bdb93a6db606 Mon Sep 17 00:00:00 2001 From: rugk Date: Thu, 30 Oct 2025 13:21:59 +0100 Subject: [PATCH 2/7] Add information about Composer dir --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 00dd1928..a77b552d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -36,6 +36,7 @@ ### 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 ES5+ syntax except in `legacy.js` (ES3). ### Run From baa01170283c9c4d4e61e734dbad358f4247ab59 Mon Sep 17 00:00:00 2001 From: rugk Date: Thu, 30 Oct 2025 15:11:16 +0000 Subject: [PATCH 3/7] wipfix: apply doc fixes from contributors --- .github/copilot-instructions.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a77b552d..5bbc8838 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,7 +12,7 @@ ### Prerequisites -- **PHP:** 7.0+ (recommended: latest stable 7.x or 8.x) +- **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. @@ -29,6 +29,7 @@ 3. **Install JS dependencies (for test only):** ```sh + cd ./js npm install ``` - Only required for running JS tests. Not needed for building or running the app. @@ -53,9 +54,9 @@ - Always run after code changes to backend logic. - If `vendor/bin/phpunit` does not exist, ensure `composer install` completed without errors. -- **JavaScript Unit Tests:** ```sh - npm test + 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. @@ -81,28 +82,27 @@ ## Project Layout & Structure - **Root files:** - - `index.php`: Main server entry point. - - `README.md`: Project overview ([view full](https://github.com/PrivateBin/PrivateBin/blob/9d7508f44fac95dfadf4aad4fb3d3be128633336/README.md)). + - `README.md`: Project overview ([view full](../README.md)). - `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.** - - `main.js`: Core encryption and paste interface logic. + - `privatebin.js`: Core encryption and paste interface logic. - `tpl/`: HTML templates. - `css/`: Stylesheets. - **Testing & Validation:** - - `test/`: Contains PHP and JS unit tests. + - `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. -- **Key architectural notes:** - - **Encryption:** Only client-side in JS. + - **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. + - **Configuration:** See `cfg/conf.php` and [wiki](https://github.com/PrivateBin/PrivateBin/wiki/Configuration) for available options. ## Automated Checks From 46599af4f0bd319a86bc0e0058c09e3175cfc090 Mon Sep 17 00:00:00 2001 From: rugk Date: Sun, 2 Nov 2025 17:47:12 +0100 Subject: [PATCH 4/7] Add note about jQuery dropping Co-authored-by: El RIDO --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5bbc8838..4b25cfca 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -38,7 +38,7 @@ - **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 ES5+ syntax except in `legacy.js` (ES3). +- **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 From 4f64ad3b12520cdb8fd7d298aedd24c025f6afb0 Mon Sep 17 00:00:00 2001 From: rugk Date: Sun, 2 Nov 2025 17:49:26 +0100 Subject: [PATCH 5/7] docs: remove wrong public dir advise Co-authored-by: El RIDO --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4b25cfca..b744e78f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -42,7 +42,7 @@ ### Run -- **PHP Server Mode:** Use Apache/Nginx with PHP, pointing the web root to the repo root or the `public/` directory (if present). +- **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 From 42df559d3c91a8ef34f2f389481f7a98acfbf6c9 Mon Sep 17 00:00:00 2001 From: rugk Date: Tue, 11 Nov 2025 19:52:12 +0100 Subject: [PATCH 6/7] docs: update how to open Co-authored-by: El RIDO --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b744e78f..87daf532 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -43,7 +43,7 @@ ### 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). +- **Demo:** Open the root directory served by the web server in a browser. This should call the index.php in the repositories root directory. ### Test From f4216b34dfc63433f2c5a57889b75a806f3c59dc Mon Sep 17 00:00:00 2001 From: rugk Date: Wed, 12 Nov 2025 19:36:05 +0100 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: El RIDO --- .github/copilot-instructions.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 87daf532..e004b740 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -22,7 +22,7 @@ 1. **Clone the repository** and enter its root directory. 2. **Install PHP dependencies:** ```sh - composer install + composer require --global google/cloud-storage phpunit/phpunit ``` - Always run this before building or testing PHP code. - If you receive permission errors, verify `vendor/` is writable. @@ -58,7 +58,7 @@ cd ./js npm run test ``` - - Runs Jasmine-based tests in Node.js context. + - Runs Mocha-based tests in Node.js context. Tests are implemented in BDD-Style or using jsVerify fixtures for property-based tests. - 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. @@ -76,7 +76,7 @@ ### Validation / CI -- **GitHub Actions:** CI runs `composer install`, `phpunit`, and JS tests on PRs and pushes. +- **GitHub Actions:** CI runs `composer install`, `phpunit`, and `mocha` tests on PRs and pushes, as well as external tools such as style checkers and linters. - **Pre-commit:** Always run both PHP and JS tests before submitting PRs. Fix any warnings or errors. ## Project Layout & Structure @@ -84,10 +84,10 @@ - **Root files:** - `README.md`: Project overview ([view full](../README.md)). - `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: + - `package.json`: JS test/lint dependencies (not for production JS). - `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. @@ -99,10 +99,10 @@ - `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](https://github.com/PrivateBin/PrivateBin/wiki/Configuration) for available options. + - **Encryption:** Only client-side in JS using the browsers WebCrypto API. + - **Backend:** Serves encrypted blobs (as base64 encoded strings) and plaintext meta data in JSON format. APIs are designed for WORM (write once, read many) usage. Once stored content is never updated, only deleted, if delete token is sent, has expired as per meta data or immediately upon reading for the first time, if meta data was set to burn-after-reading. + - **Legacy Support:** `js/legacy.js` must remain compatible with IE4 and Netscape for feature detection of ancient browsers. + - **Configuration:** See `cfg/conf.sample.php` and the [wiki](https://github.com/PrivateBin/PrivateBin/wiki/Configuration) for available options. All option defaults are defined in `lib/Configuration.php` ## Automated Checks