npm · Oct 17, 2022 · Oct 17, 2022 · Oct 19, 2022 · Oct 19, 2022 · Oct 28, 2022
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -7,6 +7,7 @@ updates:
     directory: /
     schedule:
       interval: daily
+    target-branch: "main"
     allow:
       - dependency-type: direct
     versioning-strategy: increase-if-necessary

diff --git a/.github/settings.yml b/.github/settings.yml
@@ -1,2 +1,27 @@
----
-_extends: '.github:npm-cli/settings.yml'
+# This file is automatically added by @npmcli/template-oss. Do not edit.
+
+repository:
+  allow_merge_commit: false
+  allow_rebase_merge: true
+  allow_squash_merge: true
+  squash_merge_commit_title: PR_TITLE
+  squash_merge_commit_message: PR_BODY
+  delete_branch_on_merge: true
+  enable_automated_security_fixes: true
+  enable_vulnerability_alerts: true
+
+branches:
+  - name: main
+    protection:
+      required_status_checks: null
+      enforce_admins: true
+      block_creations: true
+      required_pull_request_reviews:
+        required_approving_review_count: 1
+        require_code_owner_reviews: true
+        require_last_push_approval: true
+        dismiss_stale_reviews: true
+      restrictions:
+        apps: []
+        users: []
+        teams: [ "cli-team" ]
diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.yml
@@ -33,5 +33,7 @@ jobs:
         run: npm -v
       - name: Install Dependencies
         run: npm i --ignore-scripts --no-audit --no-fund --package-lock
-      - name: Run Audit
-        run: npm audit
+      - name: Run Production Audit
+        run: npm audit --omit=dev
+      - name: Run Full Audit
+        run: npm audit --audit-level=none
diff --git a/.github/workflows/ci-release.yml b/.github/workflows/ci-release.yml
@@ -3,6 +3,12 @@
 name: CI - Release
 
 on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        required: true
+        type: string
+        default: main
   workflow_call:
     inputs:
       ref:
@@ -21,21 +27,49 @@ jobs:
       run:
         shell: bash
     steps:
+      - name: Get Workflow Job
+        uses: actions/github-script@v6
+        if: inputs.check-sha
+        id: check-output
+        env:
+          JOB_NAME: "Lint All"
+          MATRIX_NAME: ""
+        with:
+          script: |
+            const { owner, repo } = context.repo
+
+            const { data } = await github.rest.actions.listJobsForWorkflowRun({
+              owner,
+              repo,
+              run_id: context.runId,
+              per_page: 100
+            })
+
+            const jobName = process.env.JOB_NAME + process.env.MATRIX_NAME
+            const job = data.jobs.find(j => j.name.endsWith(jobName))
+            const jobUrl = job?.html_url
+
+            const shaUrl = `${context.serverUrl}/${owner}/${repo}/commit/${{ inputs.check-sha }}`
+
+            let summary = `This check is assosciated with ${shaUrl}\n\n`
+
+            if (jobUrl) {
+              summary += `For run logs, click here: ${jobUrl}`
+            } else {
+              summary += `Run logs could not be found for a job with name: "${jobName}"`
+            }
+
+            return { summary }
       - name: Create Check
-        uses: LouisBrunner/checks-action@v1.3.1
+        uses: LouisBrunner/checks-action@v1.6.0
         id: check
-
+        if: inputs.check-sha
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           status: in_progress
           name: Lint All
           sha: ${{ inputs.check-sha }}
-          # XXX: this does not work when using the default GITHUB_TOKEN.
-          # Instead we post the main job url to the PR as a comment which
-          # will link to all the other checks. To work around this we would
-          # need to create a GitHub that would create on-demand tokens.
-          # https://github.com/LouisBrunner/checks-action/issues/18
-          # details_url:
+          output: ${{ steps.check-output.outputs.result }}
       - name: Checkout
         uses: actions/checkout@v3
         with:
@@ -59,8 +93,8 @@ jobs:
       - name: Post Lint
         run: npm run postlint --ignore-scripts
       - name: Conclude Check
-        uses: LouisBrunner/checks-action@v1.3.1
-        if: always()
+        uses: LouisBrunner/checks-action@v1.6.0
+        if: steps.check.outputs.check_id && always()
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           conclusion: ${{ job.status }}
@@ -83,8 +117,6 @@ jobs:
             os: windows-latest
             shell: cmd
         node-version:
-          - 14.17.0
-          - 14.x
           - 16.13.0
           - 16.x
           - 18.0.0
@@ -94,21 +126,49 @@ jobs:
       run:
         shell: ${{ matrix.platform.shell }}
     steps:
+      - name: Get Workflow Job
+        uses: actions/github-script@v6
+        if: inputs.check-sha
+        id: check-output
+        env:
+          JOB_NAME: "Test All"
+          MATRIX_NAME: " - ${{ matrix.platform.name }} - ${{ matrix.node-version }}"
+        with:
+          script: |
+            const { owner, repo } = context.repo
+
+            const { data } = await github.rest.actions.listJobsForWorkflowRun({
+              owner,
+              repo,
+              run_id: context.runId,
+              per_page: 100
+            })
+
+            const jobName = process.env.JOB_NAME + process.env.MATRIX_NAME
+            const job = data.jobs.find(j => j.name.endsWith(jobName))
+            const jobUrl = job?.html_url
+
+            const shaUrl = `${context.serverUrl}/${owner}/${repo}/commit/${{ inputs.check-sha }}`
+
+            let summary = `This check is assosciated with ${shaUrl}\n\n`
+
+            if (jobUrl) {
+              summary += `For run logs, click here: ${jobUrl}`
+            } else {
+              summary += `Run logs could not be found for a job with name: "${jobName}"`
+            }
+
+            return { summary }
       - name: Create Check
-        uses: LouisBrunner/checks-action@v1.3.1
+        uses: LouisBrunner/checks-action@v1.6.0
         id: check
-
+        if: inputs.check-sha
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           status: in_progress
           name: Test All - ${{ matrix.platform.name }} - ${{ matrix.node-version }}
           sha: ${{ inputs.check-sha }}
-          # XXX: this does not work when using the default GITHUB_TOKEN.
-          # Instead we post the main job url to the PR as a comment which
-          # will link to all the other checks. To work around this we would
-          # need to create a GitHub that would create on-demand tokens.
-          # https://github.com/LouisBrunner/checks-action/issues/18
-          # details_url:
+          output: ${{ steps.check-output.outputs.result }}
       - name: Checkout
         uses: actions/checkout@v3
         with:
@@ -146,8 +206,8 @@ jobs:
       - name: Test
         run: npm test --ignore-scripts
       - name: Conclude Check
-        uses: LouisBrunner/checks-action@v1.3.1
-        if: always()
+        uses: LouisBrunner/checks-action@v1.6.0
+        if: steps.check.outputs.check_id && always()
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           conclusion: ${{ job.status }}

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -8,62 +8,11 @@ on:
   push:
     branches:
       - main
-      - latest
   schedule:
     # "At 09:00 UTC (02:00 PT) on Monday" https://crontab.guru/#0_9_*_*_1
     - cron: "0 9 * * 1"
 
 jobs:
