oauth-guard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# 🛡️ oauth-guard
+
+[![NPM Version](https://img.shields.io/npm/v/oauth-guard.svg?style=flat-square)](https://www.npmjs.com/package/oauth-guard)
+[![License](https://img.shields.io/npm/l/oauth-guard.svg?style=flat-square)](./LICENSE)
+[![Node Support](https://img.shields.io/node/v/oauth-guard.svg?style=flat-square)](https://nodejs.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/agarwalpranav0711/oauth-guard/pulls)
+
+A zero-config, zero-dependency local proxy server that automatically manages, caches, and refreshes OAuth2 Client Credentials tokens. Built specifically to solve token expiration friction in API testing tools like Postman, Insomnia, and `curl`.
+
+---
+
+## 🛑 The Friction
+
+When testing APIs secured by the OAuth2 **Client Credentials** grant, developers face a persistent workflow interruption. 
+
+According to the OAuth2 specification (RFC 6749, sections 4.2.2 and 4.4.3), auth servers **should not** issue a `refresh_token` for Client Credentials. Because of this, popular desktop API clients (like Postman) cannot automatically refresh tokens when they expire. 
+
+This leaves developers with three painful choices during testing:
+1. Manually trigger token requests and copy-paste new `Authorization` headers every hour.
+2. Write custom pre-request scripts in Postman that execute on *every single request*, slowing down response times and cluttering test collections.
+3. Deal with unexpected `401 Unauthorized` errors mid-flow.
+
+---
+
+## ⚡ What It Is (and What It Isn't)
+
+`oauth-guard` runs a lightweight proxy on your local machine. You direct your API client (Postman, curl, or a local dev frontend) to `http://localhost:8787` instead of the real API base URL. 
+
+The proxy intercepts incoming calls, checks process memory for a valid token, auto-refreshes it proactively if it has expired (or is about to expire), attaches it to the `Authorization` header, and forwards your request to the target API.
+
+* **What it is:** A simple, single-binary-equivalent Node.js developer tool configured with one JSON file. It is optimized for local loopback testing.
+* **What it isn't:** It is **not** an enterprise API gateway, production sidecar, or Kubernetes service mesh component. If you need advanced cluster ingress token-management, mutual TLS (mTLS), or cluster-level caching, check out infrastructure-focused utilities like Go's `observatorium/token-refresher` or Go libraries like `udhos/oauth2`.
+
+---
+
+## 🔄 How It Works
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Client as API Client (Postman / curl)
+    participant Proxy as localhost:8787 (oauth-guard)
+    participant Auth as OAuth Provider (Auth0/Okta)
+    participant API as Target API (e.g. Gateway)
+
+    Client->>Proxy: GET /v1/users
+    alt Token is missing or expires in < 30s
+        Proxy->>Auth: POST /oauth/token (grant_type=client_credentials)
+        Auth-->>Proxy: Return JSON (access_token + expires_in)
+    end
+    Proxy->>API: GET /v1/users (Authorization: Bearer <token>)
+    API-->>Proxy: Return Data (JSON/Binary/Stream)
+    Proxy-->>Client: Pipe back response unchanged (200 OK)
+```
+
+---
+
+## 🛠️ Concurrency Safety (Singleflight Request Coalescing)
+
+If your test suite launches multiple requests in parallel (or you open a dashboard making 10 concurrent API calls) while the cached token is expired or missing, standard proxies trigger 10 simultaneous token requests. This can lead to **rate-limiting blocks** or invalidating previously generated tokens.
+
+`oauth-guard` implements **single-flight request coalescing**. When multiple concurrent requests arrive, only **one** network request is made to the token endpoint. All other concurrent requests wait in a queue and resolve safely once that single request completes.
+
+---
+
+## 🚀 Installation & Usage
+
+### Option 1: Run with `npx` (No Global Installation)
+```bash
+npx oauth-guard start --config config.json
+```
+
+### Option 2: Install Globally
+```bash
+npm install -g oauth-guard
+```
+
+---
+
+## 📂 Configuration Examples
+
+Create a `config.json` file in your workspace (copy from `config.example.json` to start).
+
+### Example 1: Auth0 (Requires `audience` and Form Body Credentials)
+```json
+{
+  "tokenEndpoint": "https://dev-your-tenant.us.auth0.com/oauth/token",
+  "clientId": "your_auth0_client_id",
+  "clientSecret": "your_auth0_client_secret",
+  "credentialStyle": "body",
+  "audience": "https://api.yourdomain.local",
+  "targetApiBaseUrl": "https://api.yourdomain.com",
+  "listenPort": 8787
+}
+```
+
+### Example 2: Okta / Standard OAuth (Basic Auth Credentials + Custom Timeout)
+```json
+{
+  "tokenEndpoint": "https://your-org.okta.com/oauth2/default/v1/token",
+  "clientId": "your_client_id",
+  "clientSecret": "your_client_secret",
+  "credentialStyle": "basic",
+  "targetApiBaseUrl": "https://api.yourdomain.com",
+  "listenPort": 8787,
+  "scope": "read:users write:users",
+  "targetTimeoutMs": 15000
+}
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+| Parameter | Type | Required | Default | Description |
+| :--- | :--- | :---: | :---: | :--- |
+| `tokenEndpoint` | `string` | **Yes** | — | The full URL to request OAuth tokens (e.g., `https://auth.company.com/oauth/token`). |
+| `clientId` | `string` | **Yes** | — | The client ID for application authentication. |
+| `clientSecret` | `string` | **Yes** | — | The client secret for application authentication. |
+| `credentialStyle`| `string` | **Yes** | — | Location of client credentials. Must be `"body"` (sent in POST request body) or `"basic"` (sent in HTTP Basic Auth headers). |
+| `targetApiBaseUrl`| `string` | **Yes** | — | The base target API URL where requests will be forwarded. |
+| `listenPort` | `number` | **Yes** | — | Local port the proxy binds to (e.g., `8787`). Must be an integer between 1 and 65535. |
+| `audience` | `string` | No | `""` | The resource audience identifier (required by Auth0). |
+| `scope` | `string` | No | `""` | Optional space-separated list of scopes to request. |
+| `targetTimeoutMs`| `number` | No | `30000` | Connection timeout in milliseconds for forwarded requests to the target API. |
+
+---
+
+## 💻 CLI Commands
+
+### 1. `oauth-guard start`
+Starts the HTTP proxy server on the configured local port.
+
+* **Command:** `oauth-guard start --config <path>`
+* **Flags:**
+  * `-c, --config <path>`: Path to the JSON configuration file.
+  * `-v, --verbose`: Enables verbose logging. Prints full outbound headers (with **redacted access tokens**), request paths, and response latency.
+
+### 2. `oauth-guard status`
+A one-shot diagnostics tool to verify credentials and connectivity without starting the server.
+
+* **Command:** `oauth-guard status --config <path>`
+* **Output:** Displays endpoint reachability latency, credential authentication status, token lifetime remaining, and a redacted preview of the returned token.
+
+```text
+[oauth-guard] [status] ℹ️ Checking token endpoint: https://dev-tenant.us.auth0.com/oauth/token
+[oauth-guard] 🔄 Fetching new token from https://dev-tenant.us.auth0.com/oauth/token...
+[oauth-guard] ✅ Token acquired, expires in 86400s
+
+[oauth-guard] [status] ✅ Diagnostic Summary:
+  • Token endpoint reachability : REACHABLE (took 452ms)
+  • Authentication status       : SUCCESSFUL
+  • Token lifetime / expiry     : 86400s remaining (23h 59m 59s)
+  • Token confirmation          : eyJhbG*** [redacted]
+```
+
+---
+
+## 🔒 Security Notes
+
+> [!IMPORTANT]
+> Because `oauth-guard` handles active credentials and authentication tokens, please observe the following guidelines:
+>
+> 1. **Local-Only Binding:** The proxy server binds and listens on `localhost` (127.0.0.1) only. Never expose the configured port to public networks or external interfaces.
+> 2. **Git Safety:** Add `config.json` to your local `.gitignore` immediately. Never commit real credentials to source control. Use `config.example.json` to share schemas with team members.
+> 3. **Memory Caching:** Credentials and access tokens are kept purely in-memory. They are never written to disk or serialized to local temporary folders.
+
+---
+
+## ⚠️ Limitations & Scope
+
+* **Single Target API:** Each instance of the proxy is dedicated to one `targetApiBaseUrl`. If you need to test multiple separate target APIs, start multiple proxy instances on separate local ports.
+* **Flow Support:** Supports **Client Credentials** grant type only. Authorization Code, Implicit, and Password grants are out of scope.
+* **No Persistence:** Restarting the proxy clears the cached token, meaning a fresh token will be acquired on the first request after launch.
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/bin/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { program } = require('commander');
+const { loadConfig } = require('../src/configLoader');
+const { startServer } = require('../src/server');
+
+program
+  .name('oauth-guard')
+  .description(
+    'A local HTTP proxy that automatically manages OAuth2 Client Credentials tokens.'
+  )
+  .version('1.0.0');
+
+const { fetchNewToken } = require('../src/tokenManager');
+
+program
+  .command('start')
+  .description('Start the oauth-guard proxy server')
+  .requiredOption(
+    '-c, --config <path>',
+    'Path to the JSON config file'
+  )
+  .option(
+    '-v, --verbose',
+    'Enable verbose logging of outbound requests, headers, and timing'
+  )
+  .action((options) => {
+    try {
+      // --- Load and validate config ---
+      const config = loadConfig(options.config);
+
+      // --- Start the proxy server ---
+      const server = startServer(config, options);
+
+      // --- Graceful shutdown on Ctrl+C ---
+      process.on('SIGINT', () => {
+        console.log('\n[oauth-guard] Shutting down...');
+        server.close(() => {
+          process.exit(0);
+        });
+        // Force exit after 3s if server.close() hangs
+        setTimeout(() => process.exit(0), 3000);
+      });
+
+      // Windows-specific: handle the terminal close signal
+      process.on('SIGTERM', () => {
+        console.log('\n[oauth-guard] Shutting down...');
+        server.close(() => {
+          process.exit(0);
+        });
+        setTimeout(() => process.exit(0), 3000);
+      });
+    } catch (err) {
+      console.error(`\n[oauth-guard] ❌ ${err.message}\n`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('status')
+  .description('Verify config and connection to the token endpoint')
+  .requiredOption(
+    '-c, --config <path>',
+    'Path to the JSON config file'
+  )
+  .action(async (options) => {
+    try {
+      // --- Load and validate config ---
+      const config = loadConfig(options.config);
+
+      console.log(`[oauth-guard] [status] ℹ️ Checking token endpoint: ${config.tokenEndpoint}`);
+
+      // --- Attempt to fetch token ---
+      const startTime = Date.now();
+      const token = await fetchNewToken(config);
+      const duration = Date.now() - startTime;
+
+      console.log('');
+      console.log('[oauth-guard] [status] ✅ Diagnostic Summary:');
+      console.log(`  • Token endpoint reachability : REACHABLE (took ${duration}ms)`);
+      console.log('  • Authentication status       : SUCCESSFUL');
+      
+      const secondsRemaining = Math.max(0, Math.round((token.expiresAt - Date.now()) / 1000));
+      const countdownStr = formatCountdown(token.expiresAt - Date.now());
+      console.log(`  • Token lifetime / expiry     : ${secondsRemaining}s remaining (${countdownStr})`);
+
+      const redacted = token.accessToken.slice(0, 6) + '*** [redacted]';
+      console.log(`  • Token confirmation          : ${redacted}`);
+      console.log('');
+      process.exit(0);
+    } catch (err) {
+      console.error(`\n[oauth-guard] [status] ❌ Diagnostic failed: ${err.message}\n`);
+      process.exit(1);
+    }
+  });
+
+function formatCountdown(ms) {
+  if (ms <= 0) return 'Expired';
+  const seconds = Math.floor((ms / 1000) % 60);
+  const minutes = Math.floor((ms / (1000 * 60)) % 60);
+  const hours = Math.floor((ms / (1000 * 60 * 60)) % 24);
+  const days = Math.floor(ms / (1000 * 60 * 60 * 24));
+
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0 || days > 0) parts.push(`${hours}h`);
+  if (minutes > 0 || hours > 0 || days > 0) parts.push(`${minutes}m`);
+  parts.push(`${seconds}s`);
+  return parts.join(' ');
+}
+
+// Top-level error handling — clean output, no raw stack traces
+try {
+  program.parse(process.argv);
+} catch (err) {
+  console.error(`\n[oauth-guard] ❌ Unexpected error: ${err.message}\n`);
+  process.exit(1);
+}

package/config.example.json

@@ -0,0 +1,10 @@
+{
+  "tokenEndpoint": "https://api.example.com/oauth/token",
+  "clientId": "YOUR_CLIENT_ID",
+  "clientSecret": "YOUR_CLIENT_SECRET",
+  "credentialStyle": "body",
+  "targetApiBaseUrl": "https://api.example.com",
+  "audience": "https://your-api-identifier",
+  "scope": "optional-scope-string",
+  "listenPort": 8787
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "oauth-guard",
+  "version": "1.0.0",
+  "description": "A zero-config local proxy that automatically fetches and refreshes OAuth2 Client Credentials tokens for API testing tools like Postman and curl.",
+  "bin": {
+    "oauth-guard": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js start"
+  },
+  "keywords": [
+    "oauth2",
+    "client-credentials",
+    "proxy",
+    "postman",
+    "api-testing",
+    "token-refresh",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agarwalpranav0711/oauth-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agarwalpranav0711/oauth-guard/issues"
+  },
+  "homepage": "https://github.com/agarwalpranav0711/oauth-guard#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "config.example.json"
+  ]
+}

package/src/configLoader.js

@@ -0,0 +1,150 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Required fields and their expected types for a valid oauth-guard config.
+ */
+const REQUIRED_FIELDS = {
+  tokenEndpoint: 'string',
+  clientId: 'string',
+  clientSecret: 'string',
+  credentialStyle: 'string',
+  targetApiBaseUrl: 'string',
+  listenPort: 'number',
+};
+
+/**
+ * Valid values for the credentialStyle field.
+ */
+const VALID_CREDENTIAL_STYLES = ['body', 'basic'];
+
+/**
+ * Loads and validates a config JSON file.
+ * Returns the parsed config object if valid.
+ * Throws a descriptive Error listing all validation problems if invalid.
+ *
+ * @param {string} configPath - Absolute or relative path to the JSON config file.
+ * @returns {object} The validated config object.
+ */
+function loadConfig(configPath) {
+  const resolvedPath = path.resolve(configPath);
+
+  // --- File existence check ---
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Config file not found: ${resolvedPath}`);
+  }
+
+  // --- JSON parse ---
+  let raw;
+  try {
+    raw = fs.readFileSync(resolvedPath, 'utf-8');
+  } catch (err) {
+    throw new Error(`Could not read config file: ${err.message}`);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Config file is not valid JSON: ${err.message}`);
+  }
+
+  // --- Field validation ---
+  const problems = [];
+
+  for (const [field, expectedType] of Object.entries(REQUIRED_FIELDS)) {
+    if (!(field in config)) {
+      problems.push(`Missing required field: "${field}"`);
+    } else if (typeof config[field] !== expectedType) {
+      problems.push(
+        `Field "${field}" must be a ${expectedType}, got ${typeof config[field]}`
+      );
+    } else if (expectedType === 'string' && config[field].trim() === '') {
+      problems.push(`Field "${field}" must not be empty`);
+    }
+  }
+
+  // credentialStyle enum check (only if present and is a string)
+  if (
+    typeof config.credentialStyle === 'string' &&
+    !VALID_CREDENTIAL_STYLES.includes(config.credentialStyle)
+  ) {
+    problems.push(
+      `Field "credentialStyle" must be one of: ${VALID_CREDENTIAL_STYLES.join(', ')} — got "${config.credentialStyle}"`
+    );
+  }
+
+  // listenPort range check (only if present and is a number)
+  if (typeof config.listenPort === 'number') {
+    if (
+      !Number.isInteger(config.listenPort) ||
+      config.listenPort < 1 ||
+      config.listenPort > 65535
+    ) {
+      problems.push(
+        `Field "listenPort" must be an integer between 1 and 65535, got ${config.listenPort}`
+      );
+    }
+  }
+
+  // URL format validation
+  if (typeof config.tokenEndpoint === 'string' && config.tokenEndpoint.trim() !== '') {
+    try {
+      new URL(config.tokenEndpoint);
+    } catch (err) {
+      problems.push(`Field "tokenEndpoint" is not a well-formed URL: ${err.message}`);
+    }
+  }
+
+  if (typeof config.targetApiBaseUrl === 'string' && config.targetApiBaseUrl.trim() !== '') {
+    try {
+      new URL(config.targetApiBaseUrl);
+    } catch (err) {
+      problems.push(`Field "targetApiBaseUrl" is not a well-formed URL: ${err.message}`);
+    }
+  }
+
+  // targetTimeoutMs is optional; if present must be a positive integer
+  if ('targetTimeoutMs' in config) {
+    if (typeof config.targetTimeoutMs !== 'number') {
+      problems.push(
+        `Field "targetTimeoutMs" must be a number if provided, got ${typeof config.targetTimeoutMs}`
+      );
+    } else if (!Number.isInteger(config.targetTimeoutMs) || config.targetTimeoutMs <= 0) {
+      problems.push(
+        `Field "targetTimeoutMs" must be a positive integer, got ${config.targetTimeoutMs}`
+      );
+    }
+  } else {
+    // Apply default
+    config.targetTimeoutMs = 30000;
+  }
+
+  // scope is optional; if present must be a string (empty strings are silently ignored at request time)
+  if ('scope' in config && config.scope !== '') {
+    if (typeof config.scope !== 'string') {
+      problems.push(
+        `Field "scope" must be a string if provided, got ${typeof config.scope}`
+      );
+    }
+  }
+
+  // audience is optional; if present must be a non-empty string
+  if ('audience' in config && config.audience !== '') {
+    if (typeof config.audience !== 'string') {
+      problems.push(
+        `Field "audience" must be a string if provided, got ${typeof config.audience}`
+      );
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new Error(
+      `Invalid config file (${resolvedPath}):\n  • ${problems.join('\n  • ')}`
+    );
+  }
+
+  return config;
+}
+
+module.exports = { loadConfig };

package/src/server.js

@@ -0,0 +1,174 @@
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+const { getValidToken } = require('./tokenManager');
+
+/**
+ * The currently cached token, held in module scope so it persists across
+ * requests for the lifetime of the proxy process.
+ * @type {{accessToken: string, expiresAt: number} | null}
+ */
+let cachedToken = null;
+
+/**
+ * Creates and starts the oauth-guard proxy server.
+ *
+ * @param {object} config - The validated oauth-guard config object.
+ * @returns {http.Server} The running HTTP server instance.
+ */
+function startServer(config, options = {}) {
+  const { targetApiBaseUrl, listenPort, targetTimeoutMs } = config;
+  const verbose = !!options.verbose;
+
+  // Pre-parse the target base URL once
+  const targetUrl = new URL(targetApiBaseUrl);
+  const isTargetHttps = targetUrl.protocol === 'https:';
+  const transport = isTargetHttps ? https : http;
+  const targetPort = targetUrl.port || (isTargetHttps ? '443' : '80');
+
+  const server = http.createServer(async (incomingReq, incomingRes) => {
+    if (verbose) {
+      console.log(`[oauth-guard] [VERBOSE] Request received: ${incomingReq.method} ${incomingReq.url}`);
+    } else {
+      console.log(`[oauth-guard] Request received: ${incomingReq.method} ${incomingReq.url}`);
+    }
+    // Pause incoming request immediately to avoid losing events/data during the await
+    incomingReq.pause();
+
+    // --- Step 1: Get a valid token ---
+    let token;
+    try {
+      token = await getValidToken(config, cachedToken);
+      cachedToken = token;
+    } catch (err) {
+      console.error(`[oauth-guard] ❌ Token fetch failed: ${err.message}`);
+      incomingRes.writeHead(502, { 'Content-Type': 'application/json' });
+      incomingRes.end(
+        JSON.stringify({
+          error: 'oauth-guard: failed to acquire token',
+          detail: err.message,
+        })
+      );
+      return;
+    }
+
+    // --- Step 2: Build the outbound request ---
+    // Preserve the original path + query string exactly as received
+    const outboundPath =
+      targetUrl.pathname.replace(/\/$/, '') + incomingReq.url;
+
+    // Clone incoming headers, removing/replacing sensitive ones
+    const outboundHeaders = { ...incomingReq.headers };
+
+    // Remove caller's own auth — our managed token replaces it
+    delete outboundHeaders['authorization'];
+
+    // Replace host with the target's host
+    outboundHeaders['host'] = targetUrl.host;
+
+    // Inject the managed Bearer token
+    outboundHeaders['authorization'] = `Bearer ${token.accessToken}`;
+
+    const outboundOptions = {
+      hostname: targetUrl.hostname,
+      port: targetPort,
+      path: outboundPath,
+      method: incomingReq.method,
+      headers: outboundHeaders,
+    };
+
+    if (verbose) {
+      const headersToLog = {};
+      for (const [key, value] of Object.entries(outboundHeaders)) {
+        if (key.toLowerCase() === 'authorization' && typeof value === 'string') {
+          const parts = value.split(' ');
+          if (parts[0] && parts[0].toLowerCase() === 'bearer' && parts[1]) {
+            headersToLog[key] = `Bearer ${parts[1].slice(0, 6)}*** [redacted]`;
+          } else {
+            headersToLog[key] = '[redacted]';
+          }
+        } else {
+          headersToLog[key] = value;
+        }
+      }
+      console.log(`[oauth-guard] [VERBOSE] Sending request to target API:`);
+      console.log(`[oauth-guard] [VERBOSE]   Method: ${incomingReq.method}`);
+      console.log(`[oauth-guard] [VERBOSE]   Path: ${outboundPath}`);
+      console.log(`[oauth-guard] [VERBOSE]   Headers: ${JSON.stringify(headersToLog, null, 2)}`);
+    }
+
+    const startTime = Date.now();
+
+    // --- Step 3: Forward the request (stream the body) ---
+    // NOTE: We pipe the incoming body as a raw stream to the outbound request.
+    // This works for JSON, form data, plain text, and binary payloads.
+    // For v1, streaming responses are also piped back directly.
+    const proxyReq = transport.request(outboundOptions, (proxyRes) => {
+      const duration = Date.now() - startTime;
+      // Calculate time remaining on the token for logging
+      const secondsRemaining = Math.round(
+        (token.expiresAt - Date.now()) / 1000
+      );
+
+      if (verbose) {
+        console.log(
+          `[oauth-guard] [VERBOSE] Received response from target API in ${duration}ms (status: ${proxyRes.statusCode})`
+        );
+      }
+
+      console.log(
+        `[oauth-guard] ${incomingReq.method} ${incomingReq.url} → ${proxyRes.statusCode} (token valid, ${secondsRemaining}s remaining)`
+      );
+
+      // --- Step 4: Pipe the response back unchanged ---
+      incomingRes.writeHead(proxyRes.statusCode, proxyRes.headers);
+      proxyRes.pipe(incomingRes, { end: true });
+    });
+
+    // Set a timeout on the outbound request
+    proxyReq.setTimeout(targetTimeoutMs, () => {
+      proxyReq.destroy(new Error(`outbound request timed out after ${targetTimeoutMs}ms`));
+    });
+
+    proxyReq.on('error', (err) => {
+      const duration = Date.now() - startTime;
+      if (verbose) {
+        console.error(
+          `[oauth-guard] [VERBOSE] Request failed after ${duration}ms: ${err.message}`
+        );
+      }
+      console.error(
+        `[oauth-guard] ❌ Proxy request failed: ${err.message}`
+      );
+      // Only send an error response if headers haven't been sent yet
+      if (!incomingRes.headersSent) {
+        incomingRes.writeHead(502, { 'Content-Type': 'application/json' });
+        incomingRes.end(
+          JSON.stringify({
+            error: 'oauth-guard: target API unreachable',
+            detail: err.message,
+          })
+        );
+      }
+    });
+
+    // Pipe the incoming body to the outbound request (raw stream — no parsing)
+    incomingReq.pipe(proxyReq, { end: true });
+  });
+
+  server.listen(listenPort, () => {
+    console.log('');
+    console.log(
+      `[oauth-guard] Starting proxy on http://localhost:${listenPort}`
+    );
+    console.log(`[oauth-guard] Forwarding to: ${targetApiBaseUrl}`);
+    console.log(
+      `[oauth-guard] Point your API client at http://localhost:${listenPort} instead of the real API.`
+    );
+    console.log('');
+  });
+
+  return server;
+}
+
+module.exports = { startServer };

package/src/tokenManager.js

@@ -0,0 +1,196 @@
+  const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+/**
+ * Seconds before actual expiry at which we consider the token "expired"
+ * and proactively refresh. This prevents edge-case failures where a token
+ * is technically valid when we check but expires before the target API
+ * processes the request.
+ */
+const EXPIRY_BUFFER_SECONDS = 30;
+
+/**
+ * In-flight token fetch promise. When a fetch is in progress, concurrent
+ * callers await this same promise instead of triggering redundant requests.
+ * @type {Promise<{accessToken: string, expiresAt: number}> | null}
+ */
+let inFlightFetch = null;
+
+/**
+ * Sends the Client Credentials token request and returns the parsed token.
+ *
+ * @param {object} config - The validated oauth-guard config object.
+ * @returns {Promise<{accessToken: string, expiresAt: number}>}
+ */
+async function fetchNewToken(config) {
+  const { tokenEndpoint, clientId, clientSecret, credentialStyle, scope, audience } =
+    config;
+
+  console.log(`[oauth-guard] 🔄 Fetching new token from ${tokenEndpoint}...`);
+
+  // Build the form-urlencoded body
+  const bodyParams = new URLSearchParams();
+  bodyParams.append('grant_type', 'client_credentials');
+
+  if (credentialStyle === 'body') {
+    bodyParams.append('client_id', clientId);
+    bodyParams.append('client_secret', clientSecret);
+  }
+
+  if (scope) {
+    bodyParams.append('scope', scope);
+  }
+
+  if (audience) {
+    bodyParams.append('audience', audience);
+  }
+
+  const bodyString = bodyParams.toString();
+
+  // Build request options
+  const parsedUrl = new URL(tokenEndpoint);
+  const isHttps = parsedUrl.protocol === 'https:';
+  const transport = isHttps ? https : http;
+
+  const requestOptions = {
+    hostname: parsedUrl.hostname,
+    port: parsedUrl.port || (isHttps ? 443 : 80),
+    path: parsedUrl.pathname + parsedUrl.search,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      'Content-Length': Buffer.byteLength(bodyString),
+    },
+  };
+
+  // Add Basic Auth header if credentialStyle is "basic"
+  if (credentialStyle === 'basic') {
+    const encoded = Buffer.from(`${clientId}:${clientSecret}`).toString(
+      'base64'
+    );
+    requestOptions.headers['Authorization'] = `Basic ${encoded}`;
+  }
+
+  // Make the request
+  return new Promise((resolve, reject) => {
+    const req = transport.request(requestOptions, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const rawBody = Buffer.concat(chunks).toString('utf-8');
+
+        // Non-2xx check
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          const truncated =
+            rawBody.length > 200 ? rawBody.slice(0, 200) + '…' : rawBody;
+          reject(
+            new Error(
+              `Token endpoint returned ${res.statusCode} ${res.statusMessage || ''} — check clientId/clientSecret. Response: ${truncated}`
+            )
+          );
+          return;
+        }
+
+        // JSON parse
+        let data;
+        try {
+          data = JSON.parse(rawBody);
+        } catch {
+          reject(
+            new Error(
+              `Token endpoint returned non-JSON response (status ${res.statusCode}) — this usually means the tokenEndpoint URL is wrong, or the server returned an HTML error page instead of JSON.`
+            )
+          );
+          return;
+        }
+
+        // Validate required fields in the token response
+        if (!data.access_token) {
+          const truncated =
+            rawBody.length > 200 ? rawBody.slice(0, 200) + '…' : rawBody;
+          reject(
+            new Error(
+              `Token endpoint response missing 'access_token' field — got: ${truncated}`
+            )
+          );
+          return;
+        }
+
+        if (data.expires_in == null || typeof data.expires_in !== 'number') {
+          const truncated =
+            rawBody.length > 200 ? rawBody.slice(0, 200) + '…' : rawBody;
+          reject(
+            new Error(
+              `Token endpoint response missing or invalid 'expires_in' field — got: ${truncated}`
+            )
+          );
+          return;
+        }
+
+        const expiresAt = Date.now() + data.expires_in * 1000;
+
+        console.log(
+          `[oauth-guard] ✅ Token acquired, expires in ${data.expires_in}s`
+        );
+
+        resolve({
+          accessToken: data.access_token,
+          expiresAt,
+        });
+      });
+    });
+
+    req.on('error', (err) => {
+      reject(
+        new Error(`Token fetch network error: ${err.message}`)
+      );
+    });
+
+    req.write(bodyString);
+    req.end();
+  });
+}
+
+/**
+ * Returns a valid (non-expired) token, re-fetching if necessary.
+ *
+ * Concurrency-safe: if multiple callers invoke this while a fetch is already
+ * in-flight, they all await the SAME promise — only one network call happens.
+ *
+ * @param {object} config - The validated oauth-guard config object.
+ * @param {{accessToken: string, expiresAt: number} | null} currentCachedToken
+ * @returns {Promise<{accessToken: string, expiresAt: number}>}
+ */
+async function getValidToken(config, currentCachedToken) {
+  const now = Date.now();
+  const bufferMs = EXPIRY_BUFFER_SECONDS * 1000;
+
+  // If we have a cached token that's still valid (with buffer), return it
+  if (
+    currentCachedToken &&
+    currentCachedToken.expiresAt - now > bufferMs
+  ) {
+    return currentCachedToken;
+  }
+
+  // A fetch is needed. If one is already in-flight, piggyback on it.
+  if (inFlightFetch) {
+    return inFlightFetch;
+  }
+
+  // No in-flight fetch — start one and store the promise
+  inFlightFetch = fetchNewToken(config)
+    .then((token) => {
+      inFlightFetch = null;
+      return token;
+    })
+    .catch((err) => {
+      inFlightFetch = null;
+      throw err;
+    });
+
+  return inFlightFetch;
+}
+
+module.exports = { fetchNewToken, getValidToken };