newman-oauth-refresh 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Shivam Mahajan
+
+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 OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,242 @@
-# Temporary Holding Version
+# newman-oauth-refresh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![ci](https://github.com/gl1tchdust/newman-oauth-refresh/actions/workflows/ci.yml/badge.svg)](https://github.com/gl1tchdust/newman-oauth-refresh/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/newman-oauth-refresh)](https://www.npmjs.com/package/newman-oauth-refresh)
+
+OAuth2 token refresh for [Newman](https://github.com/postmanlabs/newman) collection
+runs. Proactive for JWTs, reactive on 401 for opaque tokens, and never writes a
+token to disk.
+
+## The problem
+
+Postman's app refreshes OAuth2 tokens for you. Newman does not, so a collection
+longer than the token's lifetime starts returning 401s partway through and
+every request after that fails.
+
+Two issues, and their states matter:
+
+- [postmanlabs/postman-app-support#10112](https://github.com/postmanlabs/postman-app-support/issues/10112)
+  "Auto update/refresh of OAuth2 access tokens" — **closed as completed**,
+  March 2025. The app got it.
+- [postmanlabs/newman#3219](https://github.com/postmanlabs/newman/issues/3219)
+  "Automatic Token Refresh Not Working in Newman CLI When OAuth 2.0 Access
+  Token Expires" — **still open.** The CLI did not.
+
+So this is not a feature nobody got round to. It shipped in one product and
+not the other, and Postman's documentation says so plainly: scheduled runs,
+monitors, "the Postman CLI, and Newman don't support automatic token refresh"
+([Postman docs, OAuth 2.0](https://learning.postman.com/docs/sending-requests/authorization/oauth-20/)).
+
+That claim is checked, not quoted on trust. `scripts/premise.mjs` runs a
+collection with Postman's own OAuth 2.0 auth block fully configured, refresh
+token included, and expires the access token after the first request:
+
+```
+newman, unassisted: req/first:200  req/second:401  req/third:401
+token endpoint calls: 0
+```
+
+Zero. Newman never attempted a refresh. CI runs that check on every push, and
+**fails if Newman ever starts refreshing on its own** — at which point this
+package should be retired rather than maintained.
+
+## Three failure modes in the existing workarounds
+
+Most published workarounds are a pre-request snippet that fetches a token
+before every request. They mostly work, and they fail in three specific ways.
+
+**1. The refresh call drops your custom headers.** Snippets build their token
+request from scratch and send nothing but `Content-Type`. If your token
+endpoint sits behind a gateway that requires a `User-Agent`, or your provider
+wants an `X-Client-ID`, the refresh is rejected and the error you see is a
+confusing 400 from an endpoint that worked yesterday. Headers you configure
+here are passed through to the token call, and there is a test asserting they
+arrive.
+
+**2. They force HTTP Basic for client credentials.** RFC 6749 §2.3.1 permits
+credentials in the request body, and a number of providers accept only that
+form. A snippet hardcoded to `Authorization: Basic` cannot talk to them at all.
+Body is the default here; Basic is one variable away.
+
+**3. They cache the token to disk.** Usually by writing it into an environment
+file so the next run can reuse it. That leaves a live bearer token on every CI
+runner, in every container layer, and in anything that archives the workspace.
+Nothing in this package reads or writes a token file, and a test monkeypatches
+every `fs` write API to prove a full refresh cycle touches none of them.
+
+A fourth, less often noticed: providers that **rotate** refresh tokens
+invalidate the old one on use. Keeping the original breaks the *second*
+refresh, an hour into a long run, which is a miserable thing to debug. Rotated
+tokens are adopted automatically.
+
+## 60-second quickstart
+
+```bash
+npm install newman-oauth-refresh
+```
+
+Running Newman as a library:
+
+```js
+import newman from 'newman'
+import { withOAuthRefresh } from 'newman-oauth-refresh'
+
+newman.run({
+  collection: withOAuthRefresh(require('./collection.json')),
+  envVar: [
+    { key: 'oauthTokenUrl',     value: 'https://id.example.com/oauth2/token' },
+    { key: 'oauthClientId',     value: process.env.CLIENT_ID },
+    { key: 'oauthClientSecret', value: process.env.CLIENT_SECRET },
+    { key: 'oauthRefreshToken', value: process.env.REFRESH_TOKEN }
+  ]
+}, (err, summary) => { /* ... */ })
+```
+
+Point your requests at `Bearer {{oauthAccessToken}}` and that is the whole
+integration.
+
+Prefer the CLI? Paste the module into your collection's **Pre-request Script**
+tab once:
+
+```bash
+node -e "console.log(require('newman-oauth-refresh').preRequestScript())" > prerequest.js
+```
+
+then run `newman run collection.json` as usual.
+
+## How it refreshes
+
+Two paths, because tokens come in two shapes and neither path covers both.
+
+**Proactive**, for JWTs. The token says when it expires, so decode `exp` and
+refresh a fixed margin before. No request ever goes out carrying a token that
+dies in flight, which is the thing that makes expiry bugs intermittent.
+Signature verification is deliberately absent: we are the client that was
+handed this token, not the resource server that has to trust it.
+
+**Reactive**, for opaque tokens. Nothing in the token says anything, so the
+401 is the only available signal. Take it, refresh, replay the request once,
+carry on.
+
+Reactive alone is not enough: it turns every expiry into a visible failed
+request, and some gateways alert on 401 rates. Proactive alone is not enough
+either: it cannot work for opaque tokens, and clock skew between you and the
+issuer will eventually beat any margin you pick. Both, or there is a gap.
+
+Exactly one retry, never a loop. A second 401 means the credential is wrong,
+the scope is missing, or the resource genuinely is not yours, and retrying past
+that turns an authorization bug into a flood against your token endpoint.
+
+## What Newman actually allows
+
+Four behaviours, each established by running real Newman rather than reading
+about it. They shaped the design, and they are the reason this is a
+pre-request module rather than an event hook.
+
+| Behaviour | Result |
+|---|---|
+| Mutating headers in a `beforeRequest` listener | **works** |
+| Newman awaiting an `async` event handler | **no** — the request goes out first |
+| `pm.sendRequest` in a pre-request script being awaited | **yes** |
+| `postman.setNextRequest` replaying the current request | **yes** |
+
+The second row is the constraint everything else follows from. A
+`beforeRequest` listener can stamp a header, but it cannot *wait* for a token,
+so a Newman event hook can never refresh one. `pm.sendRequest` inside a
+pre-request script is awaited, which makes the sandbox the only place a
+blocking refresh can happen during a run. Hence a pre-request module.
+
+The retry is the same story. Newman has no retry hook, so replaying a failed
+request has to happen inside the sandbox, via `postman.setNextRequest`. The
+generated snippet carries a guard variable: without one, a permanently
+rejected token retries forever.
+
+### A reporting quirk worth knowing
+
+When a pre-request script issues its own `pm.sendRequest`, Newman reports the
+item's execution **twice** in `summary.run.executions`. Both entries carry the
+same `cursor.httpRequestId`, and the target server receives the request once.
+
+Verified directly: a one-item collection produces two identical execution
+entries while the mock API records a single request. If you assert on
+execution counts in your own pipeline, deduplicate by `cursor.httpRequestId`
+or you will chase a duplicate that was never sent. The tests here assert on
+what the mock servers received instead.
+
+## API
+
+```js
+import {
+  TokenManager,          // the refresh logic, no Newman dependency
+  createAuthorizedFetch, // fetch wrapper: proactive + reactive + one retry
+  withOAuthRefresh,      // inject both scripts into a collection in memory
+  preRequestScript,      // the module, as text
+  retryOn401Script       // the retry snippet, as text
+} from 'newman-oauth-refresh'
+```
+
+`TokenManager` and `createAuthorizedFetch` have no Newman dependency, so they
+work in any Node code that needs a token kept fresh:
+
+```js
+const tokens = new TokenManager({
+  tokenUrl: 'https://id.example.com/oauth2/token',
+  clientId, clientSecret, refreshToken,
+  credentials: 'body',                               // or 'basic'
+  headers: { 'User-Agent': 'acme-ci/2.1' },          // sent on the refresh call
+  marginMs: 60_000
+})
+
+const fetch = createAuthorizedFetch(tokens)
+const res = await fetch('https://api.example.com/orders')
+```
+
+### Collection variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `oauthTokenUrl` | required | token endpoint |
+| `oauthClientId` | | client id |
+| `oauthClientSecret` | | client secret |
+| `oauthRefreshToken` | | enables `grant_type=refresh_token` |
+| `oauthScope` | | scope string |
+| `oauthCredentials` | `body` | `body` or `basic` |
+| `oauthMarginSec` | `60` | refresh this long before `exp` |
+| `oauthExtraHeaders` | | JSON object of headers for the refresh call |
+
+Set `oauthAccessToken` in your requests as `Bearer {{oauthAccessToken}}`.
+
+## Limitations
+
+- **A request body that is a stream cannot be retried.** The retry re-sends the
+  body, and a stream is single use, so the replay would go out empty. Buffer
+  first; `isReplayable(body)` tells you which case you are in.
+- **No `authorization_code` flow.** This refreshes tokens, it does not perform
+  an interactive grant. Obtain the first refresh token out of band.
+- **Secrets come from you.** Pass them as environment variables. The package
+  never persists one, but it cannot stop your CI logs from printing what you
+  hand it.
+- **The sandbox module is ES5.** Postman's sandbox is not Node, so the
+  pre-request module avoids `Buffer`, imports and modern syntax deliberately.
+
+## Tests
+
+```bash
+npm test          # 40 tests
+npm run premise   # is the problem still real?
+```
+
+Every test runs against a real OAuth2 token endpoint and a real protected API
+on real sockets, not a stubbed `fetch`. The three failure modes above are all
+claims about what goes *on the wire* — which headers survive, where the
+credentials are placed, whether an expired token is noticed — and a stub would
+agree with any implementation, including a broken one.
+
+The Newman tests drive actual Newman, for the same reason: this package's whole
+premise is a claim about Newman's behaviour.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Shivam Mahajan, https://linkedin.com/in/shivam-mahajan-a8005a205

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "newman-oauth-refresh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "OAuth2 token refresh for Newman collection runs: proactive for JWTs, reactive on 401 for opaque tokens, memory only",
+  "license": "MIT",
+  "author": "Shivam Mahajan (https://linkedin.com/in/shivam-mahajan-a8005a205)",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "premise": "node scripts/premise.mjs",
+    "prepublishOnly": "npm test && npm run premise"
+  },
+  "keywords": [
+    "newman",
+    "postman",
+    "oauth2",
+    "token-refresh",
+    "jwt",
+    "api-testing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gl1tchdust/newman-oauth-refresh.git"
+  },
+  "devDependencies": {
+    "newman": "^6.2.1"
+  },
+  "homepage": "https://github.com/gl1tchdust/newman-oauth-refresh#readme",
+  "bugs": {
+    "url": "https://github.com/gl1tchdust/newman-oauth-refresh/issues"
+  }
+}

package/src/authorized-fetch.js

@@ -0,0 +1,97 @@
+/**
+ * A fetch wrapper that attaches a bearer token and recovers from a 401 once.
+ *
+ * Two paths, because tokens come in two shapes:
+ *
+ *   Proactive  A JWT says when it expires, so refresh just before. The
+ *              request never goes out with a token that dies in flight.
+ *
+ *   Reactive   An opaque token says nothing. The only way to learn it has
+ *              expired is to be told, so take the 401, refresh, send the
+ *              same request again, and carry on.
+ *
+ * Reactive alone is not enough: it turns every expiry into a visible failed
+ * request, and some APIs rate-limit or alert on 401s. Proactive alone is not
+ * enough either: it cannot work for opaque tokens, and clock skew between you
+ * and the issuer will eventually beat any margin you pick. Both, or you have
+ * a gap.
+ */
+
+/**
+ * Exactly one retry. Not a loop.
+ *
+ * If the second 401 arrives, the token is not the problem: the credential is
+ * wrong, the scope is missing, or the resource genuinely is not yours. Retrying
+ * past that point turns an authorization bug into a self-inflicted flood
+ * against the token endpoint, and hides the real error behind a timeout.
+ */
+const MAX_RETRIES = 1
+
+/**
+ * @param {import('./token-manager.js').TokenManager} tokenManager
+ * @param {object} [options]
+ * @param {Function} [options.fetchImpl]
+ * @param {string}   [options.headerName]  default Authorization
+ * @param {string}   [options.scheme]      default Bearer
+ * @param {Function} [options.onRetry]     observability hook
+ * @returns {(url: string, init?: object) => Promise<Response>}
+ */
+export function createAuthorizedFetch (tokenManager, options = {}) {
+  const {
+    fetchImpl = globalThis.fetch,
+    headerName = 'Authorization',
+    scheme = 'Bearer',
+    onRetry = null
+  } = options
+
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError('no fetch available; pass fetchImpl (Node 18+ has global fetch)')
+  }
+
+  return async function authorizedFetch (url, init = {}) {
+    // Proactive. Refreshes only when the token is near expiry.
+    let token = await tokenManager.getAccessToken()
+
+    const send = (bearer) => fetchImpl(url, {
+      ...init,
+      headers: {
+        // Caller headers first: a per-request header must not be lost just
+        // because this wrapper has opinions about Authorization.
+        ...(init.headers || {}),
+        [headerName]: `${scheme} ${bearer}`
+      }
+    })
+
+    let response = await send(token)
+
+    for (let attempt = 0; attempt < MAX_RETRIES && response.status === 401; attempt++) {
+      // Reactive. The server has told us the token is no good; believe it
+      // rather than trusting our own expiry arithmetic.
+      token = await tokenManager.refresh('reactive-401')
+      if (onRetry) { onRetry({ url, attempt: attempt + 1 }) }
+      response = await send(token)
+    }
+
+    return response
+  }
+}
+
+/**
+ * Is this request body safe to send a second time?
+ *
+ * A retry re-sends the body. Strings, buffers and URLSearchParams can be read
+ * twice; a stream cannot, and the retry would go out with an empty body and
+ * fail in a way that looks like a server bug. Callers sending streams should
+ * buffer first, and this is here so they can check rather than find out.
+ *
+ * @param {*} body
+ * @returns {boolean}
+ */
+export function isReplayable (body) {
+  if (body === undefined || body === null) { return true }
+  if (typeof body === 'string') { return true }
+  if (body instanceof URLSearchParams) { return true }
+  if (ArrayBuffer.isView(body) || body instanceof ArrayBuffer) { return true }
+  // ReadableStream, Readable, FormData with a stream part: single use.
+  return false
+}

package/src/index.js

@@ -0,0 +1,102 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export { TokenManager, RefreshError } from './token-manager.js'
+export { createAuthorizedFetch, isReplayable } from './authorized-fetch.js'
+export { decodePayload, expiryMs, isExpiring } from './jwt.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * The pre-request module, as text, ready to paste into a collection's
+ * Pre-request Script tab or to inject programmatically.
+ *
+ * This is the only `readFileSync` in the package, and it reads this package's
+ * own source. No token ever touches the filesystem; see the test that asserts
+ * it.
+ *
+ * @returns {string}
+ */
+export function preRequestScript () {
+  return readFileSync(join(here, 'postman', 'prerequest.js'), 'utf8')
+}
+
+/**
+ * The test-script snippet that retries a request once after a 401.
+ *
+ * Newman has no retry hook, and it does not await async event handlers, so
+ * neither a wrapper nor a `beforeRequest` listener can replay a failed
+ * request. `postman.setNextRequest` can, because it runs inside the sandbox
+ * where the collection's own control flow lives.
+ *
+ * The guard variable matters. Without it a permanently rejected token
+ * retries forever, turning an authorization bug into an infinite loop
+ * against the token endpoint.
+ *
+ * @param {object} [options]
+ * @param {string} [options.itemName] the request's own name; defaults to the
+ *   runtime value, which is correct unless the request is renamed mid-run
+ * @returns {string}
+ */
+export function retryOn401Script (options = {}) {
+  const target = options.itemName
+    ? JSON.stringify(options.itemName)
+    : 'pm.info.requestName'
+
+  return [
+    '// newman-oauth-refresh: retry once after a 401.',
+    '// Pair with the pre-request module, which does the refreshing.',
+    'if (pm.response.code === 401) {',
+    "  var key = 'oauthRetried:' + pm.info.requestName;",
+    '  if (!pm.variables.get(key)) {',
+    "    pm.variables.set(key, '1');",
+    "    pm.variables.set('oauthAccessToken', '');        // force a refresh",
+    "    pm.variables.set('oauthAccessTokenExpiresAt', '');",
+    `    postman.setNextRequest(${target});`,
+    '  }',
+    '} else {',
+    "  pm.variables.unset('oauthRetried:' + pm.info.requestName);",
+    '}'
+  ].join('\n')
+}
+
+/**
+ * Inject both scripts into a collection object in memory.
+ *
+ * Returns a new collection; the input is not modified. Useful when you run
+ * Newman as a library and would rather not hand-edit the collection file,
+ * which also keeps the scripts out of version control alongside your tests.
+ *
+ * @param {object} collection a Postman v2.1 collection
+ * @param {object} [options]
+ * @param {boolean} [options.retryOn401] also add the retry snippet to each item
+ * @returns {object}
+ */
+export function withOAuthRefresh (collection, options = {}) {
+  const { retryOn401 = true } = options
+  const next = structuredClone(collection)
+
+  next.event = (next.event || []).filter((e) => e.listen !== 'prerequest')
+  next.event.push({
+    listen: 'prerequest',
+    script: { type: 'text/javascript', exec: preRequestScript().split('\n') }
+  })
+
+  if (retryOn401) {
+    const snippet = retryOn401Script().split('\n')
+    const addTo = (items) => {
+      for (const item of items || []) {
+        if (item.item) { addTo(item.item); continue }   // folder
+        item.event = (item.event || []).filter((e) => e.listen !== 'test')
+        item.event.push({
+          listen: 'test',
+          script: { type: 'text/javascript', exec: snippet }
+        })
+      }
+    }
+    addTo(next.item)
+  }
+
+  return next
+}

package/src/jwt.js

@@ -0,0 +1,83 @@
+/**
+ * Read the expiry out of a JWT, without verifying it.
+ *
+ * Verification is deliberately absent. We are the client that was handed this
+ * token, not the resource server that has to trust it. We do not have the
+ * signing key and could not check it if we wanted to. The only question here
+ * is "roughly when does the issuer say this stops working", so the right
+ * amount of cryptography is none.
+ *
+ * Treating `exp` as advisory is also why a bad signature is not an error
+ * worth throwing on: if the token is junk, the API will say so, and the
+ * reactive 401 path handles it.
+ */
+
+/**
+ * Decode a JWT payload. Returns null for anything that is not a JWT, which
+ * includes every opaque token, and that is the normal case rather than an
+ * error. Opaque tokens are handled reactively instead.
+ *
+ * @param {string} token
+ * @returns {object|null}
+ */
+export function decodePayload (token) {
+  if (typeof token !== 'string') { return null }
+
+  const parts = token.split('.')
+  if (parts.length !== 3) { return null }
+
+  try {
+    // base64url, and Buffer tolerates the missing padding.
+    const json = Buffer.from(parts[1], 'base64url').toString('utf8')
+    const payload = JSON.parse(json)
+    // A JWT payload is a JSON object. An array or a bare number is not one,
+    // and would make `payload.exp` silently undefined further down.
+    return (payload && typeof payload === 'object' && !Array.isArray(payload))
+      ? payload
+      : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Expiry as epoch milliseconds, or null when the token does not carry one.
+ *
+ * Null means "no opinion", not "expired". An opaque token has no expiry we
+ * can read, and treating that as expired would refresh before every single
+ * request.
+ *
+ * @param {string} token
+ * @returns {number|null}
+ */
+export function expiryMs (token) {
+  const payload = decodePayload(token)
+  if (!payload) { return null }
+
+  const { exp } = payload
+  // RFC 7519 says exp is NumericDate, seconds since epoch. Some issuers send
+  // it as a string. Accept both; reject anything else rather than producing
+  // NaN, which compares false against everything and would disable refresh
+  // without any visible failure.
+  const seconds = typeof exp === 'string' ? Number(exp) : exp
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds)) { return null }
+
+  return seconds * 1000
+}
+
+/**
+ * Is this token within `marginMs` of expiring?
+ *
+ * False for tokens with no readable expiry. The caller decides what to do
+ * with those; this function will not guess.
+ *
+ * @param {string} token
+ * @param {number} marginMs how long before expiry to start saying yes
+ * @param {number} [now] epoch ms, injectable so tests do not sleep
+ * @returns {boolean}
+ */
+export function isExpiring (token, marginMs, now = Date.now()) {
+  const expires = expiryMs(token)
+  if (expires === null) { return false }
+  return expires - now <= marginMs
+}

package/src/postman/prerequest.js

@@ -0,0 +1,177 @@
+/* eslint-disable */
+/**
+ * newman-oauth-refresh: collection pre-request module.
+ *
+ * Paste this into your collection's Pre-request Script tab, set the variables
+ * listed below, and set each request's Authorization header to
+ * `Bearer {{oauthAccessToken}}`.
+ *
+ * Why a pre-request script rather than a Newman event hook: Newman does not
+ * await async event handlers, so a `beforeRequest` listener cannot refresh a
+ * token before the request goes out. `pm.sendRequest` inside a pre-request
+ * script *is* awaited, which makes this the only place a blocking refresh can
+ * happen inside a Newman run.
+ *
+ * Required variables:
+ *   oauthTokenUrl         token endpoint
+ *
+ * Optional variables:
+ *   oauthClientId         client id
+ *   oauthClientSecret     client secret
+ *   oauthRefreshToken     enables grant_type=refresh_token
+ *   oauthScope            scope string
+ *   oauthCredentials      'body' (default) or 'basic'
+ *   oauthMarginSec        refresh this many seconds before exp (default 60)
+ *   oauthExtraHeaders     JSON object of headers to send on the refresh call
+ *
+ * Written for the Postman sandbox: ES5, no imports, no Buffer, no fs.
+ */
+(function () {
+  var TOKEN_VAR = 'oauthAccessToken'
+  var EXPIRY_VAR = 'oauthAccessTokenExpiresAt'
+
+  function v (name, fallback) {
+    var value = pm.variables.get(name)
+    return (value === undefined || value === null || value === '') ? fallback : value
+  }
+
+  var tokenUrl = v('oauthTokenUrl', null)
+  if (!tokenUrl) {
+    throw new Error('newman-oauth-refresh: set the oauthTokenUrl variable')
+  }
+
+  var clientId = v('oauthClientId', null)
+  var clientSecret = v('oauthClientSecret', null)
+  var refreshToken = v('oauthRefreshToken', null)
+  var scope = v('oauthScope', null)
+  var credentials = v('oauthCredentials', 'body')
+  var marginSec = Number(v('oauthMarginSec', 60))
+
+  var extraHeaders = {}
+  try {
+    var rawHeaders = v('oauthExtraHeaders', null)
+    if (rawHeaders) {
+      extraHeaders = typeof rawHeaders === 'string' ? JSON.parse(rawHeaders) : rawHeaders
+    }
+  } catch (e) {
+    throw new Error('newman-oauth-refresh: oauthExtraHeaders is not valid JSON')
+  }
+
+  // --- expiry ---------------------------------------------------------------
+  //
+  // Decoded, never verified. We are the client that was handed this token, not
+  // the resource server that has to trust it.
+
+  function b64urlDecode (input) {
+    var s = String(input).replace(/-/g, '+').replace(/_/g, '/')
+    while (s.length % 4 !== 0) { s += '=' }
+    return atob(s)
+  }
+
+  function jwtExpiryMs (token) {
+    if (typeof token !== 'string') { return null }
+    var parts = token.split('.')
+    if (parts.length !== 3) { return null }   // opaque token: no opinion
+    try {
+      var payload = JSON.parse(b64urlDecode(parts[1]))
+      var exp = typeof payload.exp === 'string' ? Number(payload.exp) : payload.exp
+      if (typeof exp !== 'number' || !isFinite(exp)) { return null }
+      return exp * 1000
+    } catch (e) {
+      return null
+    }
+  }
+
+  function needsRefresh () {
+    var token = pm.variables.get(TOKEN_VAR)
+    if (!token) { return true }
+
+    var now = Date.now()
+    var marginMs = marginSec * 1000
+
+    // A JWT carries its own expiry.
+    var exp = jwtExpiryMs(token)
+    if (exp !== null) { return (exp - now) <= marginMs }
+
+    // An opaque token does not, so fall back to what the token endpoint said
+    // when it issued this one. Without either signal, do not refresh: the
+    // 401 retry snippet in the README covers that case, and refreshing before
+    // every request would defeat the point.
+    var storedExpiry = Number(pm.variables.get(EXPIRY_VAR))
+    if (storedExpiry) { return (storedExpiry - now) <= marginMs }
+
+    return false
+  }
+
+  // --- refresh --------------------------------------------------------------
+
+  function buildRequest () {
+    var form = []
+    var grantType = refreshToken ? 'refresh_token' : 'client_credentials'
+    form.push('grant_type=' + encodeURIComponent(grantType))
+    if (refreshToken) { form.push('refresh_token=' + encodeURIComponent(refreshToken)) }
+    if (scope) { form.push('scope=' + encodeURIComponent(scope)) }
+
+    // Caller headers first; the protocol bits below have to win. Everything
+    // else the caller set is passed through, which is the point: dropping
+    // User-Agent or a required X-Client-ID is how these refresh calls get
+    // rejected by API gateways.
+    var header = {}
+    for (var k in extraHeaders) {
+      if (Object.prototype.hasOwnProperty.call(extraHeaders, k)) {
+        header[k] = extraHeaders[k]
+      }
+    }
+    header['Content-Type'] = 'application/x-www-form-urlencoded'
+
+    if (credentials === 'basic') {
+      header.Authorization = 'Basic ' + btoa((clientId || '') + ':' + (clientSecret || ''))
+    } else {
+      // RFC 6749 2.3.1 allows credentials in the body, and some providers
+      // accept nothing else. Forcing Basic breaks those outright.
+      if (clientId) { form.push('client_id=' + encodeURIComponent(clientId)) }
+      if (clientSecret) { form.push('client_secret=' + encodeURIComponent(clientSecret)) }
+    }
+
+    return {
+      url: tokenUrl,
+      method: 'POST',
+      header: header,
+      body: { mode: 'raw', raw: form.join('&') }
+    }
+  }
+
+  if (!needsRefresh()) { return }
+
+  pm.sendRequest(buildRequest(), function (err, res) {
+    if (err) {
+      throw new Error('newman-oauth-refresh: token request failed: ' + err)
+    }
+    if (res.code < 200 || res.code >= 300) {
+      throw new Error('newman-oauth-refresh: token endpoint returned ' + res.code +
+                      ': ' + String(res.text()).slice(0, 200))
+    }
+
+    var body = res.json()
+    if (!body.access_token) {
+      throw new Error('newman-oauth-refresh: token response has no access_token')
+    }
+
+    // pm.variables is run-scoped and in memory. Deliberately NOT
+    // pm.environment.set with a persisted environment file: a token written
+    // to disk outlives the run that needed it, on every CI runner it touches.
+    pm.variables.set(TOKEN_VAR, body.access_token)
+
+    if (typeof body.expires_in === 'number') {
+      pm.variables.set(EXPIRY_VAR, String(Date.now() + body.expires_in * 1000))
+    } else {
+      pm.variables.set(EXPIRY_VAR, '')
+    }
+
+    // Rotation: a provider that issues a new refresh token invalidates the
+    // old one, so keeping the original breaks the *second* refresh.
+    if (body.refresh_token) {
+      pm.variables.set('oauthRefreshToken', body.refresh_token)
+    }
+  })
+})()

package/src/token-manager.js

@@ -0,0 +1,231 @@
+import { isExpiring } from './jwt.js'
+
+/**
+ * Thrown when the token endpoint refuses to issue a token.
+ *
+ * Separate from a failure of the request you were actually trying to make,
+ * because the two need different responses: a 401 from your API means refresh
+ * and retry, a 401 from the token endpoint means your client credentials are
+ * wrong and retrying will never help.
+ */
+export class RefreshError extends Error {
+  constructor (message, { status, body } = {}) {
+    super(message)
+    this.name = 'RefreshError'
+    this.status = status
+    this.body = body
+  }
+}
+
+const DEFAULT_MARGIN_MS = 60_000
+
+/**
+ * Holds an OAuth2 access token and refreshes it.
+ *
+ * Memory only. Nothing here reads or writes a file, and there is a test that
+ * fails if that changes. A CLI that caches tokens on disk turns every CI
+ * runner, every laptop, and every container layer into a place a bearer token
+ * can be found later. The run is short; keeping the token in the process that
+ * needs it costs nothing.
+ */
+export class TokenManager {
+  /**
+   * @param {object} options
+   * @param {string} options.tokenUrl                 token endpoint
+   * @param {string} [options.clientId]
+   * @param {string} [options.clientSecret]
+   * @param {string} [options.refreshToken]           for grant_type=refresh_token
+   * @param {string} [options.accessToken]            a token you already hold
+   * @param {string} [options.scope]
+   * @param {'body'|'basic'} [options.credentials]    where client creds go
+   * @param {object} [options.headers]                extra headers for the refresh call
+   * @param {number} [options.marginMs]               refresh this long before exp
+   * @param {'refresh_token'|'client_credentials'} [options.grantType]
+   * @param {Function} [options.fetchImpl]            injectable for tests
+   * @param {Function} [options.now]                  injectable clock
+   * @param {Function} [options.onRefresh]            observability hook
+   */
+  constructor (options = {}) {
+    const {
+      tokenUrl,
+      clientId,
+      clientSecret,
+      refreshToken,
+      accessToken = null,
+      scope,
+      credentials = 'body',
+      headers = {},
+      marginMs = DEFAULT_MARGIN_MS,
+      grantType = refreshToken ? 'refresh_token' : 'client_credentials',
+      fetchImpl = globalThis.fetch,
+      now = () => Date.now(),
+      onRefresh = null
+    } = options
+
+    if (!tokenUrl) { throw new TypeError('tokenUrl is required') }
+    if (credentials !== 'body' && credentials !== 'basic') {
+      throw new TypeError(`credentials must be 'body' or 'basic', got ${credentials}`)
+    }
+    if (typeof fetchImpl !== 'function') {
+      throw new TypeError('no fetch available; pass fetchImpl (Node 18+ has global fetch)')
+    }
+
+    this.tokenUrl = tokenUrl
+    this.clientId = clientId
+    this.clientSecret = clientSecret
+    this.scope = scope
+    this.credentials = credentials
+    this.headers = headers
+    this.marginMs = marginMs
+    this.grantType = grantType
+    this.onRefresh = onRefresh
+
+    this._fetch = fetchImpl
+    this._now = now
+
+    // The only places a token lives. No disk, no module-level cache that
+    // outlives the instance.
+    this._accessToken = accessToken
+    this._refreshToken = refreshToken
+    // Set when the endpoint tells us expires_in but the token is opaque, so
+    // even opaque tokens get proactive refresh when the server is helpful.
+    this._expiresAtMs = null
+    // Single-flight guard. A collection run fires requests back to back; if
+    // three of them notice an expiring token at once, one refresh should go
+    // out, not three. Concurrent refreshes also race to store the rotated
+    // refresh token, and the loser's copy is already invalid.
+    this._inFlight = null
+  }
+
+  /** The token currently held, without triggering a refresh. */
+  get accessToken () { return this._accessToken }
+
+  /** The refresh token currently held. Rotated values are kept up to date. */
+  get refreshToken () { return this._refreshToken }
+
+  /**
+   * Should we refresh before using this token?
+   *
+   * Two independent signals, because tokens come in two shapes. A JWT carries
+   * its own `exp` and we read it. An opaque token carries nothing, but the
+   * token endpoint usually returned `expires_in`, so we remember that.
+   * Neither available means no opinion, and the reactive 401 path covers it.
+   */
+  needsRefresh () {
+    if (!this._accessToken) { return true }
+
+    const now = this._now()
+    if (isExpiring(this._accessToken, this.marginMs, now)) { return true }
+    if (this._expiresAtMs !== null && this._expiresAtMs - now <= this.marginMs) {
+      return true
+    }
+    return false
+  }
+
+  /**
+   * A usable access token, refreshing first if it is close to expiry.
+   *
+   * This is the proactive path. For a JWT it means a request is never sent
+   * with a token that is about to die mid-flight, which is the failure that
+   * makes expiry bugs intermittent and miserable to reproduce.
+   */
+  async getAccessToken () {
+    if (this.needsRefresh()) { await this.refresh('proactive') }
+    return this._accessToken
+  }
+
+  /**
+   * Refresh now, regardless of expiry. Used by the reactive 401 path.
+   *
+   * Concurrent callers share one in-flight request rather than stampeding
+   * the token endpoint.
+   *
+   * @param {string} [reason] recorded for the onRefresh hook
+   */
+  async refresh (reason = 'forced') {
+    if (this._inFlight) { return this._inFlight }
+
+    this._inFlight = this._performRefresh(reason)
+      .finally(() => { this._inFlight = null })
+    return this._inFlight
+  }
+
+  async _performRefresh (reason) {
+    const body = new URLSearchParams()
+    body.set('grant_type', this.grantType)
+
+    if (this.grantType === 'refresh_token') {
+      if (!this._refreshToken) {
+        throw new RefreshError('grant_type is refresh_token but no refresh token is held')
+      }
+      body.set('refresh_token', this._refreshToken)
+    }
+    if (this.scope) { body.set('scope', this.scope) }
+
+    // Custom headers first, ours second. The protocol bits have to win:
+    // the body encoding is ours to declare, and in basic mode the
+    // Authorization header carries the client credentials. Everything else
+    // the caller set is passed through untouched, which is the point.
+    const headers = { ...this.headers }
+    headers['Content-Type'] = 'application/x-www-form-urlencoded'
+
+    if (this.credentials === 'basic') {
+      const pair = `${this.clientId ?? ''}:${this.clientSecret ?? ''}`
+      headers.Authorization = `Basic ${Buffer.from(pair).toString('base64')}`
+    } else {
+      // RFC 6749 §2.3.1 permits credentials in the body, and plenty of
+      // providers accept only this form. Forcing Basic is a real-world
+      // failure, not a style preference.
+      if (this.clientId !== undefined) { body.set('client_id', this.clientId) }
+      if (this.clientSecret !== undefined) { body.set('client_secret', this.clientSecret) }
+    }
+
+    const response = await this._fetch(this.tokenUrl, {
+      method: 'POST',
+      headers,
+      body: body.toString()
+    })
+
+    const text = await response.text()
+    if (!response.ok) {
+      throw new RefreshError(
+        `token endpoint returned ${response.status}`,
+        { status: response.status, body: text.slice(0, 500) }
+      )
+    }
+
+    let payload
+    try {
+      payload = JSON.parse(text)
+    } catch {
+      throw new RefreshError('token endpoint did not return JSON',
+        { status: response.status, body: text.slice(0, 500) })
+    }
+
+    if (!payload.access_token) {
+      throw new RefreshError('token response has no access_token',
+        { status: response.status, body: text.slice(0, 500) })
+    }
+
+    this._accessToken = payload.access_token
+
+    // Rotation. Providers that rotate refresh tokens invalidate the old one
+    // on use, so keeping the original would break the *second* refresh and
+    // look like an intermittent failure an hour into a long run.
+    if (payload.refresh_token) { this._refreshToken = payload.refresh_token }
+
+    this._expiresAtMs = typeof payload.expires_in === 'number'
+      ? this._now() + payload.expires_in * 1000
+      : null
+
+    if (this.onRefresh) {
+      this.onRefresh({
+        reason,
+        expiresIn: payload.expires_in ?? null,
+        rotated: Boolean(payload.refresh_token)
+      })
+    }
+
+    return this._accessToken
+  }
+}