-  engines:
-    name: Engines - ${{ matrix.platform.name }} - ${{ matrix.node-version }}
-    if: github.repository_owner == 'npm'
-    strategy:
-      fail-fast: false
-      matrix:
-        platform:
-          - name: Linux
-            os: ubuntu-latest
-            shell: bash
-        node-version:
-          - 14.17.0
-          - 16.13.0
-          - 18.0.0
-    runs-on: ${{ matrix.platform.os }}
-    defaults:
-      run:
-        shell: ${{ matrix.platform.shell }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup Git User
-        run: |
-          git config --global user.email "npm-cli+bot@github.com"
-          git config --global user.name "npm CLI robot"
-      - name: Setup Node
-        uses: actions/setup-node@v3
-        with:
-          node-version: ${{ matrix.node-version }}
-      - name: Update Windows npm
-        # node 12 and 14 ship with npm@6, which is known to fail when updating itself in windows
-        if: matrix.platform.os == 'windows-latest' && (startsWith(matrix.node-version, '12.') || startsWith(matrix.node-version, '14.'))
-        run: |
-          curl -sO https://registry.npmjs.org/npm/-/npm-7.5.4.tgz
-          tar xf npm-7.5.4.tgz
-          cd package
-          node lib/npm.js install --no-fund --no-audit -g ..\npm-7.5.4.tgz
-          cd ..
-          rmdir /s /q package
-      - name: Install npm@7
-        if: startsWith(matrix.node-version, '10.')
-        run: npm i --prefer-online --no-fund --no-audit -g npm@7
-      - name: Install npm@latest
-        if: ${{ !startsWith(matrix.node-version, '10.') }}
-        run: npm i --prefer-online --no-fund --no-audit -g npm@latest
-      - name: npm Version
-        run: npm -v
-      - name: Install Dependencies
-        run: npm i --ignore-scripts --no-audit --no-fund --engines-strict
-
   lint:
     name: Lint
     if: github.repository_owner == 'npm'
@@ -110,8 +59,6 @@ jobs:
             os: windows-latest
             shell: cmd
         node-version:
-          - 14.17.0
-          - 14.x
           - 16.13.0
           - 16.x
           - 18.0.0

diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -6,11 +6,9 @@ on:
   push:
     branches:
       - main
-      - latest
   pull_request:
     branches:
       - main
-      - latest
   schedule:
     # "At 10:00 UTC (03:00 PT) on Monday" https://crontab.guru/#0_10_*_*_1
     - cron: "0 10 * * 1"

diff --git a/.github/workflows/post-dependabot.yml b/.github/workflows/post-dependabot.yml
@@ -48,11 +48,11 @@ jobs:
         run: |
           dependabot_dir="${{ steps.metadata.outputs.directory }}"
           if [[ "$dependabot_dir" == "/" ]]; then
-            echo "::set-output name=workspace::-iwr"
+            echo "workspace=-iwr" >> $GITHUB_OUTPUT
           else
             # strip leading slash from directory so it works as a
             # a path to the workspace flag
-            echo "::set-output name=workspace::-w ${dependabot_dir#/}"
+            echo "workspace=-w ${dependabot_dir#/}" >> $GITHUB_OUTPUT
           fi
 
       - name: Apply Changes
@@ -61,17 +61,17 @@ jobs:
         run: |
           npm run template-oss-apply ${{ steps.flags.outputs.workspace }}
           if [[ `git status --porcelain` ]]; then
-            echo "::set-output name=changes::true"
+            echo "changes=true" >> $GITHUB_OUTPUT
           fi
           # This only sets the conventional commit prefix. This workflow can't reliably determine
           # what the breaking change is though. If a BREAKING CHANGE message is required then
           # this PR check will fail and the commit will be amended with stafftools
-          if [[ "${{ steps.dependabot-metadata.outputs.update-type }}" == "version-update:semver-major" ]]; then
+          if [[ "${{ steps.metadata.outputs.update-type }}" == "version-update:semver-major" ]]; then
             prefix='feat!'
           else
-            prefix='chore!'
+            prefix='chore'
           fi
-          echo "::set-output name=message::$prefix: postinstall for dependabot template-oss PR"
+          echo "message=$prefix: postinstall for dependabot template-oss PR" >> $GITHUB_OUTPUT
 
       # This step will fail if template-oss has made any workflow updates. It is impossible
       # for a workflow to update other workflows. In the case it does fail, we continue
@@ -90,7 +90,7 @@ jobs:
       # and attempt to commit and push again. This is helpful because we will have a commit
       # with the correct prefix that we can then --amend with @npmcli/stafftools later.
       - name: Push All Changes Except Workflows
-        if: steps.apply.outputs.changes && steps.push-all.outcome == 'failure'
+        if: steps.apply.outputs.changes && steps.push.outcome == 'failure'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |

diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml
@@ -41,8 +41,10 @@ jobs:
         id: commit
         continue-on-error: true
         run: |
-          npx --offline commitlint -V --from origin/${{ github.base_ref }} --to ${{ github.event.pull_request.head.sha }}
+          npx --offline commitlint -V --from 'origin/${{ github.base_ref }}' --to ${{ github.event.pull_request.head.sha }}
       - name: Run Commitlint on PR Title
         if: steps.commit.outcome == 'failure'
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
         run: |
-          echo ${{ github.event.pull_request.title }} | npx --offline commitlint -V
+          echo "$PR_TITLE" | npx --offline commitlint -V
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -3,10 +3,14 @@
 name: Release
 
 on:
+  workflow_dispatch:
+    inputs:
+      release-pr:
+        description: a release PR number to rerun release jobs on
+        type: string
   push:
     branches:
       - main
-      - latest
 
 permissions:
   contents: write
@@ -17,8 +21,8 @@ jobs:
   release:
     outputs:
       pr: ${{ steps.release.outputs.pr }}
+      release: ${{ steps.release.outputs.release }}
       releases: ${{ steps.release.outputs.releases }}
-      release-flags: ${{ steps.release.outputs.release-flags }}
       branch: ${{ steps.release.outputs.pr-branch }}
       pr-number: ${{ steps.release.outputs.pr-number }}
       comment-id: ${{ steps.pr-comment.outputs.result }}
@@ -51,49 +55,82 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          npx --offline template-oss-release-please ${{ github.ref_name }}
+          npx --offline template-oss-release-please "${{ github.ref_name }}" "${{ inputs.release-pr }}"
       - name: Post Pull Request Comment
         if: steps.release.outputs.pr-number
         uses: actions/github-script@v6
         id: pr-comment
         env:
           PR_NUMBER: ${{ steps.release.outputs.pr-number }}
+          REF_NAME: ${{ github.ref_name }}
         with:
           script: |
-            const repo = { owner: context.repo.owner, repo: context.repo.repo }
-            const issue = { ...repo, issue_number: process.env.PR_NUMBER }
+            const { REF_NAME, PR_NUMBER: issue_number } = process.env
+            const { runId, repo: { owner, repo } } = context
 
-            const { data: workflow } = await github.rest.actions.getWorkflowRun({ ...repo, run_id: context.runId })
+            const { data: workflow } = await github.rest.actions.getWorkflowRun({ owner, repo, run_id: runId })
 
             let body = '## Release Manager\n\n'
 
-            const comments = await github.paginate(github.rest.issues.listComments, issue)
-            let commentId = comments?.find(c => c.user.login === 'github-actions[bot]' && c.body.startsWith(body))?.id
+            const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number })
+            let commentId = comments.find(c => c.user.login === 'github-actions[bot]' && c.body.startsWith(body))?.id
+
+            body += `Release workflow run: ${workflow.html_url}\n\n#### Force CI to Update This Release\n\n`
+            body += `This PR will be updated and CI will run for every non-\`chore:\` commit that is pushed to \`${REF_NAME}\`. `
+            body += `To force CI to update this PR, run this command:\n\n`
+            body += `\`\`\`\ngh workflow run release.yml -r ${REF_NAME} -R ${owner}/${repo} -f release-pr=${issue_number}\n\`\`\``
 
