axios 1.17.0 → 1.18.1

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## v1.18.0 — June 13, 2026
+
+This release hardens redirect and URL handling, improves the validateStatus configuration semantics, and includes updates to documentation, dependencies, and release metadata.
+
+## 🔒 Security Fixes
+
+* **Redirect Header Safety:** Added Node HTTP adapter support for stripping caller-specified sensitive headers on cross-origin redirects, helping prevent custom auth headers such as API keys from leaking to another origin. (__#10892__)
+
+* **URL And Request Hardening:** Rejects malformed `http:` and `https:` URLs that omit `//` with `ERR_INVALID_URL`, while tightening prototype-pollution-safe config reads, stream size limits, FormData depth handling, data URL sizing, and local `NO_PROXY` matching. (__#11000__)
+
+## 🐛 Bug Fixes
+
+* **Status Validation:** Added `transitional.validateStatusUndefinedResolves` so applications can opt in to treating `validateStatus: undefined` like the option was omitted, while `validateStatus: null` remains the explicit way to accept every status. (__#10899__)
+
+## 🔧 Maintenance & Chores
+
+* **Documentation:** Published the v1.17.0 release notes, fixed a changelog typo, clarified the package update PR policy, and marked the `proxy` request config as Node.js-only in the advanced docs. (__#10984__, __#10988__, __#10992__, __#10995__)
+
+* **Dependencies:** Bumped `@babel/core`, `@babel/preset-env`, `@commitlint/cli`, `@commitlint/config-conventional`, `@rollup/plugin-babel`, `@rollup/plugin-commonjs`, `@vitest/browser`, `@vitest/browser-playwright`, `eslint`, `lint-staged`, `rollup`, `vitest`, and `actions/checkout`. (__#10989__, __#10996__, __#10997__)
+
+* **Release Metadata:** Prepared the 1.18.0 release by updating package metadata and the runtime `VERSION` value. (__#11003__)
+
+## 🌟 New Contributors
+
+We are thrilled to welcome our new contributors. Thank you for helping improve axios:
+
+* __@drori12__ (__#10984__)
+* __@eyupcanakman__ (__#10899__)
+* __@Adi-Beker__ (__#10995__)
+
+[Full Changelog](https://github.com/axios/axios/compare/v1.17.0...v1.18.0)
+
+## v1.17.0 — June 1, 2026
+
+This release adds Node HTTP zstd decompression, hardens config and release workflows, and fixes authentication, header, proxy, and type-handling regressions.
+
+## 🔒 Security Fixes
+
+* **Config Hardening:** Guarded `socketPath`, `params`, and `paramsSerializer` reads with own-property checks to prevent inherited prototype values from affecting request behavior, including SSRF-sensitive paths. (__#10901__, __#10922__)
+* **Release Publishing:** Switched the publish workflow to npm staged publishing for safer, auditable package releases with provenance. (__#10926__)
+
+## 🚀 New Features
+
+* **HTTP Compression:** Added Node HTTP adapter support for zstd response decompression, with `transitional.advertiseZstdAcceptEncoding` controlling whether `zstd` is advertised in `Accept-Encoding`. (__#6792__, __#10920__)
+
+## 🐛 Bug Fixes
+
+* **Authentication Handling:** Restored Basic auth on same-origin Node redirects while continuing to strip credentials cross-origin, and aligned the fetch adapter with HTTP adapter behavior for URL-embedded Basic auth. (__#10929__, __#10896__)
+* **Proxy TLS:** Preserved user `httpsAgent` TLS options when tunneling HTTPS requests through HTTP CONNECT proxies. (__#10957__)
+* **React Native FormData:** Cleared default `Content-Type` for React Native `FormData` so multipart boundaries can be generated correctly. (__#10898__)
+* **Headers:** Silently skipped empty or whitespace-only header names instead of throwing, matching parsed-header behavior and avoiding React Native response crashes. (__#10875__)
+* **Request Data Merging:** Preserved enumerable symbol keys when cloning plain request data through axios merge logic. (__#10812__)
+* **Bundler Compatibility:** Converted `resolveConfig` from an arrow default export to a named function export to avoid webpack and Babel transform interop failures. (__#10891__)
+* **Types:** Corrected `AxiosHeaders.toJSON()` return types and updated CommonJS `isCancel` typings to narrow to `CanceledError<T>`. (__#10956__, __#10952__)
+* **Build Tooling:** Avoided emitting a null `Authorization` header from the GitHub build helper when `GITHUB_TOKEN` is unset. (__#10931__)
+
+## 🔧 Maintenance & Chores
+
+* **HTTP/2 Internals:** Extracted `Http2Sessions` into its own helper module and added direct unit coverage for session pooling, timeout, and cleanup behavior. (__#10861__)
+* **Package Publishing:** Reduced published package size by switching to a `files` allowlist and dropping unneeded unminified bundle source maps. (__#10939__)
+* **CI and Release Automation:** Added bundle-size reporting, moved reports to the job summary, fixed bundle-size comparison coverage, added Node 26 to the matrix, pinned npm for staged publishing, and prepared the 1.17.0 release. (__#10907__, __#10911__, __#10916__, __#10927__, __#10935__, __#10983__)
+* **Developer Workflow:** Added a dev container and iterated on OpenSpec workflow files before removing them from the release branch. (__#10925__, __#10914__, __#10958__)
+* **Documentation and Policy:** Updated disclosure, contributor, collaboration, threat-model, advanced docs, README badges, release notes, moderator configuration, and project metadata. (__#10890__, __#10889__, __#10921__, __#10945__, __#10905__, __#10933__, __#10915__, __#10887__, __#10955__)
+* **Dependencies:** Bumped Babel tooling, Commitlint, ESLint, Rollup, Globals, Vitest, Playwright, `fs-extra`, `qs`, docs dependencies, and GitHub Actions dependencies including `actions/dependency-review-action` and `zizmorcore/zizmor-action`. (__#10871__, __#10879__, __#10918__, __#10919__, __#10934__, __#10947__, __#10954__, __#10960__)
+
+## 🌟 New Contributors
+
+We are thrilled to welcome our new contributors. Thank you for helping improve axios:
+
+* __@BasixKOR__ (__#6792__)
+* __@carladams1299-lab__ (__#10861__)
+* __@LaplaceYoung__ (__#10812__)
+* __@JamieMagee__ (__#10939__)
+* __@RonGamzu__ (__#10905__)
+* __@sapirbaruch__ (__#10891__)
+* __@nezukoagent__ (__#10901__)
+* __@devareddy05__ (__#10929__)
+* __@Mohammad-Faiz-Cloud-Engineer__ (__#10922__)
+* __@azandabot__ (__#10931__)
+* __@niksy__ (__#10896__)
+
+[Full Changelog](https://github.com/axios/axios/compare/v1.16.1...v1.17.0)
+
 ## v1.16.1 — May 13, 2026
 
 This release ships a defence-in-depth fix for prototype pollution in `formDataToJSON`, hardens proxy and CI workflows, restores Webpack 4 compatibility for the fetch adapter, and includes several small bug fixes and maintenance improvements.
@@ -1432,7 +1515,7 @@ This functionality is considered as a fix.
 
 - fix: improve AxiosHeaders class [#5224](https://github.com/axios/axios/pull/5224)
 - fix: TypeScript type definitions for commonjs [#5196](https://github.com/axios/axios/pull/5196)
-- fix: type definition of use method on AxiosInterceptorManager to match the the README [#5071](https://github.com/axios/axios/pull/5071)
+- fix: type definition of use method on AxiosInterceptorManager to match the README [#5071](https://github.com/axios/axios/pull/5071)
 - fix: \_\_dirname is not defined in the sandbox [#5269](https://github.com/axios/axios/pull/5269)
 - fix: AxiosError.toJSON method to avoid circular references [#5247](https://github.com/axios/axios/pull/5247)
 - fix: Z_BUF_ERROR when content-encoding is set but the response body is empty [#5250](https://github.com/axios/axios/pull/5250)

package/README.md

@@ -298,7 +298,6 @@
     </tr>
 </table>
 
-
 <!--<div>marker</div>-->
 
 <br><br>
@@ -430,6 +429,12 @@ Using bun:
 $ bun add axios
 ```
 
+Using Deno:
+
+```bash
+$ deno add axios
+```
+
 Once the package is installed, import it with `import` or `require`:
 
 ```js
@@ -513,16 +518,16 @@ axios
 // Want to use async/await? Add the `async` keyword to your outer function/method.
 async function getUser() {
   try {
-// Example: GET request with query parameters
-const response = await axios.get('/user', {
-  params: {
-    ID: 12345
-  }
-});
+    // Example: GET request with query parameters
+    const response = await axios.get('/user', {
+      params: {
+        ID: 12345,
+      },
+    });
 
-// Using the `params` option improves readability and automatically formats query strings
+    // Using the `params` option improves readability and automatically formats query strings
 
-console.log(response);
+    console.log(response);
   } catch (error) {
     console.error(error);
   }
@@ -770,9 +775,12 @@ These config options are available for requests. Only `url` is required. Request
 
   // `data` is the data to be sent as the request body
   // Only applicable for request methods 'PUT', 'POST', 'DELETE', and 'PATCH'
+  // `data` is request-specific: axios does not inherit or deep-merge it from defaults.
+  // To add shared body fields, use a request interceptor or transformRequest.
   // When no `transformRequest` is set, it must be of one of the following types:
   // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
   // - Browser only: FormData, File, Blob
+  // - React Native: FormData
   // - Node only: Stream, Buffer, FormData (form-data package)
   data: {
     firstName: 'Fred'
@@ -877,10 +885,12 @@ These config options are available for requests. Only `url` is required. Request
     // Do whatever you want with the Axios progress event
   },
 
-  // `maxContentLength` defines the max size of the http response content in bytes allowed in node.js
+  // `maxContentLength` defines the max size of the response content in bytes.
+  // It is enforced by the Node.js HTTP adapter and the fetch adapter.
   maxContentLength: 2000,
 
-  // `maxBodyLength` (Node only option) defines the max size of the http request content in bytes allowed
+  // `maxBodyLength` defines the max size of the request content in bytes.
+  // It is enforced by the Node.js HTTP adapter and the fetch adapter when the body length can be determined.
   maxBodyLength: 2000,
 
   // `redact` masks matching config keys when AxiosError#toJSON() is called.
@@ -888,8 +898,11 @@ These config options are available for requests. Only `url` is required. Request
   redact: ['authorization', 'password'],
 
   // `validateStatus` defines whether to resolve or reject the promise for a given
-  // HTTP response status code. If `validateStatus` returns `true` (or is set to `null`
-  // or `undefined`), Axios resolves the promise; otherwise, Axios rejects it.
+  // HTTP response status code. If `validateStatus` returns `true` or is set to
+  // `null`, Axios resolves the promise; otherwise, Axios rejects it.
+  // Explicit `validateStatus: undefined` resolves every status by default for
+  // backward compatibility. Set `transitional.validateStatusUndefinedResolves`
+  // to `false` to make explicit `undefined` behave as if this option was omitted.
   validateStatus: function (status) {
     return status >= 200 && status < 300; // default
   },
@@ -898,6 +911,12 @@ These config options are available for requests. Only `url` is required. Request
   // If set to 0, Axios follows no redirects.
   maxRedirects: 21, // default
 
+  // `sensitiveHeaders` (Node only option) lists custom secret-bearing headers
+  // (such as `X-API-Key`) to remove from cross-origin redirects. Matching is
+  // case-insensitive. Same-origin redirects keep these headers. If
+  // `maxRedirects` is 0, this option is not used.
+  sensitiveHeaders: ['X-API-Key'],
+
   // `beforeRedirect` defines a function that Axios calls before redirect.
   // Use this to adjust the request options upon redirecting,
   // to inspect the latest response headers,
@@ -957,6 +976,12 @@ These config options are available for requests. Only `url` is required. Request
   // for your proxy configuration, you can also define a `no_proxy` environment
   // variable as a comma-separated list of domains that should not be proxied.
   // Use `false` to disable proxies, ignoring environment variables.
+  // On Node.js versions with native environment proxy support, axios defers
+  // environment proxy handling to Node when the selected agent has `proxyEnv`
+  // enabled, including processes started with `NODE_USE_ENV_PROXY=1`,
+  // `--use-env-proxy`, or `NODE_OPTIONS=--use-env-proxy`. Custom agents without
+  // `proxyEnv` continue to use axios environment proxy resolution. Explicit
+  // `proxy` config is still handled by axios.
   // `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and
   // supplies credentials.
   // For `http://` targets, axios sends the request to the proxy in
@@ -1033,6 +1058,11 @@ These config options are available for requests. Only `url` is required. Request
     // throw ETIMEDOUT error instead of generic ECONNABORTED on request timeouts
     clarifyTimeoutError: false,
 
+    // keep explicit `validateStatus: undefined` resolving every response status
+    // for backward compatibility. Set to false to make explicit undefined behave
+    // as if validateStatus was omitted.
+    validateStatusUndefinedResolves: true,
+
     // advertise `zstd` in the default Accept-Encoding header when the current
     // Node.js runtime supports zstd decompression. Axios still decompresses
     // zstd responses when support exists and `decompress` is true.
@@ -1063,6 +1093,15 @@ These config options are available for requests. Only `url` is required. Request
 }
 ```
 
+For custom secret-bearing headers in Node.js, list them in `sensitiveHeaders` so Axios removes them when following a redirect to another origin:
+
+```js
+axios.get('https://api.example.com/users', {
+  headers: { 'X-API-Key': 'secret' },
+  sensitiveHeaders: ['X-API-Key'],
+});
+```
+
 ### Strict RFC 3986 percent-encoding for query params
 
 By default, axios decodes `%3A`, `%24`, `%2C` and `%20` back to `:`, `$`, `,` and `+` for readability (the `+` follows the `application/x-www-form-urlencoded` convention for spaces in query strings). These characters are valid in a query component under [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4), so the default output is correct, but some backends require strict percent-encoding and reject the readable form.
@@ -1073,12 +1112,12 @@ Override the default encoder via `paramsSerializer.encode`:
 // Per-request: emit strict RFC 3986 percent-encoding for query values
 axios.get('/foo', {
   params: { filter: JSON.stringify({ startedAt: '2026-01-23' }) },
-  paramsSerializer: { encode: encodeURIComponent }
+  paramsSerializer: { encode: encodeURIComponent },
 });
 
 // Or set it on the instance defaults
 const client = axios.create({
-  paramsSerializer: { encode: encodeURIComponent }
+  paramsSerializer: { encode: encodeURIComponent },
 });
 ```
 
@@ -1167,6 +1206,8 @@ instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
 
 Axios merges config in this order: library defaults from [lib/defaults/index.js](https://github.com/axios/axios/blob/main/lib/defaults/index.js#L49), the instance `defaults` property, and the request `config` argument. Later values take precedence over earlier ones.
 
+Some options are request-specific and are only taken from the request `config`. `data` is one of those options: axios does not inherit or deep-merge request bodies from global or instance defaults. If every request needs shared body fields, add them with a request interceptor or `transformRequest`, and scope that logic carefully so sensitive values are not sent to the wrong endpoint.
+
 ```js
 // Create an instance using the config defaults provided by the library
 // At this point the timeout config value is `0` as is the default for the library
@@ -1360,7 +1401,7 @@ These are the internal Axios error codes:
 | ERR_INVALID_URL           | Invalid URL provided for axios request.                                                                                                                                                                                                                                                                                                                                                        |
 | ECONNABORTED              | Typically indicates that the request has been timed out (unless `transitional.clarifyTimeoutError` is set) or aborted by the browser or its plugin.                                                                                                                                                                                                                                            |
 | ERR_CANCELED              | The user explicitly canceled the request with an AbortSignal or CancelToken.                                                                                                                                                                                                                                                                                                                   |
-| ETIMEDOUT                 | Request timed out after exceeding the configured Axios timeout. Set `transitional.clarifyTimeoutError` to `true`; otherwise Axios throws a generic `ECONNABORTED` error.                                                                                                                                                                                                                        |
+| ETIMEDOUT                 | Request timed out after exceeding the configured Axios timeout. Set `transitional.clarifyTimeoutError` to `true`; otherwise Axios throws a generic `ECONNABORTED` error.                                                                                                                                                                                                                       |
 | ERR_NETWORK               | Network-related issue. In the browser, this error can also be caused by a [CORS](https://developer.mozilla.org/ru/docs/Web/HTTP/Guides/CORS) or [Mixed Content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content) policy violation. The browser does not allow the JS code to clarify the real reason for the error caused by security issues, so please check the console. |
 | ERR_FR_TOO_MANY_REDIRECTS | Request exceeded the configured maximum number of redirects.                                                                                                                                                                                                                                                                                                                                   |
 | ERR_BAD_RESPONSE          | Response cannot be parsed properly or is in an unexpected format. Usually related to a response with `5xx` status code.                                                                                                                                                                                                                                                                        |
@@ -1401,6 +1442,19 @@ axios.get('/user/12345', {
 });
 ```
 
+By default, explicit `validateStatus: undefined` keeps legacy behavior and resolves every response status because `transitional.validateStatusUndefinedResolves` defaults to `true`. Set it to `false` to make explicit `validateStatus: undefined` behave like the option was omitted, so Axios uses the configured/default validator and rejects non-2xx responses by default.
+
+`validateStatus: null` still accepts every response status. If you disable the transitional behavior and intentionally want all statuses to resolve, use `null` or `() => true`.
+
+```js
+axios.get('/user/12345', {
+  validateStatus: undefined,
+  transitional: {
+    validateStatusUndefinedResolves: false,
+  },
+});
+```
+
 Use `toJSON` to get more information about the HTTP error.
 
 ```js
@@ -1412,12 +1466,14 @@ axios.get('/user/12345').catch(function (error) {
 To avoid logging secrets from `error.config`, pass a `redact` array in the request config. Matching config keys are masked case-insensitively at any depth when `AxiosError#toJSON()` is called.
 
 ```js
-axios.get('/user/12345', {
-  headers: { Authorization: 'Bearer token' },
-  redact: ['authorization']
-}).catch(function (error) {
-  console.log(error.toJSON().config.headers.Authorization); // [REDACTED ****]
-});
+axios
+  .get('/user/12345', {
+    headers: { Authorization: 'Bearer token' },
+    redact: ['authorization'],
+  })
+  .catch(function (error) {
+    console.log(error.toJSON().config.headers.Authorization); // [REDACTED ****]
+  });
 ```
 
 ## Handling timeouts
@@ -1527,11 +1583,44 @@ axios.get('/user/12345', {
 cancel();
 ```
 
+`CancelToken` also exposes low-level helpers for legacy integrations:
+
+```js
+const source = axios.CancelToken.source();
+
+const listener = (cancel) => {
+  console.log(cancel.message);
+};
+
+source.token.subscribe(listener);
+
+const signal = source.token.toAbortSignal();
+// Pass `signal` to APIs that accept AbortSignal.
+
+source.cancel('Operation canceled by the user.');
+source.token.unsubscribe(listener);
+```
+
+Canceled requests reject with `axios.CanceledError`. The legacy `axios.Cancel` export is an alias of `axios.CanceledError`, and cancellation errors include `__CANCEL__` for `axios.isCancel` compatibility.
+
 > Note: You can cancel several requests with the same cancel token or abort controller.
 > If a cancellation token is already cancelled when an Axios request starts, Axios cancels the request immediately without making a real request.
 
 > During the transition period, you can use both cancellation APIs, even for the same request:
 
+```js
+const controller = new AbortController();
+const source = axios.CancelToken.source();
+
+axios.get('/user/12345', {
+  cancelToken: source.token,
+  signal: controller.signal,
+});
+
+controller.abort();
+source.cancel('Operation canceled by the user.');
+```
+
 ## Using `application/x-www-form-urlencoded` format
 
 ### URLSearchParams
@@ -1640,6 +1729,7 @@ server = app.listen(3000);
 
 To send data as `multipart/form-data`, pass a FormData instance as the payload.
 You do not need to set the `Content-Type` header. Axios detects it from the payload type.
+For browser, web worker, and React Native `FormData`, leave `Content-Type` unset so the runtime can add the multipart boundary.
 
 ```js
 const formData = new FormData();
@@ -1732,6 +1822,9 @@ FormData serializer supports additional options via `config.formSerializer: obje
   input object exceeds this depth, an `AxiosError` with `code: 'ERR_FORM_DATA_DEPTH_EXCEEDED'` is
   thrown instead of overflowing the call stack. This protects server applications from DoS
   attacks via deeply nested payloads. Set to `Infinity` to disable the limit and restore pre-fix behaviour.
+- `Blob: typeof Blob` - Blob constructor used when converting ArrayBuffer-like values for spec-compliant
+  `FormData`. Override it only for runtimes that provide a compatible `Blob` constructor under a
+  different binding.
 
 ```js
 // Raise the limit for a schema that genuinely nests deeper than 100 levels:
@@ -2058,6 +2151,7 @@ console.log(headers);
 set(headerName, value: Axios, rewrite?: boolean);
 set(headerName, value, rewrite?: (this: AxiosHeaders, value: string, name: string, headers: RawAxiosHeaders) => boolean);
 set(headers?: RawAxiosHeaders | AxiosHeaders | string, rewrite?: boolean);
+set(headers?: Iterable<[string, AxiosHeaderValue]>, rewrite?: boolean);
 ```
 
 The `rewrite` argument controls the overwriting behavior:
@@ -2068,6 +2162,21 @@ The `rewrite` argument controls the overwriting behavior:
 
 The option can also accept a user-defined function that determines whether to overwrite the value.
 
+Empty or whitespace-only header names are ignored.
+
+Iterable key/value pairs, such as a `Map`, are accepted:
+
+```js
+const headers = new AxiosHeaders();
+
+headers.set(
+  new Map([
+    ['X-Trace-Id', 'abc123'],
+    ['Accept', 'application/json'],
+  ])
+);
+```
+
 Returns `this`.
 
 ### AxiosHeaders#get(header)
@@ -2188,6 +2297,14 @@ toJSON(asStrings?: false): Record<string, string | string[]>;
 Resolves all internal header values into a new null prototype object.
 Set `asStrings` to true to resolve arrays as a string containing all elements, separated by commas.
 
+### AxiosHeaders#toString()
+
+```
+toString(): string;
+```
+
+Returns the headers as a CRLF-free HTTP header block, one `name: value` pair per line.
+
 ### AxiosHeaders.from(thing?)
 
 ```
@@ -2243,6 +2360,8 @@ const { data } = fetchAxios.get(url);
 The adapter supports the same features as the `xhr` adapter, including upload and download progress capturing.
 It also supports response types such as `stream` and `formdata` when the environment supports them.
 
+When `auth` is omitted, the fetch adapter can read HTTP Basic auth credentials from the request URL, for example `https://user:pass@example.com`. Percent-encoded URL credentials are decoded before the `Authorization` header is generated, and `auth` takes precedence over URL-embedded credentials.
+
 ### Custom fetch
 
 Since `v1.12.0`, you can configure the fetch adapter to use a custom fetch API instead of environment globals.
@@ -2365,6 +2484,20 @@ try {
 }
 ```
 
+Use `axios.isCancel<T>()` to narrow cancellation errors to `CanceledError<T>`:
+
+```typescript
+const controller = new AbortController();
+
+try {
+  await axios.get<User>('/user?ID=12345', { signal: controller.signal });
+} catch (error) {
+  if (axios.isCancel<User>(error)) {
+    handleCancellation(error);
+  }
+}
+```
+
 Because axios publishes an ESM default export and a CJS `module.exports`, TypeScript has a few caveats.
 The recommended setting is `"moduleResolution": "node16"`, which is implied by `"module": "node16"`. This requires TypeScript 4.7 or greater.
 If you use ESM, your settings should be fine.