## Summary
Adds a new CI-enforced ESLint rule that prevents shipped SDK libraries
from taking new **third-party runtime dependencies** without approval.
Dependencies are validated against a central allow-list so adding a new
one is a deliberate, reviewable change.
## How it works
- **New rule** `@azure/azure-sdk/ts-package-json-approved-dependencies`
in `@azure/eslint-plugin-azure-sdk`, enabled as `error` in the default
config. Runs as part of `pnpm lint` and in CI via the existing lint
path.
- **Scope**: only shipped libraries — `package.json` files under `sdk/`
with `"sdk-type": "client"` or `"sdk-type": "mgmt"`. Samples, tests,
perf tests, and utility/tooling packages are out of scope. Only the
`dependencies` field is checked; `devDependencies` and
`peerDependencies` are ignored.
- **Allow-list**: `eng/approved-third-party-dependencies.yml`
- First-party scopes (`@azure/`, `@azure-rest/`, `@azure-tools/`,
`@microsoft/`, `@typespec/`) are always approved and need not be listed.
- `allowed`: dependencies any in-scope package may take.
- `exceptions`: dependencies only specific named packages may take.
- Entries may be exact names **or scope wildcards** (`@scope/*`) that
match every package in an npm scope. Wildcards work in both `allowed`
and `exceptions`.
## Allow-list seeding & curation
The list was **seeded from current usage** so existing packages continue
to pass. During review the following were curated up to globally
`allowed`:
- `@opentelemetry/*` (entire scope, via wildcard)
- `rhea`, `rhea-promise`, `buffer`, `events`, `fast-xml-parser`,
`http-proxy-agent`, `https-proxy-agent`, `openai`
The remaining ~45 genuinely package-specific dependencies stay as scoped
`exceptions`. These reflect current state, not a final curated policy —
entries can be tightened or promoted over time.
## Failure behavior
If an in-scope package declares a runtime dependency that is neither
first-party nor approved, lint fails with a message pointing at the
allow-list and explaining how to add an `allowed` or `exceptions` entry.
The rule fails closed if the allow-list is missing or malformed.
## Tests & docs
- 17 rule tests (incl. wildcard cases); full plugin suite (703 tests)
passes; Prettier clean.
- Author-facing guidance lives in
`documentation/steps-after-generations.md` ("Adding a new third-party
runtime dependency"), with a pointer left in
`documentation/dependency-management.md` (which targets library
*consumers* managing transitive dependencies, not SDK authors).
- Also updated: the new rule doc page, reviewer dependency instructions,
and the plugin README rule table.
## Incidental cleanups
- Fixed a malformed markdown link (`github-source-headers`) in the
plugin README rules table that was missing its opening `(`.
- Removed the broad `docs/` rule from the root `.gitignore` (and its
now-orphaned `!eng/scripts/docs` negation). That legacy rule forced `git
add -f` for legitimate hand-authored docs while protecting nothing
generated — package builds emit to `dist/`/`review/`/`temp/` and
pipeline TypeDoc output goes to `docGen/` (still ignored). Verified by
building `@azure/storage-blob`, which produced no `docs/` output; the
only `docs/` directories in the source tree are already tracked.
## Notes for reviewers
- A few `@azure-tools/*` packages (e.g. `mock-hub`, some
`communication-*`) appear as exception consumers because they carry
`sdk-type: client`.
- The allow-list is the artifact owners will maintain going forward.
Co-authored-by: Copilot <[email protected]>
---------
Co-authored-by: Copilot <[email protected]>
4.4 KiB
Dependency Management
The Azure SDK for JS client libraries include a host of dependencies, both internal and external. In general, our policy allows for some flexibility in dependencies and we generally pin to a caret version - allowing for patches, security fixes, and any non-breaking changes in our dependency ranges.
There are times when a dependency needs to be updated, such as when a security vulnerability has been found and patched in the dependency's codebase. While we will address security vulnerabilities in dependencies by updating our minimum version to the latest patched version, our SemVer policy allows customers to update to the latest version of a transitive dependency without waiting for our next releases and without requiring a hotfix.
In this document we'll outline a few options available to you when a transitive dependency must be updated.
SDK authors: for the policy on taking a new third-party runtime dependency in a shipped library, see Adding a new third-party runtime dependency.
Example scenario
Let's assume that a vulnerability has been found in node-fetch version 2.6.6 and that you use @azure/keyvault-keys directly. Your security scan identified this vulnerability and asks to upgrade to 2.6.7 or higher.
The outputs below assume you're using npm v8.1.2 with a lockfile, but we will provide instructions for Yarn as well.
Identifying the dependency tree
First, let's see how node-fetch is pulled into our dependency tree.
> npm ls node-fetch
[email protected] /home/user/my-app
└─┬ @azure/[email protected]
└─┬ @azure/[email protected]
└── [email protected]
If you are using Yarn you can use
yarn why node-fetchwith similar results.
It looks like node-fetch, a dependency of @azure/[email protected] is being pulled in transitively via @azure/[email protected].
Because I use a lockfile, running npm install again will not help me here. But npm provides a few utilities that can.
Using npm audit fix
First, it's possible that you were alerted to a security vulnerability thanks to npm audit. In this case, the simplest solution might be to run npm audit fix. Let's see what that looks like:
> npm audit fix
changed 1 package, and audited 51 packages in 421ms
2 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
keyvault main % npm ls node-fetch
[email protected] /home/user/my-app
└─┬ @azure/[email protected]
└─┬ @azure/[email protected]
└── [email protected]
As you can see node-fetch has been updated to 2.6.7, without having to wait for a new version of @azure/core-http.
For more information on npm audit please refer to the npm-audit documentation.
If you are using Yarn you can use
yarn npm auditwith similar results.
Using npm update
Not all updates are due to security vulnerabilities. Sometimes you just want to update a transitive dependency without deleting your lockfile. In that case, npm update node-fetch can help. Let's see what that looks like:
> npm update node-fetch
changed 1 package, and audited 51 packages in 320ms
2 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
keyvault main % npm ls node-fetch
[email protected] /home/user/my-app
└─┬ @azure/[email protected]
└─┬ @azure/[email protected]
└── [email protected]
Awesome!
If you are using Yarn you can use
yarn up node-fetchwith similar results.
Note: In some previous versions of
npm,npm updatewould only update top-level dependencies. If you're using npm 6.x for example you can provide the--depthargument to achieve similar results.
For more information on npm update please refer to the npm-update documentation.
I read this guide and still have no idea what to do
Feel free to file an issue and start a discussion, we're here to help and will try to do so to the best of our abilities!