-            body += `- Release workflow run: ${workflow.html_url}`
             if (commentId) {
-              await github.rest.issues.updateComment({ ...repo, comment_id: commentId, body })
+              await github.rest.issues.updateComment({ owner, repo, comment_id: commentId, body })
             } else {
-              const { data: comment } = await github.rest.issues.createComment({ ...issue, body })
+              const { data: comment } = await github.rest.issues.createComment({ owner, repo, issue_number, body })
               commentId = comment?.id
             }
 
             return commentId
+      - name: Get Workflow Job
+        uses: actions/github-script@v6
+        if: steps.release.outputs.pr-sha
+        id: check-output
+        env:
+          JOB_NAME: "Release"
+          MATRIX_NAME: ""
+        with:
+          script: |
+            const { owner, repo } = context.repo
+
+            const { data } = await github.rest.actions.listJobsForWorkflowRun({
+              owner,
+              repo,
+              run_id: context.runId,
+              per_page: 100
+            })
+
+            const jobName = process.env.JOB_NAME + process.env.MATRIX_NAME
+            const job = data.jobs.find(j => j.name.endsWith(jobName))
+            const jobUrl = job?.html_url
+
+            const shaUrl = `${context.serverUrl}/${owner}/${repo}/commit/${{ steps.release.outputs.pr-sha }}`
+
+            let summary = `This check is assosciated with ${shaUrl}\n\n`
+
+            if (jobUrl) {
+              summary += `For run logs, click here: ${jobUrl}`
+            } else {
+              summary += `Run logs could not be found for a job with name: "${jobName}"`
+            }
+
+            return { summary }
       - name: Create Check
-        uses: LouisBrunner/checks-action@v1.3.1
+        uses: LouisBrunner/checks-action@v1.6.0
         id: check
-        if: steps.release.outputs.pr-number
+        if: steps.release.outputs.pr-sha
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           status: in_progress
           name: Release
           sha: ${{ steps.release.outputs.pr-sha }}
-          # XXX: this does not work when using the default GITHUB_TOKEN.
-          # Instead we post the main job url to the PR as a comment which
-          # will link to all the other checks. To work around this we would
-          # need to create a GitHub that would create on-demand tokens.
-          # https://github.com/LouisBrunner/checks-action/issues/18
-          # details_url:
+          output: ${{ steps.check-output.outputs.result }}
 
   update:
     needs: release
@@ -132,7 +169,7 @@ jobs:
           RELEASE_COMMENT_ID: ${{ needs.release.outputs.comment-id }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          npm exec --offline -- template-oss-release-manager
+          npm exec --offline -- template-oss-release-manager --lockfile=false --publish=true
           npm run rp-pull-request --ignore-scripts --if-present
       - name: Commit
         id: commit
@@ -141,25 +178,53 @@ jobs:
         run: |
           git commit --all --amend --no-edit || true
           git push --force-with-lease
-          echo "::set-output  name=sha::$(git rev-parse HEAD)"
+          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
+      - name: Get Workflow Job
+        uses: actions/github-script@v6
+        if: steps.commit.outputs.sha
+        id: check-output
+        env:
+          JOB_NAME: "Update - Release"
+          MATRIX_NAME: ""
+        with:
+          script: |
+            const { owner, repo } = context.repo
+
+            const { data } = await github.rest.actions.listJobsForWorkflowRun({
+              owner,
+              repo,
+              run_id: context.runId,
+              per_page: 100
+            })
+
+            const jobName = process.env.JOB_NAME + process.env.MATRIX_NAME
+            const job = data.jobs.find(j => j.name.endsWith(jobName))
+            const jobUrl = job?.html_url
+
+            const shaUrl = `${context.serverUrl}/${owner}/${repo}/commit/${{ steps.commit.outputs.sha }}`
+
+            let summary = `This check is assosciated with ${shaUrl}\n\n`
+
+            if (jobUrl) {
+              summary += `For run logs, click here: ${jobUrl}`
+            } else {
+              summary += `Run logs could not be found for a job with name: "${jobName}"`
+            }
+
+            return { summary }
       - name: Create Check
-        uses: LouisBrunner/checks-action@v1.3.1
+        uses: LouisBrunner/checks-action@v1.6.0
         id: check
-
+        if: steps.commit.outputs.sha
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           status: in_progress
           name: Release
           sha: ${{ steps.commit.outputs.sha }}
-          # XXX: this does not work when using the default GITHUB_TOKEN.
-          # Instead we post the main job url to the PR as a comment which
-          # will link to all the other checks. To work around this we would
-          # need to create a GitHub that would create on-demand tokens.
-          # https://github.com/LouisBrunner/checks-action/issues/18
-          # details_url:
+          output: ${{ steps.check-output.outputs.result }}
       - name: Conclude Check
-        uses: LouisBrunner/checks-action@v1.3.1
-        if: always()
+        uses: LouisBrunner/checks-action@v1.6.0
+        if: needs.release.outputs.check-id && always()
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           conclusion: ${{ job.status }}
@@ -194,10 +259,10 @@ jobs:
           else
             result="success"
           fi
-          echo "::set-output name=result::$result"
+          echo "result=$result" >> $GITHUB_OUTPUT
       - name: Conclude Check
-        uses: LouisBrunner/checks-action@v1.3.1
-        if: always()
+        uses: LouisBrunner/checks-action@v1.6.0
+        if: needs.update.outputs.check-id && always()
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           conclusion: ${{ steps.needs-result.outputs.result }}
@@ -211,25 +276,122 @@ jobs:
     defaults:
       run:
         shell: bash
+    steps:
+      - name: Create Release PR Comment
+        uses: actions/github-script@v6
+        env:
+          RELEASES: ${{ needs.release.outputs.releases }}
+        with:
+          script: |
+            const releases = JSON.parse(process.env.RELEASES)
+            const { runId, repo: { owner, repo } } = context
+            const issue_number = releases[0].prNumber
+
+            let body = '## Release Workflow\n\n'
+            for (const { pkgName, version, url } of releases) {
+              body += `- \`${pkgName}@${version}\` ${url}\n`
+            }
+
+            const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number })
+              .then(cs => cs.map(c => ({ id: c.id, login: c.user.login, body: c.body })))
+            console.log(`Found comments: ${JSON.stringify(comments, null, 2)}`)
+            const releaseComments = comments.filter(c => c.login === 'github-actions[bot]' && c.body.includes('Release is at'))
+
+            for (const comment of releaseComments) {
+              console.log(`Release comment: ${JSON.stringify(comment, null, 2)}`)
+              await github.rest.issues.deleteComment({ owner, repo, comment_id: comment.id })
+            }
+
+            const runUrl = `https://github.com/${owner}/${repo}/actions/runs/${runId}`
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number,
+              body: `${body}- Workflow run: :arrows_counterclockwise: ${runUrl}`,
+            })
+
+  release-integration:
+    needs: release
+    name: Release Integration
+    if: needs.release.outputs.release
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    permissions:
+      deployments: write
+      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v3
-      - name: Setup Git User
-        run: |
-          git config --global user.email "npm-cli+bot@github.com"
-          git config --global user.name "npm CLI robot"
+        with:
+          ref: ${{ fromJSON(needs.release.outputs.release).tagName }}
       - name: Setup Node
         uses: actions/setup-node@v3
         with:
           node-version: 18.x
       - name: Install npm@latest
