applications/pass-extension/README.md

   1 ## Extension resources
   2
   3 -   [Chrome Extension API](https://developer.chrome.com/docs/extensions/reference/runtime/)
   4 -   [Service Worker Lifecycle Reference](https://developer.chrome.com/docs/workbox/service-worker-lifecycle/)
   5 -   [⚠️ Chrome Extension SW discussion](https://stackoverflow.com/questions/66618136/persistent-service-worker-in-chrome-extension/66618269#66618269)
   6
   7 ## How to run the extension
   8
   9 Please note that all commands should be run from this directory, i.e. `applications/pass-extension`
  10
  11 On Mac, please first install `mkcert` with `brew install mkcert` (brew can be installed on https://brew.sh/) then:
  12
  13 ```bash
  14 yarn install
  15 yarn install:devtools
  16 ```
  17
  18 ### For Chromium
  19
  20 Run
  21
  22 ```bash
  23 # `yarn start` targets the internal environment by default.
  24 yarn start:prod
  25 ```
  26
  27 After that, the build is available in `dist/` directory that you can install in Chromium by going to [extension page](chrome://extensions/), enable the developer mode, click on "Load Unpacked" and choose the `dist/` directory here.
  28
  29 ### For Firefox
  30
  31 If you want to run the extension on Firefox, you can do:
  32
  33 ```bash
  34 BUILD_TARGET=firefox yarn start:prod
  35 ```
  36
  37 <details>
  38 <summary>To run an extension on Firefox</summary>
  39 <p>
  40 1. Open firefox and navigate to `about:debugging`
  41 2. Click on "_This Firefox_"
  42 3. Click on "_Load Temporary Add-On_" and chose the `dist/manifest.json`
  43 4. Right click on the extension icon in the toolbar and select "_Manage extension_"
  44 5. Go to the permission tab and enable all necessary permissions <sup>1</sup>
  45 6. Go back to `about:debugging` and click on "_Reload_" <sup>2</sup>
  46 7. You may sign in and start using Pass
  47
  48 > <sup>1</sup> <small>Firefox does not prompt for permissions when launching a temporary add-on </small><br /><sup>2</sup> <small>FF might not pick-up the permission changes needed for content-script communication</small>
  49
  50 </p>
  51
  52 ## How to run the extension against localhost BE
  53
  54 As a prerequisite you need to have the backend running locally.
  55
  56 ### Build the extension with the proper config
  57
  58 -   Edit `applications/pass-extension/src/app/config.ts` and set `export const API_URL = 'https://localhost:9090/api';`
  59 -   Edit `applications/pass-extension/public/manifest.json` and set `externally_connectable` to
  60
  61 ```
  62         "matches": ["https://*.proton.local/*", "https://*.proton.black/*", "https://*.proton.pink/*", "https://localhost/*", "http://localhost/*", "https://localhost:9090/*"]
  63 ```
  64
  65 -   Now the extension can be built by going to `applications/pass-extension` and running `yarn run start`
  66
  67 ### Running the web account client locally
  68
  69 We need to run web account pointing to our local backend installation. From the root of this repository run:
  70
  71 ```
  72 yarn workspace proton-account start --api=https://localhost --port 8081
  73 ```
  74
  75 This will run the web account listening at port 8081 but chrome requires the extension to connect to sites with TLS enabled and the dev server for the web account doesn't support TLS. So we need to run something in front of it that will take care of the TLS termination and proxy the requests to the local web account. We can do that with [Caddy webserver](https://caddyserver.com/) in proxy mode. To do so, create a file called `Caddyfile` with the following contents:
  76
  77 ```
  78 {
  79         http_port 9080
  80 }
  81
  82 https://localhost:9090 {
  83                 reverse_proxy http://localhost:8081
  84                 header Access-Control-Allow-Origin *
  85                 header -Server
  86 }
  87 ```
  88
  89 and run `caddy` from the directory where the file is. Caddy should generate automatically a cert and export https via port 9090. Requests sent there will be forwarded to the web account client.
  90
  91 Now you should be able to use the extension with your local backend installation.