### Install and Build WebExtension Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/README.md Steps to install project dependencies using npm and build the add-on for deployment. This involves running npm install to fetch packages and npm run build to compile the extension assets. ```bash npm install ``` ```bash npm run build ``` -------------------------------- ### Secure Proxy General Events Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Defines general operation and error events for the Secure Proxy extension, including installation and update notifications. These events are logged under the 'secure.proxy' category. ```APIDOC APIDOC: Secure Proxy General Events category: secure.proxy Event: general Fires when the extension detects a generic operation/error. Objects: - otherProxyInUse: Another proxy setting has been detected. - settingsShown: The settings view is shown. - loadingError: The loading of the panel fails (based on a timer). - install: The extension has been installed. value: The version number. - update: The extension has been updated. value: The version number. - panelShown: The proxy panel has been opened. ``` -------------------------------- ### Run WebExtension Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/README.md Command to start the development server for the Firefox extension. It internally uses the 'web-ext run' command, which allows for live reloading and debugging. Refer to web-ext documentation for advanced configuration. ```bash npm start ``` ```bash web-ext run ``` -------------------------------- ### Secure Proxy Upsell Click Events Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Logs user clicks on upsell entry points within the Secure Proxy extension, such as navigating to a payment required page. ```APIDOC APIDOC: Secure Proxy Upsell Click Events category: secure.proxy Event: upsell_clicks Fires when the user clicks on one of the upsell entry points. Objects: - paymentRequired: User navigates to the payment required page. (user-interaction) ``` -------------------------------- ### Secure Proxy Settings URL Click Events Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Tracks user interactions with various URLs within the settings view of the Secure Proxy extension. These events help understand user engagement with support and policy links. ```APIDOC APIDOC: Secure Proxy Settings URL Click Events category: secure.proxy Event: settings_url_clicks Fires when the user interacts with the settings view. Objects: - manageAccount: The user clicks on the manage account URL. (user-interaction) - contactUs: The user clicks on the contact us URL. (user-interaction) - helpAndSupport: The user clicks on the help & support URL. (user-interaction) - cloudflare: The user clicks on the Cloudflare URL. (user-interaction) - privacyPolicy: The user clicks on privacy & policy URL. (user-interaction) - termsAndConditions: The user clicks on terms & conditions URL. (user-interaction) - giveUsFeedback: The user clicks on give-us-a-feedback URL. (user-interaction) ``` -------------------------------- ### Secure Proxy FXA Authentication Events Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Logs authentication events related to the Firefox Accounts (FXA) flow within the Secure Proxy extension. These events track the lifecycle of the authentication process. ```APIDOC APIDOC: Secure Proxy FXA Authentication Events category: secure.proxy Event: fxa Fires when there are authentication events. Objects: - authStarted: The user has started the authentication flow. (user-interaction) - authCompleted: The user has completed the authentication flow. - authFailed: The authentication flow has terminated with an error. - authFailedByGeo: The authentication flow has terminated with a geo-restriction error. ``` -------------------------------- ### Register Telemetry Events in JavaScript Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Demonstrates how to register telemetry events using the browser.telemetry.registerEvents API. This function defines the structure for event categories, methods, objects, and optional extra data, which is a prerequisite for recording events. ```javascript browser.telemetry.registerEvents("eventcategory", { "eventName": { methods: ["click", ... ], // types of events that can occur objects: ["aButton", ... ], // objects event can occur on extra: {"key": "value", ... } // key-value pairs (strings) } }) ``` -------------------------------- ### Secure Proxy State Change Events Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Logs changes in the proxy's operational state, such as enabling or disabling the proxy via user interaction. Includes extension version information. ```APIDOC APIDOC: Secure Proxy State Change Events category: secure.proxy Event: state Fires when the proxy state changes. Objects: - proxyEnabled: The proxy is enabled by user-interaction. value: Only stateButton for now. extra: version, the extension version. (user-interaction) - proxyDisabled: The proxy is disabled by user-interaction. value: Only stateButton for now. extra: version, the extension version. (user-interaction) ``` -------------------------------- ### SPS REST API Authentication Endpoints Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/authentication.md This section details the various endpoints of the Secure Proxy Server (SPS) REST API used for authentication. It covers requests for state tokens, finalizing authentication with FxA codes, retrieving user info, and generating new tokens, including their request methods, paths, content types, request bodies, responses, and potential error codes. ```APIDOC SPS REST API Authentication: This API manages the authentication flow for the secure-proxy. 1. State Token Request: - Purpose: Obtains a state token from SPS. - Request: - Path: /browser/oauth/state - Method: GET - Content-type: application/json - Response: - Status: 201 - Body: { "state": "ok", "state_token": "", "scopes": [], "client_id": "", "access_type": "", "authorization_endpoint": "" } - Content-type: application/json 2. Finalize Authentication Request: - Purpose: Completes the authentication process using an FxA code and state token. - Request: - Path: /browser/oauth/authenticate - Method: POST - Content-type: application/json - Body: { "state_token": "", "fxa_code": "" } - Response: - Status: 200 - Content-type: application/json - Body: { "state": "ok", "proxy_token": "" } - Error Codes: - 400: Missing or invalid state_token or fxa code. 3. Info Request: - Purpose: Retrieves information about the current proxy tokens used by the user. - Request: - Path: /browser/oauth/info - Method: POST - Content-type: application/json - Body: { "state_token": "" } - Response: - Status: 200 - Content-type: application/json - Body: { "state": "ok", "proxy_token": "" } - Error Codes: - 400: Missing or invalid state_token or fxa code. 4. New Token Request: - Purpose: Generates a new proxy token. - Request: - Path: /browser/oauth/token - Method: POST - Content-type: application/json - Body: { "state_token": "" } - Response: - Status: 200 - Content-type: application/json - Body: { "state": "ok", "proxy_token": "" } - Error Codes: - 400: Missing or invalid state_token or fxa code. - 402: No tokens available for the current user. ``` -------------------------------- ### Secure Proxy Bandwidth Scalar Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Collects scalar data for the amount of kbytes sent and received while the Secure Proxy is in use. This data is logged under the 'secure.proxy' category. ```APIDOC APIDOC: Secure Proxy Bandwidth Scalar category: secure.proxy Scalar: bandwidth Contains the amount of kbytes sent and received when the proxy is in use. ``` -------------------------------- ### SPS REST API: State Token Request Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/authentication_jwt.md Requests a state token from the secure-proxy API to initiate the authentication flow. The response includes the state token, FxA client ID, and authorization endpoint. ```APIDOC SPS REST API: State Token Request Request: Path: /browser/oauth/state Method: GET Content-type: application/json Response: State: 201 Body: { "state": "ok", "state_token": "", "scopes": [], "client_id": "", "access_type": "", "authorization_endpoint": "" } Content-type: application/json ``` -------------------------------- ### Secure Proxy Networking Error Events Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/metrics.md Tracks proxy network errors encountered by the Secure Proxy extension, including specific HTTP status codes and connectivity issues. ```APIDOC APIDOC: Secure Proxy Networking Error Events category: secure.proxy Event: networking Fires when there is a proxy network error. Objects: - 407: A 407 error code has been received (invalid/expired token). - 429: The proxy returns 429 when the user is abusing the service. - 502: The proxy returns 502. This error is tracked. - connecting: The proxy is unreachable during the connecting phase. - proxyDown: The proxy seems unreachable. ``` -------------------------------- ### SPS REST API: Info Request Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/authentication_jwt.md Retrieves information about the current proxy tokens used by the user. Requires a valid state token. ```APIDOC SPS REST API: Info Request Request: Path: /browser/oauth/info Method: POST Content-type: application/json Body: { "state_token": "" } Response: State: 200 Content-type: application/json Body: { "state": "ok", "proxy_token": "" } Possible error codes: 400 - missing or invalid state_token or fxa code. ``` -------------------------------- ### SPS REST API: Finalize Authentication Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/authentication_jwt.md Finalizes the authentication process by sending the FxA code and state token to the secure-proxy API. It returns the current proxy token if it exists. ```APIDOC SPS REST API: Finalize Authentication Request Request: Path: /browser/oauth/authenticate Method: POST Content-type: application/json Body: { "state_token": "", "fxa_code": "" } Response: State: 200 Content-type: application/json Body: { "state": "ok", "proxy_token": "" } Possible error codes: 400 - missing or invalid state_token or fxa code. ``` -------------------------------- ### SPS REST API: New Token Request Source: https://github.com/mozilla-extensions/secure-proxy/blob/master/docs/authentication_jwt.md Requests a new proxy token generation. This endpoint requires a valid state token and may return an error if no tokens are available. ```APIDOC SPS REST API: New Token Request Request: Path: /browser/oauth/token Method: POST Content-type: application/json Body: { "state_token": "" } Response: State: 200 Content-type: application/json Body: { "state": "ok", "proxy_token": "" } Possible error codes: 400 - missing or invalid state_token or fxa code. 402 - no tokens available for the current user. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.