add global npm install ability

Author: sam-mfb

README.md

@@ -32,9 +32,39 @@ This utility works by changing the flow above as follows using a client-server p
 
 This helper is written in Typescript and compiles down to two Javascript scripts, one for the server and one for the client.
 
-### Download
+### Option 1: Install via npm (Recommended)
 
-Download the latest release from this repo. The release consists of a filed named `oauth2-forwarder.zip` which contains two Javascript scripts: `o2f-server.js` and `o2f-client.js` plus a helper `browser.sh` script, all in a directory called `o2f`. These can be placed wherever you want, but these instructions assume they are placed in the home directories of the host and container.
+You can install oauth2-forwarder globally via npm:
+
+```bash
+npm install -g oauth2-forwarder
+```
+
+After installation, you'll have the following commands available globally:
+- `o2f-server` - Run on the host machine
+- `o2f-client` - Run on the container
+- `o2f-browser` - Browser script for the container
+
+#### On the host
+
+Run `o2f-server` on the host machine. This will start the server and display the port it's listening on.
+
+#### In the container
+
+1. Set the server info environment variable based on the output from the host:
+   ```bash
+   export OAUTH2_FORWARDER_SERVER="host.docker.internal:PORT"
+   ```
+   where PORT is the port displayed when you ran `o2f-server`.
+
+2. Set the BROWSER environment variable to use the browser script:
+   ```bash
+   export BROWSER=o2f-browser
+   ```
+
+### Option 2: Download Manually
+
+Download the latest release from this repo. The release consists of a file named `oauth2-forwarder.zip` which contains two Javascript scripts: `o2f-server.js` and `o2f-client.js` plus a helper `browser.sh` script, all in a directory called `o2f`. These can be placed wherever you want, but these instructions assume they are placed in the home directories of the host and container.
 
 ### On the host
 
@@ -62,9 +92,25 @@ Notes:
 
 Here's a strategy to make this fairly easy to use with a Docker container built with a Dockerfile.
 
+#### Option 1: Using npm (Recommended)
+
+On the host, set a specific port that you will listen on by configuring the env variable `OAUTH2_FORWARDER_PORT`.
+
+Add these lines in the Dockerfile:
+
+```
+RUN npm install -g oauth2-forwarder
+ENV OAUTH2_FORWARDER_SERVER host.docker.internal:[PORT]
+ENV BROWSER o2f-browser
+```
+
+Replace `[PORT]` with the actual port number (or use Docker's `ARG` command).
+
+#### Option 2: Using the zip release
+
 On the host, set a specific port that you will listen on by configuring the env variable `OAUTH2_FORWARDER_PORT`.
 
-Add these lines in the Dockerfile
+Add these lines in the Dockerfile:
 
 ```
 RUN curl -LO https://github.com/sam-mfb/oauth2-forwarder/releases/download/v[VERSION]/oauth2-forwarder.zip

browser-global.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+#
+# Assing this script to the BROWSER env variable via:
+#   export BROWSER=o2f-browser
+#
+# This will ensure requests to open a browser get forwarded
+# through to the proxy
+#
+LOG_FILE="/tmp/oauth2-forwarder.log"
+
+# fork and return 0 as some apps (e.g., az cli) expect a zero return 
+# before they will launch their redirect listener
+o2f-client "$@" >> "$LOG_FILE" 2>&1 &
+
+exit 0

package.json

@@ -3,8 +3,13 @@
   "version": "1.0.0",
   "description": "utilities for forwarding oauth2 interactive flow (e.g. container to host)",
   "main": "dist/index.js",
+  "bin": {
+    "o2f-server": "./dist/o2f-server.js",
+    "o2f-client": "./dist/o2f-client.js",
+    "o2f-browser": "./browser-global.sh"
+  },
   "scripts": {
-    "build": "rimraf ./dist && webpack",
+    "build": "rimraf ./dist && webpack && node prepend-shebang.js",
     "zip-release": "./release.sh",
     "test": "jest --watch",
     "e2e-test": "jest -c ./jest.e2e.config.js",
@@ -14,6 +19,25 @@
   },
   "author": "Sam Davidoff",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sam-mfb/oauth2-forwarder.git"
+  },
+  "files": [
+    "dist",
+    "browser.sh",
+    "browser-global.sh"
+  ],
+  "keywords": [
+    "oauth2",
+    "docker",
+    "container",
+    "authentication",
+    "browser"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "devDependencies": {
     "@eslint/js": "^9.25.1",
     "@types/eslint__js": "^8.42.3",

prepend-shebang.js

@@ -0,0 +1,28 @@
+const fs = require('fs');
+const path = require('path');
+
+const shebang = '#!/usr/bin/env node\n';
+const files = ['o2f-server.js', 'o2f-client.js'];
+const distPath = path.join(__dirname, 'dist');
+
+files.forEach(file => {
+  const filePath = path.join(distPath, file);
+  
+  if (fs.existsSync(filePath)) {
+    // Read the file content
+    const content = fs.readFileSync(filePath, 'utf8');
+    
+    // Check if shebang is already there
+    if (!content.startsWith('#!')) {
+      console.log(`Adding shebang to ${file}`);
+      // Write the file with shebang prepended
+      fs.writeFileSync(filePath, shebang + content);
+      // Make the file executable
+      fs.chmodSync(filePath, '755');
+    } else {
+      console.log(`Shebang already exists in ${file}`);
+    }
+  } else {
+    console.error(`File not found: ${filePath}`);
+  }
+});