@omega.js/desktop 0.1.0

package/dist/test/suites/build/sign-windows-e2e.test.js

@@ -0,0 +1,302 @@
+// End-to-end tests for the Windows signer — the REAL signtool, against the REAL
+// EV token, on the box that has them ([#337](https://github.com/Omega-JS-Stack/omega/issues/337)).
+// sign-windows.test.js proves everything around signtool (command lines, retry
+// policy, env keys) anywhere; this file proves the part only the signing box can
+// answer: that a copy of where.exe comes back signed, that verify agrees, that
+// the event log has the trail, and that the `windows-sign` job's own command
+// entry lands a signed file in release/signed.
+//
+// Nothing here is mocked, so nothing here runs off Windows: every case gates on
+// the platform, on signtool being reachable, on a configured token, and on the
+// project signing HERE rather than in the cloud — a Windows dev box missing any
+// of those skips instead of failing. The one case that runs everywhere pins the
+// gate itself.
+//
+// On the box these drive the REAL EV token — a real signature, a real PIN
+// against a lockout counter — so they are an `--extended` lane, asked for
+// deliberately: `npx omega test --extended desktop:build/sign-windows-e2e`.
+// The bare lane skips them wherever it runs, the box included.
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const jetpack = require('fs-jetpack');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const signerPath = path.join(__dirname, '..', '..', '..', 'commands', 'sign-windows.js');
+const eventsPath = path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'sign-events.js');
+const signWindows = require(signerPath);
+const Manager = new (require(path.join(__dirname, '..', '..', '..', 'build.js')))();
+
+const NOT_WINDOWS  = 'Windows-only: signtool + the EV token live on the signing box';
+const NO_SIGNTOOL  = 'signtool is not reachable — install the Windows SDK / VS Build Tools, or set SIGNTOOL_PATH';
+const CLOUD        = 'strategy=cloud — the windows-sign job runs on hosted windows-latest, not against this box\'s token';
+const NOT_EXTENDED = 'extended tests skipped — pass --extended or set TEST_EXTENDED_MODE=true';
+
+// Why this run cannot sign for real, or null when it can. Pure: the platform,
+// the environment, whether signtool was found, and the configured signing
+// strategy all arrive as arguments, so the gate is provable on a Mac even
+// though nothing it guards is.
+function gateReason(platform, env, hasSigntool, strategy) {
+  if (platform !== 'win32') return NOT_WINDOWS;
+  if (!hasSigntool) return NO_SIGNTOOL;
+
+  // A cloud-strategy project sends its windows-sign job to a hosted
+  // windows-latest that calls a provider's CLI — signtool and the token here
+  // are not the path it takes, so these cases have nothing to prove. Decided
+  // BEFORE the token: a cloud box is not supposed to have one.
+  if (strategy === 'cloud') return CLOUD;
+
+  try {
+    signWindows.resolveSigntoolEnv(env);
+  } catch (e) {
+    return `no EV token configured on this box: ${e.message}`;
+  }
+
+  return null;
+}
+
+// Only ever called on Windows (the platform arm short-circuits first), where an
+// explicit SIGNTOOL_PATH is the binary itself and anything else has to be on PATH.
+function signtoolOnPath(env) {
+  env = env || process.env;
+  if (env.SIGNTOOL_PATH) return jetpack.exists(env.SIGNTOOL_PATH) === 'file';
+  return spawnSync('where', ['signtool'], { encoding: 'utf8' }).status === 0;
+}
+
+function currentGate() {
+  // Extended mode FIRST: these cases sign for real against the EV token, so the
+  // opt-in decides before anything about the box does. Read from the
+  // environment at call time, never a module const, so the gate case can take
+  // the variable away and prove this arm.
+  const extended = process.env.TEST_EXTENDED_MODE === 'true' || process.env.TEST_EXTENDED_MODE === '1';
+  if (!extended) return NOT_EXTENDED;
+
+  // The strategy comes from the project's own config — the same call the signer
+  // makes — and is only worth resolving where the rest of the gate has passed.
+  if (process.platform !== 'win32') return gateReason(process.platform, process.env, false, null);
+  return gateReason(process.platform, process.env, signtoolOnPath(process.env), Manager.getWindowsSignStrategy());
+}
+
+// The signer, loaded with its event log pointed inside this suite's scratch
+// tree. sign-events resolves that path ONCE, at require time, so the redirect
+// has to happen before the signer pulls it in — otherwise a test run appends to
+// the box's real signing trail and `runner monitor` shows test events as job
+// history. Suite cleanup restores the process-wide instances.
+function signerFor(ctx) {
+  if (ctx.state.signer) return ctx.state.signer;
+
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-sign-e2e-'));
+  ctx.state.scratch     = scratch;
+  ctx.state.logPath     = path.join(scratch, 'events', 'omega-signing.log');
+  ctx.state.origSignLog = process.env.OMEGA_SIGN_LOG;
+  process.env.OMEGA_SIGN_LOG = ctx.state.logPath;
+
+  delete require.cache[require.resolve(eventsPath)];
+  delete require.cache[require.resolve(signerPath)];
+  ctx.state.signer = require(signerPath);
+
+  return ctx.state.signer;
+}
+
+function readEvents(logPath) {
+  if (!jetpack.exists(logPath)) return [];
+  return String(jetpack.read(logPath) || '')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'sign-windows (e2e) — real signtool against the EV token [Windows only]',
+  cleanup: (ctx) => {
+    // Nothing was loaded when every case skipped — leave the environment alone.
+    if (!ctx.state.scratch) return;
+
+    if (ctx.state.origSignLog === undefined) delete process.env.OMEGA_SIGN_LOG;
+    else process.env.OMEGA_SIGN_LOG = ctx.state.origSignLog;
+
+    delete require.cache[require.resolve(eventsPath)];
+    delete require.cache[require.resolve(signerPath)];
+    require(signerPath);
+
+    jetpack.remove(ctx.state.scratch);
+  },
+  tests: [
+    {
+      name: 'the gate names why a run cannot sign — platform, signtool, the strategy, the token',
+      run: (ctx) => {
+        // The only case that runs everywhere: it asserts the skip reasons the
+        // rest of this suite reports, so a Mac run proves the gate rather than
+        // proving nothing.
+        const token = { WIN_EV_TOKEN_PATH: 'f'.repeat(40) };
+
+        ctx.expect(gateReason('darwin', token, true, 'self-hosted')).toBe(NOT_WINDOWS);
+        ctx.expect(gateReason('linux', token, true, 'self-hosted')).toBe(NOT_WINDOWS);
+
+        // On Windows the box still has to have the tool and the cert.
+        ctx.expect(gateReason('win32', token, false, 'self-hosted')).toBe(NO_SIGNTOOL);
+        ctx.expect(gateReason('win32', {}, true, 'self-hosted')).toMatch(/WIN_EV_TOKEN_PATH/);
+        ctx.expect(gateReason('win32', { WIN_EV_TOKEN_PATH: 'C:\\certs\\ev.pfx' }, true, 'self-hosted')).toMatch(/WIN_CSC_KEY_PASSWORD/);
+
+        // A cloud project signs on hosted windows-latest, so even a fully
+        // equipped box skips rather than proving a path CI never takes here —
+        // and a cloud box with no token at all says the same thing, since the
+        // strategy is decided before the token it was never meant to hold.
+        ctx.expect(gateReason('win32', token, true, 'cloud')).toBe(CLOUD);
+        ctx.expect(gateReason('win32', token, true, 'cloud')).toMatch(/cloud/);
+        ctx.expect(gateReason('win32', {}, true, 'cloud')).toBe(CLOUD);
+
+        // Windows + signtool + a configured token, signing on this box, is the
+        // one combination that runs — self-hosted and local both sign here.
+        ctx.expect(gateReason('win32', token, true, 'self-hosted')).toBeNull();
+        ctx.expect(gateReason('win32', token, true, 'local')).toBeNull();
+
+        // And before any of that: these five drive the REAL token, so the bare
+        // lane never reaches them. currentGate reads the opt-in at call time,
+        // which is what lets this case take it away and see the reason change.
+        const origExtended = process.env.TEST_EXTENDED_MODE;
+        try {
+          delete process.env.TEST_EXTENDED_MODE;
+          ctx.expect(currentGate()).toBe(NOT_EXTENDED);
+        } finally {
+          if (origExtended === undefined) delete process.env.TEST_EXTENDED_MODE;
+          else process.env.TEST_EXTENDED_MODE = origExtended;
+        }
+
+        // And every OTHER case in this file asks the gate before it does
+        // anything: on the box these drive the real token, so an ungated one
+        // would sign (or fail a PIN) whenever the lane runs.
+        const source = require('fs').readFileSync(__filename, 'utf8');
+        // Needles assembled so this case's own text is not one of their hits.
+        const cases  = source.split(`\n      ${'name'}: `).slice(1);
+        ctx.expect(cases.length).toBe(6);
+        for (const body of cases.slice(1)) {
+          if (!body.includes(`if (reason) ctx.${'skip'}(reason)`)) {
+            throw new Error(`an e2e case does not gate before it signs: ${body.slice(0, 120)}`);
+          }
+        }
+      },
+    },
+    {
+      name: 'signs an unsigned exe through the real signtool path',
+      timeout: 120000,
+      run: async (ctx) => {
+        const reason = currentGate();
+        if (reason) ctx.skip(reason);
+
+        const signer = signerFor(ctx);
+        const inDir  = path.join(ctx.state.scratch, 'in');
+        const outDir = path.join(ctx.state.scratch, 'out');
+        jetpack.dir(inDir);
+
+        // The same sample binary `--smoke` signs, from the signer's own helper.
+        const target = signer.copySampleExe(path.join(inDir, 'omega-sign-e2e.exe'));
+        const before = fs.readFileSync(target);
+
+        await signer.signWithSigntool([target], inDir, outDir);
+
+        const signedPath = path.join(outDir, 'omega-sign-e2e.exe');
+        ctx.expect(fs.existsSync(signedPath)).toBe(true);
+
+        // A signature is appended to the PE, so the output is bigger than the
+        // input and never byte-identical to it — the input is left untouched.
+        const after = fs.readFileSync(signedPath);
+        ctx.expect(after.length).toBeGreaterThan(before.length);
+        ctx.expect(after.equals(before)).toBe(false);
+        ctx.expect(fs.readFileSync(target).equals(before)).toBe(true);
+
+        ctx.state.unsignedPath = target;
+        ctx.state.signedPath   = signedPath;
+      },
+    },
+    {
+      name: 'signtool verify reports the signed copy as signed',
+      timeout: 60000,
+      run: async (ctx) => {
+        const reason = currentGate();
+        if (reason) ctx.skip(reason);
+
+        const result = await ctx.state.signer.verifyOnly([ctx.state.signedPath]);
+
+        ctx.expect(result.signed).toBe(1);
+        ctx.expect(result.unsigned).toBe(0);
+        ctx.expect(result.total).toBe(1);
+      },
+    },
+    {
+      name: 'signtool verify rejects the unsigned original',
+      timeout: 60000,
+      run: async (ctx) => {
+        const reason = currentGate();
+        if (reason) ctx.skip(reason);
+
+        // The other half of the proof: verify has to say no to the copy that was
+        // never signed, or a green verify means nothing.
+        const result = await ctx.state.signer.verifyOnly([ctx.state.unsignedPath]);
+
+        ctx.expect(result.signed).toBe(0);
+        ctx.expect(result.unsigned).toBe(1);
+      },
+    },
+    {
+      name: 'the sign-events log carries the attempt trail for that file',
+      run: (ctx) => {
+        const reason = currentGate();
+        if (reason) ctx.skip(reason);
+
+        const events = readEvents(ctx.state.logPath).filter((e) => e.file === 'omega-sign-e2e.exe');
+        const names  = events.map((e) => e.event);
+
+        ctx.expect(names).toContain('sign-start');
+        ctx.expect(names).toContain('sign-attempt');
+        ctx.expect(names).toContain('sign-done');
+        ctx.expect(names).not.toContain('sign-fail');
+
+        const attempts = events.filter((e) => e.event === 'sign-attempt');
+        ctx.expect(attempts[0].attempt).toBe(1);
+        ctx.expect(attempts[0].of).toBe(signWindows.SIGN_ATTEMPTS);
+
+        const start = events.find((e) => e.event === 'sign-start');
+        ctx.expect(start.mode).toBe(signWindows.resolveSigntoolEnv().useThumbprint ? 'thumbprint' : 'pfx');
+        ctx.expect(typeof start.ts).toBe('string');
+      },
+    },
+    {
+      name: 'one windows-sign job end to end: --in release --out release/signed',
+      timeout: 180000,
+      run: async (ctx) => {
+        const reason = currentGate();
+        if (reason) ctx.skip(reason);
+
+        // What the CI job runs is `npx omega sign-windows --in release --out
+        // release/signed` (src/defaults/.github/workflows/build.yml). The runner
+        // itself only hosts the job — there is no runner-side entry to call — so
+        // this drives the command module the CLI dispatches to, with the flags
+        // parsed the way the router hands them over.
+        const signer     = signerFor(ctx);
+        const releaseDir = path.join(ctx.state.scratch, 'job', 'release');
+        const signedDir  = path.join(releaseDir, 'signed');
+        jetpack.dir(releaseDir);
+        signer.copySampleExe(path.join(releaseDir, 'omega-runner-job.exe'));
+
+        await signer({ _: ['sign-windows'], in: releaseDir, out: signedDir });
+
+        const signedPath = path.join(signedDir, 'omega-runner-job.exe');
+        ctx.expect(fs.existsSync(signedPath)).toBe(true);
+
+        const result = await signer.verifyOnly([signedPath]);
+        ctx.expect(result.signed).toBe(1);
+
+        // The job's own bookends, which is what `runner monitor` renders per job.
+        const events    = readEvents(ctx.state.logPath);
+        const jobEvents = events.filter((e) => e.event === 'job-end');
+        ctx.expect(events.map((e) => e.event)).toContain('job-end');
+        ctx.expect(jobEvents[jobEvents.length - 1].ok).toBe(true);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/sign-windows.test.js

@@ -0,0 +1,313 @@
+// Build-layer tests for the Windows signer. signtool only exists on Windows, so
+// what we prove here is everything AROUND it: the exact command line each cert
+// mode produces, which env keys are read, and the retry policy on the sign call.
+
+const path = require('path');
+const fs = require('fs');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const signWindows = require(path.join(__dirname, '..', '..', '..', 'commands', 'sign-windows.js'));
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'sign-windows — signtool command construction + retry policy',
+  tests: [
+    {
+      name: 'this suite can never sign for real: every signWithRetry call injects its exec',
+      run: (ctx) => {
+        // The box runs this lane too. `signWithRetry` shells out to signtool by
+        // DEFAULT, so a case that forgets `exec:` would drive the real EV token
+        // (and its PIN retries) on the signing box — the deliberate signing
+        // lives in sign-windows-e2e.test.js, gated. This pins the invariant.
+        const fs = require('fs');
+        const source = fs.readFileSync(__filename, 'utf8');
+        // The needle is assembled so this case's own text is not one of its hits.
+        const calls = source.split(`signWithRetry${'('}`).slice(1);
+        ctx.expect(calls.length).toBeGreaterThan(0);
+        for (const call of calls) {
+          const body = call.slice(0, call.indexOf('});'));
+          if (!body.includes('exec:')) {
+            throw new Error(`a signWithRetry call in this suite does not inject exec — it would run the real signtool:\n${body.slice(0, 200)}`);
+          }
+        }
+      },
+    },
+    {
+      name: 'the box log is never written from a test run unless its home is a scratch',
+      run: async (ctx) => {
+        // `sign-windows` tees to `<runner home>/logs/runner.log`. On the box that
+        // IS the file to write; from a test process pointed at a real home it is
+        // the box's own record, and a test may not touch it — so the tee target
+        // resolves to null and nothing attaches.
+        const os = require('os');
+        const jetpack = require('fs-jetpack');
+        const signer = require(path.join(__dirname, '..', '..', '..', 'commands', 'sign-windows.js'));
+
+        const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-sign-home-'));
+        const realish = path.join(os.homedir(), `omega-runner-fake-${process.pid}`);
+        const origHome   = process.env.OMEGA_RUNNER_HOME;
+        const origMarker = process.env.OMEGA_TEST_RUNNER;
+        try {
+          // Pure half: the decision, with the home coming from the passed env and
+          // the "is this a test" answer coming from process.env, always.
+          process.env.OMEGA_TEST_RUNNER = '1';
+          ctx.expect(signer.boxLogTarget({ OMEGA_RUNNER_HOME: scratch }, 'darwin')).toBe(path.join(scratch, 'logs', 'runner.log'));
+          ctx.expect(signer.boxLogTarget({ OMEGA_RUNNER_HOME: realish }, 'darwin')).toBeNull();
+          ctx.expect(signer.boxLogTarget({}, 'darwin')).toBeNull();                    // no box home off Windows
+          delete process.env.OMEGA_TEST_RUNNER;
+          ctx.expect(signer.boxLogTarget({ OMEGA_RUNNER_HOME: realish }, 'darwin')).toBe(path.join(realish, 'logs', 'runner.log'));
+          process.env.OMEGA_TEST_MODE = 'true';                                        // the devkit/boot marker counts too
+          ctx.expect(signer.boxLogTarget({ OMEGA_RUNNER_HOME: realish }, 'darwin')).toBeNull();
+          delete process.env.OMEGA_TEST_MODE;
+
+          // And the command itself: pointed at a real home from a test run, it
+          // leaves no runner.log behind (it refuses --smoke off Windows).
+          process.env.OMEGA_TEST_RUNNER = '1';
+          process.env.OMEGA_RUNNER_HOME = realish;
+          let threw;
+          try {
+            await signer({ smoke: true });
+          } catch (e) { threw = e; }
+          ctx.expect(threw).toBeDefined();
+          ctx.expect(jetpack.exists(path.join(realish, 'logs', 'runner.log'))).toBe(false);
+        } finally {
+          if (origHome === undefined) delete process.env.OMEGA_RUNNER_HOME; else process.env.OMEGA_RUNNER_HOME = origHome;
+          if (origMarker === undefined) delete process.env.OMEGA_TEST_RUNNER; else process.env.OMEGA_TEST_RUNNER = origMarker;
+          jetpack.remove(scratch);
+          jetpack.remove(realish);
+        }
+      },
+    },
+    {
+      name: 'a 40-hex value is a thumbprint, a path is not',
+      run: (ctx) => {
+        ctx.expect(signWindows.isThumbprint('a'.repeat(40))).toBe(true);
+        ctx.expect(signWindows.isThumbprint(`AB CD ${'e'.repeat(36)}`)).toBe(true);   // signtool copy/paste spacing
+        ctx.expect(signWindows.isThumbprint('C:\\certs\\ev.pfx')).toBe(false);
+        ctx.expect(signWindows.isThumbprint('')).toBe(false);
+        ctx.expect(signWindows.isThumbprint(undefined)).toBe(false);
+      },
+    },
+    {
+      name: 'thumbprint mode signs with /sha1 and never puts the PIN on the command line',
+      run: (ctx) => {
+        const cmd = signWindows.buildSignCommand({
+          signtool:     'C:\\sdk\\signtool.exe',
+          tokenRef:     `AA BB ${'c'.repeat(36)}`,
+          password:     'hunter2',
+          timestampUrl: 'http://timestamp.sectigo.com',
+          outPath:      'C:\\out\\App Setup.exe',
+        });
+
+        ctx.expect(cmd).toBe(`"C:\\sdk\\signtool.exe" sign /sha1 AABB${'c'.repeat(36)}`
+          + ' /tr "http://timestamp.sectigo.com" /td sha256 /fd sha256 "C:\\out\\App Setup.exe" 2>&1');
+        // SafeNet holds the PIN in thumbprint mode — it must never reach argv.
+        ctx.expect(cmd).not.toContain('hunter2');
+      },
+    },
+    {
+      name: 'pfx mode signs with /f + /p',
+      run: (ctx) => {
+        const cmd = signWindows.buildSignCommand({
+          signtool:     'signtool',
+          tokenRef:     'C:\\certs\\ev.pfx',
+          password:     'hunter2',
+          timestampUrl: 'http://timestamp.digicert.com',
+          outPath:      'C:\\out\\App.exe',
+        });
+
+        ctx.expect(cmd).toBe('"signtool" sign /f "C:\\certs\\ev.pfx" /p "hunter2"'
+          + ' /tr "http://timestamp.digicert.com" /td sha256 /fd sha256 "C:\\out\\App.exe" 2>&1');
+      },
+    },
+    {
+      name: 'the sign command redirects stderr into stdout so the classifier sees signtool text',
+      run: (ctx) => {
+        // signtool writes its diagnosis to stderr; execute() surfaces whichever
+        // stream it captured. Without 2>&1 a wrong PIN can arrive as a bare exit
+        // code, which the classifier reads as transient and retries.
+        const cmd = signWindows.buildSignCommand({
+          signtool: 'signtool', tokenRef: 'f'.repeat(40), timestampUrl: 'http://ts', outPath: 'C:\\out\\App.exe',
+        });
+        ctx.expect(cmd.endsWith(' 2>&1')).toBe(true);
+        // verify parses its own output and stays untouched.
+        ctx.expect(signWindows.buildVerifyCommand({ signtool: 'signtool', outPath: 'C:\\out\\App.exe' }))
+          .not.toContain('2>&1');
+      },
+    },
+    {
+      name: 'verify is one shape, /pa, single-shot',
+      run: (ctx) => {
+        ctx.expect(signWindows.buildVerifyCommand({ signtool: 'signtool', outPath: 'C:\\out\\App.exe' }))
+          .toBe('"signtool" verify /pa "C:\\out\\App.exe"');
+      },
+    },
+    {
+      name: 'WIN_EV_TOKEN_PATH is the ONE cert-reference key — WIN_CSC_LINK is not read',
+      run: (ctx) => {
+        let threw;
+        try {
+          signWindows.resolveSigntoolEnv({ WIN_CSC_LINK: 'C:\\certs\\ev.pfx', WIN_CSC_KEY_PASSWORD: 'hunter2' });
+        } catch (e) { threw = e; }
+
+        ctx.expect(threw).toBeDefined();
+        ctx.expect(threw.message).toMatch(/WIN_EV_TOKEN_PATH/);
+        ctx.expect(threw.message).not.toMatch(/WIN_CSC_LINK/);
+      },
+    },
+    {
+      name: 'signtool path + timestamp url come from env with documented defaults',
+      run: (ctx) => {
+        const bare = signWindows.resolveSigntoolEnv({ WIN_EV_TOKEN_PATH: 'f'.repeat(40) });
+        ctx.expect(bare.signtool).toBe('signtool');
+        ctx.expect(bare.timestampUrl).toBe('http://timestamp.sectigo.com');
+        ctx.expect(bare.useThumbprint).toBe(true);
+
+        const set = signWindows.resolveSigntoolEnv({
+          WIN_EV_TOKEN_PATH: 'f'.repeat(40),
+          SIGNTOOL_PATH:     'C:\\sdk\\signtool.exe',
+          WIN_TIMESTAMP_URL: 'http://timestamp.digicert.com',
+        });
+        ctx.expect(set.signtool).toBe('C:\\sdk\\signtool.exe');
+        ctx.expect(set.timestampUrl).toBe('http://timestamp.digicert.com');
+      },
+    },
+    {
+      name: 'a .pfx without WIN_CSC_KEY_PASSWORD refuses; a thumbprint without one is fine',
+      run: (ctx) => {
+        let threw;
+        try {
+          signWindows.resolveSigntoolEnv({ WIN_EV_TOKEN_PATH: 'C:\\certs\\ev.pfx' });
+        } catch (e) { threw = e; }
+        ctx.expect(threw).toBeDefined();
+        ctx.expect(threw.message).toMatch(/WIN_CSC_KEY_PASSWORD/);
+
+        // Thumbprint mode: SafeNet owns the PIN, so no password is required here.
+        ctx.expect(signWindows.resolveSigntoolEnv({ WIN_EV_TOKEN_PATH: 'f'.repeat(40) }).password).toBe(undefined);
+      },
+    },
+    {
+      name: 'a timestamp-server failure is retried three times, then throws',
+      run: async (ctx) => {
+        const events = [];
+        const slept  = [];
+        let calls = 0;
+
+        let threw;
+        try {
+          await signWindows.signWithRetry('signtool sign ...', {
+            file:  'App.exe',
+            exec:  () => { calls += 1; throw new Error('SignTool Error: The timestamp signature could not be verified'); },
+            sleep: (ms) => { slept.push(ms); return Promise.resolve(); },
+            emit:  (event, data) => events.push({ event, ...data }),
+          });
+        } catch (e) { threw = e; }
+
+        ctx.expect(calls).toBe(3);
+        ctx.expect(threw.message).toMatch(/timestamp signature/);
+        // Two backoffs between three attempts, and every attempt on the event log.
+        ctx.expect(slept.length).toBe(2);
+        ctx.expect(slept.every((ms) => ms > 0)).toBe(true);
+        ctx.expect(events.filter((e) => e.event === 'sign-attempt').map((e) => e.attempt)).toEqual([1, 2, 3]);
+        ctx.expect(events.filter((e) => e.event === 'sign-retry').length).toBe(2);
+      },
+    },
+    {
+      name: 'the first attempt succeeding is the only attempt',
+      run: async (ctx) => {
+        const events = [];
+        let calls = 0;
+
+        await signWindows.signWithRetry('signtool sign ...', {
+          file:  'App.exe',
+          exec:  () => { calls += 1; return Promise.resolve('Successfully signed'); },
+          sleep: () => { throw new Error('should not back off on success'); },
+          emit:  (event, data) => events.push({ event, ...data }),
+        });
+
+        ctx.expect(calls).toBe(1);
+        ctx.expect(events.map((e) => e.event)).toEqual(['sign-attempt']);
+      },
+    },
+    {
+      name: 'a wrong PIN or a missing cert stops after ONE attempt (never walk the token to a lockout)',
+      run: async (ctx) => {
+        for (const message of [
+          'SignTool Error: The specified network password is not correct.',
+          'SignTool Error: No certificates were found that met all the given criteria.',
+        ]) {
+          const events = [];
+          let calls = 0;
+          let threw;
+          try {
+            await signWindows.signWithRetry('signtool sign ...', {
+              file:  'App.exe',
+              exec:  () => { calls += 1; throw new Error(message); },
+              sleep: () => { throw new Error('should not back off on a non-transient failure'); },
+              emit:  (event, data) => events.push({ event, ...data }),
+            });
+          } catch (e) { threw = e; }
+
+          ctx.expect(calls).toBe(1);
+          ctx.expect(threw.message).toBe(message);
+          ctx.expect(events.filter((e) => e.event === 'sign-retry').length).toBe(0);
+        }
+      },
+    },
+    {
+      name: 'every signtool attempt gets its OWN SafeNet PIN watcher, stopped after it',
+      run: async (ctx) => {
+        // The SafeNet Token Logon dialog reappears on EVERY signtool call, and
+        // the watcher returns once it has typed. One watcher around the whole
+        // retry loop leaves attempts 2 and 3 facing the dialog unattended.
+        const watchers = [];
+
+        let threw;
+        try {
+          await signWindows.signWithRetry('signtool sign ...', {
+            file:  'App.exe',
+            exec:  () => { throw new Error('SignTool Error: The timestamp signature could not be verified'); },
+            sleep: () => Promise.resolve(),
+            emit:  () => {},
+            startUnlock: () => {
+              const watcher = { stopped: false };
+              watchers.push(watcher);
+              return { stop: () => { watcher.stopped = true; } };
+            },
+          });
+        } catch (e) { threw = e; }
+
+        ctx.expect(threw).toBeDefined();
+        ctx.expect(watchers.length).toBe(3);
+        ctx.expect(watchers.every((w) => w.stopped)).toBe(true);
+      },
+    },
+    {
+      name: 'the PIN watcher is stopped before the backoff, not held across it',
+      run: async (ctx) => {
+        const events = [];
+        let live = 0;
+
+        await signWindows.signWithRetry('signtool sign ...', {
+          file:  'App.exe',
+          exec:  () => { events.push(`exec(live=${live})`); return Promise.resolve('ok'); },
+          sleep: () => Promise.resolve(),
+          emit:  () => {},
+          startUnlock: () => { live += 1; return { stop: () => { live -= 1; } }; },
+        });
+
+        ctx.expect(events).toEqual(['exec(live=1)']);
+        ctx.expect(live).toBe(0);
+      },
+    },
+    {
+      name: 'a failure signtool does not name is treated as transient',
+      run: (ctx) => {
+        ctx.expect(signWindows.isTransientSignFailure(new Error('exit status 1'))).toBe(true);
+        ctx.expect(signWindows.isTransientSignFailure(new Error('SignTool Error: No certificates were found'))).toBe(false);
+        ctx.expect(signWindows.isTransientSignFailure(new Error('The specified network password is not correct'))).toBe(false);
+      },
+    },
+  ],
+});