-        run: npm i --prefer-online --no-fund --no-audit -g npm@latest
-      - name: npm Version
-        run: npm -v
-      - name: Install Dependencies
-        run: npm i --ignore-scripts --no-audit --no-fund
-      - name: Run Post Release Actions
+        run: |
+          npm i --prefer-online --no-fund --no-audit -g npm@latest
+          npm config set '//registry.npmjs.org/:_authToken'=\${PUBLISH_TOKEN}
+      - name: Publish
         env:
-          RELEASES: ${{ needs.release.outputs.releases }}
+          PUBLISH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
+        run: npm publish --provenance
+
+  post-release-integration:
+    needs: [ release, release-integration ]
+    name: Post Release Integration - Release
+    if: github.repository_owner == 'npm' && needs.release.outputs.release && always()
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Get Needs Result
+        id: needs-result
         run: |
-          npm run rp-release --ignore-scripts --if-present ${{ join(fromJSON(needs.release.outputs.release-flags), ' ') }}
+          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+            result="x"
+          elif [[ "${{ contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
+            result="heavy_multiplication_x"
+          else
+            result="white_check_mark"
+          fi
+          echo "result=$result" >> $GITHUB_OUTPUT
+      - name: Update Release PR Comment
+        uses: actions/github-script@v6
+        env:
+          PR_NUMBER: ${{ fromJSON(needs.release.outputs.release).prNumber }}
+          RESULT: ${{ steps.needs-result.outputs.result }}
+        with:
+          script: |
+            const { PR_NUMBER: issue_number, RESULT } = process.env
+            const { runId, repo: { owner, repo } } = context
+
+            const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number })
+            const updateComment = comments.find(c =>
+              c.user.login === 'github-actions[bot]' &&
+              c.body.startsWith('## Release Workflow\n\n') &&
+              c.body.includes(runId)
+            )
+
+            if (updateComment) {
+              console.log('Found comment to update:', JSON.stringify(updateComment, null, 2))
+              let body = updateComment.body.replace(/Workflow run: :[a-z_]+:/, `Workflow run: :${RESULT}:`)
+              const tagCodeowner = RESULT !== 'white_check_mark'
+              if (tagCodeowner) {
+                body += `\n\n:rotating_light:`
+                body += ` @npm/cli-team: The post-release workflow failed for this release.`
+                body += ` Manual steps may need to be taken after examining the workflow output`
+                body += ` from the above workflow run. :rotating_light:`
+              }
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                body,
+                comment_id: updateComment.id,
+              })
+            } else {
+              console.log('No matching comments found:', JSON.stringify(comments, null, 2))
+            }
diff --git a/.gitignore b/.gitignore
@@ -15,6 +15,7 @@
 !/bin/
 !/CHANGELOG*
 !/CODE_OF_CONDUCT.md
+!/CONTRIBUTING.md
 !/docs/
 !/lib/
 !/LICENSE*

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "11.0.1"
+  ".": "12.0.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,59 @@
 # Changelog
 
