fix(security): refuse to overwrite an existing release draft

Expose local draft persistence with an explicit repository path and
exclusive file creation. Prepare data before changing branches and check
for an existing draft again after checkout.

Author: RafaelGSS

docs/git-node.md

@@ -506,7 +506,9 @@ the command creates a tracking branch from that ref. Fetch first when remote
 state may have changed.
 
 Security release commits reject unrelated staged changes before staging their
-own files. Commit or unstage those changes before continuing.
+own files. Commit or unstage those changes before continuing. `--start` refuses
+to overwrite an existing draft, including one found after switching branches.
+Use `--sync`, `--add-report`, or `--remove-report` to update that release.
 
 #### Preparing release data without the CLI
 
@@ -538,6 +540,15 @@ metadata is listed for follow-up; a draft with no reports can still contain
 dependency updates. These checks prepare a draft, not a final-release approval.
 The caller owns selection, human review, persistence, and publication.
 
+After reviewing the prepared data, local tools can use
+`writeSecurityReleaseDraft(directory, release)` from
+`lib/security-release/draft.js`. The directory is an explicit security-release
+repository path. The helper validates the draft and creates
+`security-release/next-security-release/vulnerabilities.json` with an exclusive
+write, so an existing file cannot be overwritten. It does not change Git state
+or publish anything. Review and authorization belong to the calling tool; the
+CLI retains its directory and file-write confirmations.
+
 ### `git node security --apply-patches`
 
 This command fetches the list of reports and the list of PRs labelled for the

lib/prepare_security.js

@@ -1,8 +1,12 @@
-import fs from 'node:fs';
 import path from 'node:path';
 import auth from './auth.js';
 import Request from './request.js';
 import { parsePRFromURL } from './links.js';