+## [12.0.0](https://github.com/npm/make-fetch-happen/compare/v11.1.1...v12.0.0) (2023-07-27)
+
+### ⚠️ BREAKING CHANGES
+
+* support for node 14 has been removed
+* this changes the underlying http agents to those provided by `@npmcli/agent`.  Backwards compatibility should be fully implemented but due to the scope of this change it was made a breaking change out of an abundance of caution.
+
+### Features
+
+* [`7c25367`](https://github.com/npm/make-fetch-happen/commit/7c25367d95c5a0853b4b1e93c13456ac1cfc493d) [#255](https://github.com/npm/make-fetch-happen/pull/255) move to @npmcli/agent (@wraithgar)
+
+### Bug Fixes
+
+* [`3059b28`](https://github.com/npm/make-fetch-happen/commit/3059b286be9884f0d2f83f5b57314e924c07c57d) [#259](https://github.com/npm/make-fetch-happen/pull/259) drop node14 support (#259) (@wraithgar)
+
+### Documentation
+
+* [`efd1e2f`](https://github.com/npm/make-fetch-happen/commit/efd1e2f02a38e7f39fe291503546f1be92ad0fa7) [#255](https://github.com/npm/make-fetch-happen/pull/255) update readme (@wraithgar)
+
+### Dependencies
+
+* [`5318d23`](https://github.com/npm/make-fetch-happen/commit/5318d239280b951479877badd81868411d71f19f) [#253](https://github.com/npm/make-fetch-happen/pull/253) bump minipass from 5.0.0 to 7.0.2 (#253)
+* [`5493550`](https://github.com/npm/make-fetch-happen/commit/5493550d841cc2b182deae6717c010d9fb445002) [#255](https://github.com/npm/make-fetch-happen/pull/255) remove lru-cache
+* [`193b901`](https://github.com/npm/make-fetch-happen/commit/193b901f69adb8497f932beaeb60bff1fe0a94b5) [#255](https://github.com/npm/make-fetch-happen/pull/255) remove socks-proxy-agent
+* [`fc35622`](https://github.com/npm/make-fetch-happen/commit/fc356228b1127e65f3c5c27f4e2b1dc26167298a) [#255](https://github.com/npm/make-fetch-happen/pull/255) remove agentkeepalive
+* [`e78fcdf`](https://github.com/npm/make-fetch-happen/commit/e78fcdf507938806dffcd4ce82c0f9373e589b29) [#255](https://github.com/npm/make-fetch-happen/pull/255) remove https-proxy-agent
+* [`a4089a0`](https://github.com/npm/make-fetch-happen/commit/a4089a0946476d5ea2624130d0fcf6da5b99d730) [#255](https://github.com/npm/make-fetch-happen/pull/255) remove http-proxy-agent
+* [`92c3226`](https://github.com/npm/make-fetch-happen/commit/92c32269646e531e86a0b1b7efe96596506ef563) [#255](https://github.com/npm/make-fetch-happen/pull/255) add @npmcli/agent
+
+## [11.1.1](https://github.com/npm/make-fetch-happen/compare/v11.1.0...v11.1.1) (2023-04-27)
+
+### Dependencies
+
+* [`b04e3c2`](https://github.com/npm/make-fetch-happen/commit/b04e3c279e8dc6b090f3e2bfbd854fd0af3e9195) [#220](https://github.com/npm/make-fetch-happen/pull/220) bump minipass from 4.2.7 to 5.0.0 (#220)
+
+## [11.1.0](https://github.com/npm/make-fetch-happen/compare/v11.0.3...v11.1.0) (2023-04-13)
+
+### Features
+
+* [`cca9da0`](https://github.com/npm/make-fetch-happen/commit/cca9da0af76b5900a9c480967769df91bca2570d) [#225](https://github.com/npm/make-fetch-happen/pull/225) add support for caching additional headers (#225) (@nlf)
+
+## [11.0.3](https://github.com/npm/make-fetch-happen/compare/v11.0.2...v11.0.3) (2023-02-02)
+
+### Dependencies
+
+* [`fb01043`](https://github.com/npm/make-fetch-happen/commit/fb0104335a2101e4f21721457e80b59a8300017e) [#212](https://github.com/npm/make-fetch-happen/pull/212) remove unused dependencies (#212)
+* [`5807162`](https://github.com/npm/make-fetch-happen/commit/58071621daa6d7e1cb28a61fc06df531baf440f3) [#210](https://github.com/npm/make-fetch-happen/pull/210) `http-cache-semantics@4.1.1` (#210)
+
+## [11.0.2](https://github.com/npm/make-fetch-happen/compare/v11.0.1...v11.0.2) (2022-12-07)
+
+### Dependencies
+
+* [`77018ff`](https://github.com/npm/make-fetch-happen/commit/77018ff5c7ceeeda92e7d62435c4a6214e966a99) [#194](https://github.com/npm/make-fetch-happen/pull/194) bump minipass from 3.3.6 to 4.0.0
+
 ## [11.0.1](https://github.com/npm/make-fetch-happen/compare/v11.0.0...v11.0.1) (2022-10-17)
 
 ### Dependencies

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+<!-- This file is automatically added by @npmcli/template-oss. Do not edit. -->
+
+# Contributing
+
+## Code of Conduct
+
+All interactions in the **npm** organization on GitHub are considered to be covered by our standard [Code of Conduct](https://docs.npmjs.com/policies/conduct).
+
+## Reporting Bugs
+
+Before submitting a new bug report please search for an existing or similar report.
+
+Use one of our existing issue templates if you believe you've come across a unique problem.
+
+Duplicate issues, or issues that don't use one of our templates may get closed without a response.
+
+## Pull Request Conventions
+
+### Commits
+
+We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+When opening a pull request please be sure that either the pull request title, or each commit in the pull request, has one of the following prefixes:
+
+ - `feat`: For when introducing a new feature.  The result will be a new semver minor version of the package when it is next published.
+ - `fix`: For bug fixes. The result will be a new semver patch version of the package when it is next published.
+ - `docs`: For documentation updates.  The result will be a new semver patch version of the package when it is next published.
+ - `chore`: For changes that do not affect the published module.  Often these are changes to tests.  The result will be *no* change to the version of the package when it is next published (as the commit does not affect the published version).
+
+### Test Coverage
+
+Pull requests made against this repo will run `npm test` automatically.  Please make sure tests pass locally before submitting a PR.
+
+Every new feature or bug fix should come with a corresponding test or tests that validate the solutions. Testing also reports on code coverage and will fail if code coverage drops.
+
+### Linting
+
+Linting is also done automatically once tests pass.  `npm run lintfix` will fix most linting errors automatically.
+
+Please make sure linting passes before submitting a PR.
+
+## What _not_ to contribute?
+
+### Dependencies
+
+It should be noted that our team does not accept third-party dependency updates/PRs.  If you submit a PR trying to update our dependencies we will close it with or without a reference to these contribution guidelines.
+
+### Tools/Automation
+
+Our core team is responsible for the maintenance of the tooling/automation in this project and we ask contributors to not make changes to these when contributing (e.g. `.github/*`, `.eslintrc.json`, `.licensee.json`).  Most of those files also have a header at the top to remind folks they are automatically generated.  Pull requests that alter these will not be accepted.
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ pooling, proxies, retries, [and more](#features)!
   * [`make-fetch-happen` options](#extra-options)
     * [`opts.cachePath`](#opts-cache-path)
     * [`opts.cache`](#opts-cache)
+    * [`opts.cacheAdditionalHeaders`](#opts-cache-additional-headers)
     * [`opts.proxy`](#opts-proxy)
     * [`opts.noProxy`](#opts-no-proxy)
     * [`opts.ca, opts.cert, opts.key`](#https-opts)
@@ -61,26 +62,12 @@ fetch('https://registry.npmjs.org/make-fetch-happen').then(res => {
 * Quite fast, really
 * Automatic HTTP-semantics-aware request retries
 * Cache-fallback automatic "offline mode"
-* Proxy support (http, https, socks, socks4, socks5)
 * Built-in request caching following full HTTP caching rules (`Cache-Control`, `ETag`, `304`s, cache fallback on error, etc).
 * Node.js Stream support
 * Transparent gzip and deflate support
 * [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) support
-* Literally punches nazis
-* Built in DNS cache
-* (PENDING) Range request caching and resuming
-
-### Contributing
-
-The make-fetch-happen team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! The [Contributor Guide](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) outlines the process for community interaction and contribution. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.
-
-All participants and maintainers in this project are expected to follow the [npm Code of Conduct](https://www.npmjs.com/policies/conduct), and just generally be excellent to each other.
-
-Please refer to the [Changelog](CHANGELOG.md) for project history details, too.
-
-Happy hacking!
-
-### API
+* Proxy support (http, https, socks, socks4, socks5. via [`@npmcli/agent`](https://npm.im/@npmcli/agent))
+* DNS cache (via ([`@npmcli/agent`](https://npm.im/@npmcli/agent))
 
 #### <a name="fetch"></a> `> fetch(uriOrRequest, [opts]) -> Promise<Response>`
 
@@ -125,11 +112,6 @@ The following options for `minipass-fetch` are used as-is:
 These other options are modified or augmented by make-fetch-happen:
 
 * headers - Default `User-Agent` set to make-fetch happen. `Connection` is set to `keep-alive` or `close` automatically depending on `opts.agent`.
-* agent
-  * If agent is null, an http or https Agent will be automatically used. By default, these will be `http.globalAgent` and `https.globalAgent`.
-  * If [`opts.proxy`](#opts-proxy) is provided and `opts.agent` is null, the agent will be set to an appropriate proxy-handling agent.
-  * If `opts.agent` is an object, it will be used as the request-pooling agent argument for this request.
-  * If `opts.agent` is `false`, it will be passed as-is to the underlying request library. This causes a new Agent to be spawned for every request.
 
 For more details, see [the documentation for `minipass-fetch` itself](https://github.com/npm/minipass-fetch#options).
 
@@ -139,6 +121,7 @@ make-fetch-happen augments the `minipass-fetch` API with additional features ava
 
 * [`opts.cachePath`](#opts-cache-path) - Cache target to read/write
 * [`opts.cache`](#opts-cache) - `fetch` cache mode. Controls cache *behavior*.
+* [`opts.cacheAdditionalHeaders`](#opts-cache-additional-headers) - Store additional headers in the cache
 * [`opts.proxy`](#opts-proxy) - Proxy agent
 * [`opts.noProxy`](#opts-no-proxy) - Domain segments to disable proxying for.
 * [`opts.ca, opts.cert, opts.key, opts.strictSSL`](#https-opts)
@@ -148,6 +131,7 @@ make-fetch-happen augments the `minipass-fetch` API with additional features ava
 * [`opts.onRetry`](#opts-onretry) - a function called whenever a retry is attempted
 * [`opts.integrity`](#opts-integrity) - [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) metadata.
 * [`opts.dns`](#opts-dns) - DNS cache options
+* [`opts.agent`](#opts-agent) - http/https/proxy/socks agent options.  See [`@npmcli/agent`](https://npm.im/@npmcli/agent) for more info.
 
 #### <a name="opts-cache-path"></a> `> opts.cachePath`
 
@@ -219,6 +203,34 @@ fetch('https://registry.npmjs.org/make-fetch-happen', {
 })
 ```
 
+#### <a name="opts-cache-additional-headers"></a> `> opts.cacheAdditionalHeaders`
+
+The following headers are always stored in the cache when present:
+
+- `cache-control`
+- `content-encoding`
+- `content-language`
+- `content-type`
+- `date`
+- `etag`
+- `expires`
+- `last-modified`
+- `link`
+- `location`
+- `pragma`
+- `vary`
+
+This option allows a user to store additional custom headers in the cache.
+
+
+##### Example
+
+```javascript
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  cacheAdditionalHeaders: ['my-custom-header'],
+})
+```
+
 #### <a name="opts-proxy"></a> `> opts.proxy`
 
 A string or `new url.URL()`-d URI to proxy through. Different Proxy handlers will be
@@ -350,12 +362,3 @@ fetch('https://malicious-registry.org/make-fetch-happen/-/make-fetch-happen-1.0.
   integrity: 'sha1-o47j7zAYnedYFn1dF/fR9OV3z8Q='
 }) // Error: EINTEGRITY
 ```
-
-#### <a name="opts-dns"></a> `> opts.dns`
-
-An object that provides options for the built-in DNS cache. The following options are available:
-
-Note: Due to limitations in the current proxy agent implementation, users of proxies will not benefit from the DNS cache.
-
-* `ttl`: Milliseconds to keep cached DNS responses for. Defaults to `5 * 60 * 1000` (5 minutes)
-* `lookup`: A custom lookup function, see [`dns.lookup()`](https://nodejs.org/api/dns.html#dnslookuphostname-options-callback) for implementation details. Defaults to `require('dns').lookup`.
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,3 +1,13 @@
 <!-- This file is automatically added by @npmcli/template-oss. Do not edit. -->
 
-Please send vulnerability reports through [hackerone](https://hackerone.com/github).
+GitHub takes the security of our software products and services seriously, including the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub).
+
+If you believe you have found a security vulnerability in this GitHub-owned open source repository, you can report it to us in one of two ways. 
+
+If the vulnerability you have found is *not* [in scope for the GitHub Bug Bounty Program](https://bounty.github.com/#scope) or if you do not wish to be considered for a bounty reward, please report the issue to us directly through [opensource-security@github.com](mailto:opensource-security@github.com).
+
+If the vulnerability you have found is [in scope for the GitHub Bug Bounty Program](https://bounty.github.com/#scope) and you would like for your finding to be considered for a bounty reward, please submit the vulnerability to us through [HackerOne](https://hackerone.com/github) in order to be eligible to receive a bounty award.
+
+**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+Thanks for helping make GitHub safe for everyone.
diff --git a/lib/agent.js b/lib/agent.js
diff --git a/lib/cache/entry.js b/lib/cache/entry.js
@@ -1,5 +1,5 @@
 const { Request, Response } = require('minipass-fetch')
-const Minipass = require('minipass')
+const { Minipass } = require('minipass')
 const MinipassFlush = require('minipass-flush')
 const cacache = require('cacache')
 const url = require('url')
@@ -99,6 +99,12 @@ const getMetadata = (request, response, options) => {
     }
   }
 
+  for (const name of options.cacheAdditionalHeaders) {
+    if (response.headers.has(name)) {
+      metadata.resHeaders[name] = response.headers.get(name)
+    }
+  }
+
   return metadata
 }
 
@@ -331,6 +337,7 @@ class CacheEntry {
       // that reads from cacache and attach it to a new Response
       const body = new Minipass()
       const headers = { ...this.policy.responseHeaders() }
+
       const onResume = () => {
         const cacheStream = cacache.get.stream.byDigest(
           this.options.cachePath, this.entry.integrity, { memoize: this.options.memoize }
@@ -417,6 +424,24 @@ class CacheEntry {
         }
       }
 
+      for (const name of options.cacheAdditionalHeaders) {
+        const inMeta = hasOwnProperty(metadata.resHeaders, name)
+        const inEntry = hasOwnProperty(this.entry.metadata.resHeaders, name)
+        const inPolicy = hasOwnProperty(this.policy.response.headers, name)
+
+        // if the header is in the existing entry, but it is not in the metadata
+        // then we need to write it to the metadata as this will refresh the on-disk cache
+        if (!inMeta && inEntry) {
+          metadata.resHeaders[name] = this.entry.metadata.resHeaders[name]
+        }
+        // if the header is in the metadata, but not in the policy, then we need to set
+        // it in the policy so that it's included in the immediate response. future
+        // responses will load a new cache entry, so we don't need to change that
+        if (!inPolicy && inMeta) {
+          this.policy.response.headers[name] = metadata.resHeaders[name]
+        }
+      }
+
       try {
         await cacache.index.insert(options.cachePath, this.key, this.entry.integrity, {
           size: this.entry.size,

diff --git a/lib/dns.js b/lib/dns.js
diff --git a/lib/options.js b/lib/options.js
@@ -40,6 +40,8 @@ const configureOptions = (opts) => {
     }
   }
 
+  options.cacheAdditionalHeaders = options.cacheAdditionalHeaders || []
+
   // cacheManager is deprecated, but if it's set and
   // cachePath is not we should copy it to the new field
   if (options.cacheManager && !options.cachePath) {

diff --git a/lib/remote.js b/lib/remote.js
@@ -1,10 +1,10 @@
-const Minipass = require('minipass')
+const { Minipass } = require('minipass')
 const fetch = require('minipass-fetch')
 const promiseRetry = require('promise-retry')
 const ssri = require('ssri')
 
 const CachingMinipassPipeline = require('./pipeline.js')
-const getAgent = require('./agent.js')
+const { getAgent } = require('@npmcli/agent')
 const pkg = require('../package.json')
 
 const USER_AGENT = `${pkg.name}/${pkg.version} (+https://npm.im/${pkg.name})`
@@ -14,9 +14,15 @@ const RETRY_ERRORS = [
   'ECONNREFUSED', // remote host refused to open connection
   'EADDRINUSE', // failed to bind to a local port (proxy?)
   'ETIMEDOUT', // someone in the transaction is WAY TOO SLOW
-  'ERR_SOCKET_TIMEOUT', // same as above, but this one comes from agentkeepalive
+  // from @npmcli/agent
+  'ECONNECTIONTIMEOUT',
+  'EIDLETIMEOUT',
+  'ERESPONSETIMEOUT',
+  'ETRANSFERTIMEOUT',
   // Known codes we do NOT retry on:
   // ENOTFOUND (getaddrinfo failure. Either bad hostname, or offline)
+  // EINVALIDPROXY // invalid protocol from @npmcli/agent
+  // EINVALIDRESPONSE // invalid status code from @npmcli/agent
 ]
 
 const RETRY_TYPES = [

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "make-fetch-happen",
-  "version": "11.0.1",
+  "version": "12.0.0",
   "description": "Opinionated, caching, retrying fetch client",
   "main": "lib/index.js",
   "files": [
@@ -33,35 +33,28 @@
   "author": "GitHub Inc.",
   "license": "ISC",
   "dependencies": {
-    "agentkeepalive": "^4.2.1",
+    "@npmcli/agent": "^1.1.0",
     "cacache": "^17.0.0",
-    "http-cache-semantics": "^4.1.0",
-    "http-proxy-agent": "^5.0.0",
-    "https-proxy-agent": "^5.0.0",
+    "http-cache-semantics": "^4.1.1",
     "is-lambda": "^1.0.1",
-    "lru-cache": "^7.7.1",
-    "minipass": "^3.1.6",
-    "minipass-collect": "^1.0.2",
+    "minipass": "^7.0.2",
     "minipass-fetch": "^3.0.0",
     "minipass-flush": "^1.0.5",
     "minipass-pipeline": "^1.2.4",
     "negotiator": "^0.6.3",
     "promise-retry": "^2.0.1",
-    "socks-proxy-agent": "^7.0.0",
     "ssri": "^10.0.0"
   },
   "devDependencies": {
     "@npmcli/eslint-config": "^4.0.0",
-    "@npmcli/template-oss": "4.5.1",
-    "mkdirp": "^1.0.4",
+    "@npmcli/template-oss": "4.18.0",
     "nock": "^13.2.4",
-    "rimraf": "^3.0.2",
     "safe-buffer": "^5.2.1",
     "standard-version": "^9.3.2",
     "tap": "^16.0.0"
   },
   "engines": {
-    "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
+    "node": "^16.13.0 || >=18.0.0"
   },
   "tap": {
     "color": 1,
@@ -75,6 +68,13 @@
   },
   "templateOSS": {
     "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
-    "version": "4.5.1"
+    "ciVersions": [
+      "16.13.0",
+      "16.x",
+      "18.0.0",
+      "18.x"
+    ],
+    "version": "4.18.0",
+    "publish": "true"
   }
 }
diff --git a/test/agent.js b/test/agent.js
diff --git a/test/cache.js b/test/cache.js
@@ -166,6 +166,59 @@ t.test('no match, fetches and replies even when no content-length', async (t) =>
   }, 'resHeaders has only the relevant headers for caching')
 })
 
+t.test('no matches, can store additional headers', async (t) => {
+  const srv = nock(HOST)
+    .get('/test')
+    .reply(200, CONTENT, {
+      ...getHeaders(CONTENT),
+      'x-foo': 'something',
+    })
+
+  const reqKey = cacheKey(new Request(`${HOST}/test`))
+  const dir = t.testdir()
+  const res = await fetch(`${HOST}/test`, { cachePath: dir, cacheAdditionalHeaders: ['x-foo'] })
+  t.ok(srv.isDone(), 'req is fulfilled')
+  t.equal(res.status, 200)
+  t.equal(res.url, `${HOST}/test`, 'has a url property matching the request')
+  t.equal(res.headers.get('cache-control'), 'max-age=300', 'kept cache-control')
+  t.equal(res.headers.get('content-type'), 'application/octet-stream', 'kept content-stream')
+  t.equal(res.headers.get('content-length'), `${CONTENT.length}`, 'kept content-length')
+  t.equal(res.headers.get('x-local-cache'), encodeURIComponent(dir), 'has cache dir')
+  t.equal(res.headers.get('x-local-cache-key'), encodeURIComponent(reqKey), 'has cache key')
+  t.equal(res.headers.get('x-local-cache-mode'), 'stream', 'should stream store')
+  t.equal(res.headers.get('x-local-cache-status'), 'miss', 'identifies as cache miss')
+  t.ok(res.headers.has('x-local-cache-time'), 'has cache time')
+  t.equal(res.headers.get('x-foo'), 'something', 'original response has all headers')
+  t.notOk(res.headers.has('x-local-cache-hash'), 'hash header is only set when served from cache')
+
+  const dirBeforeRead = await readdir(dir)
+  t.same(dirBeforeRead, [], 'should not write to the cache yet')
+
+  const buf = await res.buffer()
+  t.same(buf, CONTENT, 'got the correct content')
+  const dirAfterRead = await readdir(dir)
+  // note, this does not make any assumptions about what directories
+  // are in the cache, only that there is something there. this is so
+  // our tests do not have to change if cacache version bumps its content
+  // and/or index directories
+  t.ok(dirAfterRead.length > 0, 'cache has data after consuming the body')
+
+  // compact with a function that always returns false
+  // results in a list of all entries in the index
+  const entries = await cacache.index.compact(dir, reqKey, () => false)
+  t.equal(entries.length, 1, 'should only have one entry')
+  const entry = entries[0]
+  t.equal(entry.integrity, INTEGRITY, 'integrity matches')
+  t.equal(entry.metadata.url, `${HOST}/test`, 'url matches')
+  t.same(entry.metadata.reqHeaders, {}, 'metadata has no request headers as none are relevant')
+  t.same(entry.metadata.resHeaders, {
+    'content-type': res.headers.get('content-type'),
+    'cache-control': res.headers.get('cache-control'),
+    date: res.headers.get('date'),
+    'x-foo': 'something',
+  }, 'resHeaders has the relevant headers for caching and our additional header')
+})
+
 t.test('no matches, cache mode only-if-cached rejects', async (t) => {
   const dir = t.testdir()
 
@@ -204,6 +257,48 @@ t.test('cache hit, no revalidation', async (t) => {
   t.ok(res.headers.has('x-local-cache-time'))
 })
 
+t.test('cache hit, no revalidation, responds with additional headers', async (t) => {
+  const srv = nock(HOST)
+    .get('/test')
+    .reply(200, CONTENT, {
+      ...getHeaders(CONTENT),
+      'x-foo': 'something',
+    })
+
+  const dir = t.testdir()
+  const reqKey = cacheKey(new Request(`${HOST}/test`))
+  const cacheRes = await fetch(`${HOST}/test`, {
+    cachePath: dir,
+    retry: false,
+    cacheAdditionalHeaders: ['x-foo'],
+  })
+  await cacheRes.buffer() // drain it immediately so it stores to the cache
+  t.ok(srv.isDone(), 'req has fulfilled')
+
+  const res = await fetch(`${HOST}/test`, {
+    cachePath: dir,
+    retry: false,
+    cacheAdditionalHeaders: ['x-foo'],
+  })
+  const buf = await res.buffer()
+  t.same(buf, CONTENT, 'got the right content')
+  t.equal(res.status, 200, 'got a 200')
+  t.equal(res.url, `${HOST}/test`, 'has the right url')
+  t.equal(res.headers.get('cache-control'), 'max-age=300', 'kept cache-control')
+  t.equal(res.headers.get('content-type'), 'application/octet-stream', 'kept content-type')
+  t.equal(res.headers.get('content-length'), `${CONTENT.length}`, 'kept content-length')
+  t.equal(res.headers.get('x-foo'), 'something', 'kept the additional x-foo header')
+  t.equal(res.headers.get('x-local-cache'), encodeURIComponent(dir), 'encoded the path')
+  t.equal(res.headers.get('x-local-cache-status'), 'hit', 'got a cache hit')
+  t.equal(res.headers.get('x-local-cache-key'), encodeURIComponent(reqKey),
+    'got the right cache key')
+  t.equal(res.headers.get('x-local-cache-mode'), 'stream', 'should stream read')
+  t.equal(res.headers.get('x-local-cache-hash'), encodeURIComponent(INTEGRITY),
+    'has the right hash')
+  // just make sure x-local-cache-time is set, no need to assert its value
+  t.ok(res.headers.has('x-local-cache-time'))
+})
+
 t.test('cache hit, cache mode no-cache 304', async (t) => {
   const srv = nock(HOST)
     .get('/test')
@@ -1293,6 +1388,7 @@ t.test('revalidate updates headers in the metadata with new values', async (t) =
       etag: '"beef"',
       date: new Date().toISOString(),
       'content-type': 'text/plain',
+      'x-foo': 'something',
     },
   }
 
@@ -1309,6 +1405,8 @@ t.test('revalidate updates headers in the metadata with new values', async (t) =
     'initial entry does not have cache-control')
   t.equal(beforeEntries[0].metadata.resHeaders['content-type'], 'text/plain',
     'initial entry has a content-type')
+  t.equal(beforeEntries[0].metadata.resHeaders['x-foo'], 'something',
+    'initial entry has x-foo')
 
   // NOTE: the body must be undefined, not null, otherwise nock
   // will add an implicit content-type of application/json
@@ -1320,14 +1418,22 @@ t.test('revalidate updates headers in the metadata with new values', async (t) =
       date: new Date().toISOString(),
       etag: '"beef"',
       'cache-control': 'max-age=300',
+      'x-bar': 'anything',
     })
 
-  const revalidateRes = await fetch(`${HOST}/test`, { cachePath: dir })
+  const revalidateRes = await fetch(`${HOST}/test`, {
+    cachePath: dir,
+    cacheAdditionalHeaders: ['x-foo', 'x-bar'],
+  })
   t.equal(revalidateRes.status, 200, 'got a success status')
   t.equal(revalidateRes.headers.get('x-local-cache-status'), 'revalidated',
     'identifies as revalidated')
   t.equal(revalidateRes.headers.get('content-type'), 'text/plain',
     'got the content-type in the response')
+  t.equal(revalidateRes.headers.get('x-foo'), 'something',
+    'got the cached x-foo in the response')
+  t.equal(revalidateRes.headers.get('x-bar'), 'anything',
+    'got the new x-bar header')
   await revalidateRes.buffer()
   t.ok(srv.isDone())
 
@@ -1338,6 +1444,10 @@ t.test('revalidate updates headers in the metadata with new values', async (t) =
     'now has cache-control header')
   t.equal(afterEntries[0].metadata.resHeaders['content-type'], 'text/plain',
     'new index entry kept the content-type')
+  t.equal(afterEntries[0].metadata.resHeaders['x-foo'], 'something',
+    'kept the x-foo header')
+  t.equal(afterEntries[0].metadata.resHeaders['x-bar'], 'anything',
+    'stored the new x-bar header')
   t.notOk(afterEntries[0].metadata.reqHeaders['user-agent'],
     'no longer has a user-agent in reqHeaders')
 })

diff --git a/test/dns.js b/test/dns.js
diff --git a/test/fetch.js b/test/fetch.js
@@ -1,6 +1,6 @@
 'use strict'
 
-const Minipass = require('minipass')
+const { Minipass } = require('minipass')
 const t = require('tap')
 const nock = require('nock')
 const fetch = require('../lib/index.js')

diff --git a/test/lambda-agent.js b/test/lambda-agent.js
diff --git a/test/options.js b/test/options.js
@@ -14,6 +14,7 @@ test('configure options', async (t) => {
       cache: 'default',
       rejectUnauthorized: true,
       dns: defaultDns,
+      cacheAdditionalHeaders: [],
     }
     t.same(opts, expectedObject, 'should return default opts')
   })
@@ -26,6 +27,7 @@ test('configure options', async (t) => {
       cache: 'default',
       rejectUnauthorized: true,
       dns: defaultDns,
+      cacheAdditionalHeaders: [],
     }
     t.same(opts, expectedObject, 'should return default opts')
   })
@@ -39,6 +41,7 @@ test('configure options', async (t) => {
       cache: 'default',
       rejectUnauthorized: true,
       dns: defaultDns,
+      cacheAdditionalHeaders: [],
     }
     t.same(opts, expectedObject, 'should return upper cased method')
   })
@@ -51,6 +54,7 @@ test('configure options', async (t) => {
       cache: 'default',
       rejectUnauthorized: true,
       dns: defaultDns,
+      cacheAdditionalHeaders: [],
     }
     t.same(trueOpts, trueExpectedObject, 'should return default opts and copy strictSSL')
 
@@ -61,6 +65,7 @@ test('configure options', async (t) => {
       cache: 'default',
       rejectUnauthorized: false,
       dns: defaultDns,
+      cacheAdditionalHeaders: [],
     }
     t.same(falseOpts, falseExpectedObject, 'should return default opts and copy strictSSL')
 
@@ -87,6 +92,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should return default retry property')
     })
@@ -100,6 +106,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: { ...defaultDns, ttl: 100 },
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should extend default dns with custom ttl')
     })
@@ -114,6 +121,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: { ...defaultDns, lookup },
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should extend default dns with custom lookup')
     })
@@ -129,6 +137,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should return default retry property')
     })
@@ -142,6 +151,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should return default retry property')
     })
@@ -155,6 +165,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should set retry value, if number')
     })
@@ -168,6 +179,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should set retry value')
     })
@@ -181,6 +193,7 @@ test('configure options', async (t) => {
         cache: 'default',
         rejectUnauthorized: true,
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should return default retry property')
     })
@@ -196,6 +209,7 @@ test('configure options', async (t) => {
         retry: { retries: 0 },
         cache: 'default',
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should set the default cache')
     })
@@ -209,6 +223,7 @@ test('configure options', async (t) => {
         retry: { retries: 0 },
         cache: 'something',
         dns: defaultDns,
+        cacheAdditionalHeaders: [],
       }
       t.same(opts, expectedObject, 'should keep the provided cache')
     })
@@ -222,6 +237,7 @@ test('configure options', async (t) => {
         retry: { retries: 0 },
         cache: 'default',
         cachePath: './foo',
+        cacheAdditionalHeaders: [],
       }
       t.match(opts, expectedObject)
     })
@@ -236,6 +252,7 @@ test('configure options', async (t) => {
         cache: 'default',
         cachePath: './foo',
         cacheManager: './foo',
+        cacheAdditionalHeaders: [],
       }
       t.match(opts, expectedObject)
     })
@@ -248,6 +265,7 @@ test('configure options', async (t) => {
         rejectUnauthorized: true,
         retry: { retries: 0 },
         cache: 'no-store',
+        cacheAdditionalHeaders: [],
       }
       t.match(opts, expectedObject)
     })