+import {
+  assertNewSecurityRelease,
+  getSecurityReleaseDraftPath,
+  writeSecurityReleaseDraft
+} from './security-release/draft.js';
 import {
   buildIncludedTriagedReport,
   getReportPRURL,
@@ -14,7 +18,6 @@ import {
 
 import {
   NEXT_SECURITY_RELEASE_BRANCH,
-  NEXT_SECURITY_RELEASE_FOLDER,
   checkoutOnSecurityReleaseBranch,
   commitAndPushVulnerabilitiesJSON,
   validateDate,
@@ -23,7 +26,6 @@ import {
   getReportSeverity,
   pickReport,
   confirmSecurityStep,
-  writeSecurityFile,
   SecurityRelease
 } from './security-release/security-release.js';
 
@@ -100,6 +102,7 @@ export default class PrepareSecurityRelease extends SecurityRelease {
   title = 'Next Security Release';
 
   async start() {
+    assertNewSecurityRelease(process.cwd());
     const credentials = await auth({
       github: true,
       h1: true
@@ -200,17 +203,22 @@ export default class PrepareSecurityRelease extends SecurityRelease {
     reportSelectionMode = 'review',
     candidates
   ) {
-    // checkout on the next-security-release branch
-    await checkoutOnSecurityReleaseBranch(this.cli, this.repository);
+    assertNewSecurityRelease(process.cwd());
 
     // choose the reports to include in the security release
     const reports = reportSelectionMode === 'include-all'
       ? await this.includeAllTriagedReports(excludedReports, candidates)
       : await this.chooseReports(excludedReports, candidates);
     const deps = await this.getDependencyUpdates();
+    const { release } = prepareSecurityRelease({ releaseDate, reports, dependencies: deps });
 
-    // create the vulnerabilities.json file in the security-release repo
-    const filePath = await this.createVulnerabilitiesJSON(reports, deps, releaseDate);
+    // Prepare all data before changing Git state. An existing branch may contain
+    // a draft that was not present on the branch where this command started.
+    await checkoutOnSecurityReleaseBranch(this.cli, this.repository);
+    assertNewSecurityRelease(process.cwd());
+
+    const filePath = await this.createVulnerabilitiesJSON(
+      release.reports, release.dependencies, release.releaseDate);
 
     // review the vulnerabilities.json file
     const review = await this.promptReviewVulnerabilitiesJSON();
@@ -444,26 +452,23 @@ export default class PrepareSecurityRelease extends SecurityRelease {
   }
 
   async createVulnerabilitiesJSON(reports, dependencies, releaseDate) {
-    this.cli.startSpinner('Creating vulnerabilities.json...');
     const { release } = prepareSecurityRelease({ releaseDate, reports, dependencies });
-    const fileContent = JSON.stringify(release, null, 2) + '\n';
-
-    const folderPath = path.resolve(NEXT_SECURITY_RELEASE_FOLDER);
-    const fullPath = path.join(folderPath, 'vulnerabilities.json');
+    const directory = process.cwd();
+    const fullPath = getSecurityReleaseDraftPath(directory);
+    assertNewSecurityRelease(directory);
     await confirmSecurityStep(
       this.cli,
-      `create directory \`${folderPath}\``,
+      `create directory \`${path.dirname(fullPath)}\``,
       'This creates the security release folder if it does not already exist.'
     );
-    await fs.promises.mkdir(folderPath, { recursive: true });
-    await writeSecurityFile(
+    await confirmSecurityStep(
       this.cli,
-      fullPath,
-      fileContent,
+      `write \`${fullPath}\``,
       'This creates vulnerabilities.json for the next security release.'
     );
+    this.cli.startSpinner('Creating vulnerabilities.json...');
+    writeSecurityReleaseDraft(directory, release);
     this.cli.stopSpinner(`Created ${fullPath}`);
-
     return fullPath;
   }
 

lib/security-release/draft.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { NEXT_SECURITY_RELEASE_FOLDER } from './security-release.js';
+import { prepareSecurityRelease } from './preparation.js';
+
+export function getSecurityReleaseDraftPath(directory) {
+  if (typeof directory !== 'string' || !directory.trim()) {
+    throw new Error('Security release repository directory is required');
+  }
+  return path.resolve(directory, NEXT_SECURITY_RELEASE_FOLDER, 'vulnerabilities.json');
+}
+
+export function assertNewSecurityRelease(directory) {
+  const file = getSecurityReleaseDraftPath(directory);
+  if (fs.existsSync(file)) {
+    throw new Error(
+      `Security release draft already exists: ${file}. ` +
+      'Use --sync, --add-report, or --remove-report to update the existing release.'
+    );
+  }
+}
+
+// Local persistence only. The caller handles review, Git, and publication.
+export function writeSecurityReleaseDraft(directory, draft) {
+  const { release } = prepareSecurityRelease(draft);
+  const file = getSecurityReleaseDraftPath(directory);
+  assertNewSecurityRelease(directory);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(release, null, 2) + '\n', { flag: 'wx' });
+  return file;
+}

test/unit/security_draft.test.js

@@ -0,0 +1,88 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  assertNewSecurityRelease,
+  getSecurityReleaseDraftPath,
+  writeSecurityReleaseDraft
+} from '../../lib/security-release/draft.js';
+import PrepareSecurityRelease from '../../lib/prepare_security.js';
+
+function directory(t) {
+  const previous = process.cwd();
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ncu-security-draft-'));
+  t.after(() => {
+    process.chdir(previous);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+describe('security release draft persistence', () => {
+  it('writes a normalized draft only in the explicit repository directory', (t) => {
+    const dir = directory(t);
+    const file = writeSecurityReleaseDraft(dir, {
+      releaseDate: '2026/10/06', reports: [], dependencies: {}
+    });
+    assert.strictEqual(file, path.join(dir,
+      'security-release', 'next-security-release', 'vulnerabilities.json'));
+    assert.deepStrictEqual(JSON.parse(fs.readFileSync(file, 'utf8')), {
+      releaseDate: '2026-10-06', reports: [], dependencies: {}
+    });
+    assert.deepStrictEqual(fs.readdirSync(dir), ['security-release']);
+  });
+
+  it('preserves an existing draft byte for byte', (t) => {
+    const dir = directory(t);
+    const draft = { releaseDate: 'TBD', reports: [] };
+    const file = writeSecurityReleaseDraft(dir, draft);
+    const before = fs.readFileSync(file);
+    assert.throws(() => assertNewSecurityRelease(dir), /draft already exists/);
+    assert.throws(() => writeSecurityReleaseDraft(dir, {
+      releaseDate: '2026-10-06', reports: []
+    }), /draft already exists/);
+    assert.deepStrictEqual(fs.readFileSync(file), before);
+  });
+
+  it('uses exclusive creation even if the file appears after preflight', (t) => {
+    const dir = directory(t);
+    const file = getSecurityReleaseDraftPath(dir);
+    const mkdir = fs.mkdirSync;
+    t.mock.method(fs, 'mkdirSync', (...args) => {
+      mkdir(...args);
+      fs.writeFileSync(file, 'Another session\n');
+    });
+    assert.throws(() => writeSecurityReleaseDraft(dir, {
+      releaseDate: 'TBD', reports: []
+    }), { code: 'EEXIST' });
+    assert.strictEqual(fs.readFileSync(file, 'utf8'), 'Another session\n');
+  });
+
+  it('validates inputs before creating directories', (t) => {
+    const dir = directory(t);
+    assert.throws(() => writeSecurityReleaseDraft(dir, {
+      releaseDate: '2026-02-30', reports: []
+    }), /Invalid release date/);
+    assert.deepStrictEqual(fs.readdirSync(dir), []);
+    assert.throws(() => getSecurityReleaseDraftPath(), /directory is required/);
+  });
+
+  it('does not write a draft when the file-write confirmation is declined', async(t) => {
+    const dir = directory(t);
+    const previous = process.cwd();
+    t.after(() => process.chdir(previous));
+    process.chdir(dir);
+    let prompts = 0;
+    const release = new PrepareSecurityRelease({
+      async prompt() {
+        return ++prompts === 1;
+      }
+    });
+    await assert.rejects(release.createVulnerabilitiesJSON([], {}, 'TBD'), /Aborted: write/);
+    assert.strictEqual(prompts, 2);
+    assert.deepStrictEqual(fs.readdirSync(dir), []);
+  });
+});

test/unit/security_git.test.js

@@ -5,6 +5,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 
+import PrepareSecurityRelease from '../../lib/prepare_security.js';
+import { writeSecurityReleaseDraft } from '../../lib/security-release/draft.js';
+
 import {
   checkoutOnSecurityReleaseBranch,
   commitAndPushVulnerabilitiesJSON,
@@ -118,4 +121,81 @@ describe('security release git state', { concurrency: false }, () => {
     assert.match(prompts[0], /git commit/);
     assert.strictEqual(git('write-tree'), index);
   });
+
+  it('rejects an existing draft before prompting or fetching reports', async(t) => {
+    const dir = repository(t);
+    const file = writeSecurityReleaseDraft(dir, { releaseDate: 'TBD', reports: [] });
+    const before = fs.readFileSync(file);
+    const release = new PrepareSecurityRelease({
+      prompt() { assert.fail('Existing releases must not start again'); }
+    });
+    await assert.rejects(release.start(), /draft already exists/);
+    assert.strictEqual(git('branch', '--show-current'), 'main');
+    assert.deepStrictEqual(fs.readFileSync(file), before);
+  });
+
+  it('preserves Git state if draft preparation fails', async(t) => {
+    repository(t);
+    const release = new PrepareSecurityRelease(cli);
+    release.chooseReports = async() => [];
+    release.getDependencyUpdates = async() => {
+      throw new Error('Preparation interrupted');
+    };
+    await assert.rejects(
+      release.startVulnerabilitiesJSONCreation('TBD', 'Release'), /Preparation interrupted/);
+    assert.strictEqual(git('branch', '--show-current'), 'main');
+    assert.strictEqual(git('branch', '--list', 'next-security-release'), '');
+    assert.strictEqual(git('status', '--porcelain'), '');
+  });
+
+  it('preserves a draft discovered on the existing release branch', async(t) => {
+    const dir = repository(t);
+    git('checkout', '-b', 'next-security-release');
+    const file = writeSecurityReleaseDraft(dir, { releaseDate: 'TBD', reports: [] });
+    const before = fs.readFileSync(file);
+    git('add', 'security-release');
+    git('commit', '-m', 'Existing release');
+    const head = git('rev-parse', 'HEAD');
+    git('checkout', 'main');
+    assert.ok(!fs.existsSync(file));
+
+    const release = new PrepareSecurityRelease(cli);
+    release.chooseReports = async() => [];
+    release.getDependencyUpdates = async() => ({});
+    await assert.rejects(
+      release.startVulnerabilitiesJSONCreation('2026-10-06', 'Release'), /draft already exists/);
+
+    assert.deepStrictEqual(fs.readFileSync(file), before);
+    assert.strictEqual(git('rev-parse', 'HEAD'), head);
+    assert.strictEqual(git('status', '--porcelain'), '');
+  });
+
+  it('creates a local draft without committing when publication is declined', async(t) => {
+    const dir = repository(t);
+    fs.writeFileSync('user-notes.txt', 'Staged user work\n');
+    git('add', 'user-notes.txt');
+    const index = git('write-tree');
+    const head = git('rev-parse', 'HEAD');
+    const release = new PrepareSecurityRelease({
+      ...cli, startSpinner() {}, stopSpinner() {}
+    });
+    release.chooseReports = async() => [];
+    release.getDependencyUpdates = async() => ({
+      undici: { affectedVersions: { '24.x': 'https://github.com/nodejs/node/pull/1' } }
+    });
+    release.promptReviewVulnerabilitiesJSON = async() => false;
+    release.createPullRequest = async() => assert.fail('Do not publish a local draft');
+
+    await release.startVulnerabilitiesJSONCreation('2026/10/06', 'Release');
+
+    const file = path.join(dir, 'security-release/next-security-release/vulnerabilities.json');
+    const draft = JSON.parse(fs.readFileSync(file, 'utf8'));
+    assert.strictEqual(draft.releaseDate, '2026-10-06');
+    assert.deepStrictEqual(draft.reports, []);
+    assert.strictEqual(draft.dependencies.undici.affectedVersions['24.x'],
+      'https://github.com/nodejs/node/pull/1');
+    assert.strictEqual(git('write-tree'), index);
+    assert.strictEqual(git('rev-parse', 'HEAD'), head);
+    assert.strictEqual(git('branch', '--show-current'), 'next-security-release');
+  });
 });