socketduct 0.1.15

package/test/fixtures/logging/enospc-matrix.mjs

@@ -0,0 +1,238 @@
+import {expect} from "@velocious/testing"
+import {spawnSync} from "node:child_process"
+import {createHash} from "node:crypto"
+import {existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, statfsSync, unlinkSync, writeFileSync} from "node:fs"
+
+import {createJsonlFileLogger, createStructuredLogger} from "../../../src/logging/structured-logger.js"
+
+const root = "/fault-space"
+const directory = `${root}/logs`
+const active = `${directory}/reverse-gateway-1.jsonl`
+const mode = process.argv[2] ?? "matrix"
+expect(["matrix", "tear"].includes(mode)).toBeTruthy()
+expect(process.getuid()).toBe(1000)
+expect(process.getgid()).toBe(1000)
+expect(realpathSync(root)).toBe(root)
+const mount = readFileSync("/proc/self/mountinfo", "utf8").trim().split("\n").find((line) => line.split(" ")[4] === root)
+expect(mount).toBeTruthy()
+expect(mount.split(" ")[3]).toBe("/")
+expect(mount.split(" - ")[1].split(" ")[0]).toBe("tmpfs")
+const filesystem = statfsSync(root)
+expect(filesystem.type).toBe(0x01021994)
+expect(filesystem.blocks * filesystem.bsize).toBe(65536)
+expect(readdirSync(root)).toEqual([])
+expect(statSync(root).uid).toBe(1000)
+expect(statSync(root).mode & 0o777).toBe(0o700)
+process.umask(0o077)
+const loggerHash = createHash("sha256").update(readFileSync(new URL("../../../src/logging/structured-logger.js", import.meta.url))).digest("hex")
+console.log(JSON.stringify({phase: "matrix-identity", node: process.version, uid: process.getuid(), gid: process.getgid(), loggerHash}))
+const identity = {role: "reverse-gateway", processId: 1, now: () => new Date("2026-09-08T06:00:00.000Z")}
+const fields = {generation: 1000, gatewayId: "g".repeat(64), physicalConnects: 1000, reconnect: true}
+let largeLine
+createStructuredLogger({...identity, writeLine: (line) => { largeLine = line }}).log("transport.connected", fields)
+expect(largeLine).toBeTruthy()
+const largeRecord = Buffer.from(largeLine)
+expect(largeRecord.length <= 1024).toBeTruthy()
+
+if (mode === "tear") {
+  const maxFiles = Number(process.argv[3])
+  expect([1, 2, 5].includes(maxFiles)).toBeTruthy()
+  await shortWrites(maxFiles, 1, true)
+} else {
+  for (const maxFiles of [1, 2, 5]) {
+    await shortWrites(maxFiles, maxFiles === 1 ? 1 : 2, false)
+    resetCase()
+    restart(maxFiles)
+    resetCase()
+    await noByteWrites(maxFiles)
+    resetCase()
+  }
+  expect(readdirSync(root)).toEqual([])
+  console.log(JSON.stringify({phase: "matrix-correct-output-pass", cases: 9, node: process.version, uid: process.getuid(), gid: process.getgid(), loggerHash, fixtureSpaceEmpty: true}))
+}
+
+/**
+ * @param {number} maxFiles - Retention count.
+ * @param {number} cycles - Actual short appends to exercise.
+ * @param {boolean} tearOnly - Exit the child after fault preparation.
+ * @returns {Promise<void>} Resolves after bounded fault and recovery checks.
+ */
+async function shortWrites(maxFiles, cycles, tearOnly) {
+  const reports = []
+  const logger = createJsonlFileLogger({...identity, directory, maxFiles, maxFileBytes: 8192, stderr: {write: (message) => reports.push(message)}})
+  const knownTorn = []
+  for (let cycle = 0; cycle < cycles; cycle += 1) {
+    let positioned = false
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      logger.log("process.started", {runtimeMode: "reverse-gateway"})
+      const size = statSync(active).size
+      if (size % filesystem.bsize > 0 && filesystem.bsize - size % filesystem.bsize < largeRecord.length) {
+        positioned = true
+        break
+      }
+    }
+    expect(positioned).toBeTruthy()
+    const before = readFileSync(active)
+    expect(before.at(-1)).toBe(10)
+    let torn
+    await withFullDisk(() => {
+      logger.log("transport.connected", fields)
+      torn = readFileSync(active)
+      expect(torn.length > before.length).toBeTruthy()
+      expect(torn.length < before.length + largeRecord.length).toBeTruthy()
+      expect(torn.subarray(0, before.length).equals(before)).toBeTruthy()
+      expect(torn.subarray(before.length).equals(largeRecord.subarray(0, torn.length - before.length))).toBeTruthy()
+      expect(torn.at(-1) === 10).toBe(false)
+      expect(torn.length % filesystem.bsize).toBe(0)
+      knownTorn.push(torn)
+      for (let generation = 0; !tearOnly && generation < 3; generation += 1) {
+        logger.log("transport.connected", {generation})
+        assertManagedFiles(knownTorn, maxFiles, 8192)
+        const evidence = maxFiles === 1 ? active : `${active}.1`
+        expect(readFileSync(evidence).equals(torn)).toBeTruthy()
+        if (maxFiles === 2 && cycle > 0) {
+          const records = readFileSync(active, "utf8").trimEnd().split("\n").map((line) => JSON.parse(line))
+          expect(records.map((record) => record.generation)).toEqual(Array.from({length: generation + 1}, (_, index) => index))
+        } else if (maxFiles > 1) {
+          expect(statSync(active).size).toBe(0)
+        }
+      }
+      expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+      console.log(JSON.stringify({phase: "actual-enospc", case: tearOnly ? "short-before-process-exit" : "short-and-ordinary-calls", maxFiles, cycle, beforeBytes: before.length, attemptedBytes: largeRecord.length, partialBytes: torn.length - before.length, tornBytes: torn.length, filesystemError: "ENOSPC", retentionFreedBlock: maxFiles === 2 && cycle > 0, reports}))
+    })
+    expect(torn).toBeTruthy()
+    if (tearOnly) {
+      console.log(JSON.stringify({phase: "prepared-for-restart", writerPid: process.pid, tornHash: createHash("sha256").update(torn).digest("hex")}))
+      return
+    }
+    assertRecovery(logger, torn, maxFiles, maxFiles === 1 ? Buffer.alloc(0) : readFileSync(active))
+    assertManagedFiles(knownTorn, maxFiles, 8192)
+    expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+  }
+  console.log(JSON.stringify({phase: "case-pass", case: "same-instance", maxFiles, cycles}))
+}
+
+/** @param {number} maxFiles - Retention count. */
+function restart(maxFiles) {
+  const child = spawnSync(process.execPath, [import.meta.filename, "tear", String(maxFiles)], {encoding: "utf8", timeout: 10_000})
+  if (child.error) throw child.error
+  process.stdout.write(child.stdout)
+  expect(child.status).toBe(0)
+  expect(child.signal).toBe(null)
+  expect(child.stderr).toBe("")
+  const receipt = JSON.parse(child.stdout.trimEnd().split("\n").at(-1))
+  expect(receipt.phase).toBe("prepared-for-restart")
+  const torn = readFileSync(active)
+  expect(createHash("sha256").update(torn).digest("hex")).toBe(receipt.tornHash)
+  const original = statSync(active)
+  const reports = []
+  const logger = createJsonlFileLogger({...identity, directory, maxFiles, maxFileBytes: 8192, stderr: {write: (message) => reports.push(message)}})
+  assertRecovery(logger, torn, maxFiles)
+  const evidence = maxFiles === 1 ? active : `${active}.1`
+  expect(statSync(evidence).ino).toBe(original.ino)
+  assertManagedFiles([torn], maxFiles, 8192)
+  expect(reports).toEqual(maxFiles === 1 ? ["Socketduct logger failure (LOGGER_IO_ERROR)\n"] : [])
+  console.log(JSON.stringify({phase: "case-pass", case: "process-restart", maxFiles, exitedWriterPid: receipt.writerPid, resumedWriterPid: process.pid}))
+}
+
+/**
+ * @param {number} maxFiles - Retention count.
+ * @returns {Promise<void>} Resolves after repeated no-byte failure checks.
+ */
+async function noByteWrites(maxFiles) {
+  mkdirSync(directory, {mode: 0o700})
+  const reports = []
+  const logger = createJsonlFileLogger({...identity, directory, maxFiles, maxFileBytes: 1024, stderr: {write: (message) => reports.push(message)}})
+  await withFullDisk(() => {
+    for (let generation = 0; generation < 3; generation += 1) {
+      logger.log("transport.connected", {generation})
+      expect(statSync(active).size).toBe(0)
+    }
+    expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+    console.log(JSON.stringify({phase: "actual-enospc", case: "empty-file-repeated-no-byte", maxFiles, maxFileBytes: 1024, filesystemError: "ENOSPC", reports}))
+  })
+  logger.log("transport.connected", {generation: 77})
+  logger.log("runtime.status", {physicalConnections: 1})
+  const lines = readFileSync(active, "utf8").trimEnd().split("\n")
+  expect(lines.map((line) => JSON.parse(line).event)).toEqual(["transport.connected", "runtime.status"])
+  assertManagedFiles([], maxFiles, 1024)
+  expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+  console.log(JSON.stringify({phase: "case-pass", case: "no-byte", maxFiles}))
+}
+
+/**
+ * @param {() => void} exercise - Faulted operations.
+ * @returns {Promise<void>} Resolves after restoring the fixture filler space.
+ */
+async function withFullDisk(exercise) {
+  const filler = `${root}/filler`
+  const probe = `${root}/no-space-probe`
+  try {
+    const freeBytes = statfsSync(root).bavail * filesystem.bsize
+    expect(freeBytes > 0 && freeBytes <= 65536).toBeTruthy()
+    writeFileSync(filler, Buffer.alloc(freeBytes), {flag: "wx", mode: 0o600})
+    expect(statfsSync(root).bavail).toBe(0)
+    await expect(Promise.resolve().then(() => writeFileSync(probe, Buffer.alloc(filesystem.bsize), {flag: "wx", mode: 0o600}))).rejects.toMatchObject({code: "ENOSPC"})
+    await exercise()
+  } finally {
+    if (existsSync(filler)) unlinkSync(filler)
+    if (existsSync(probe)) unlinkSync(probe)
+  }
+  expect(statfsSync(root).bavail > 0).toBeTruthy()
+}
+
+/**
+ * @param {import('../../../src/logging/structured-logger.js').DiagnosticLogger} logger - Resumed logger.
+ * @param {Buffer} torn - Exact damaged bytes.
+ * @param {number} maxFiles - Retention count.
+ * @param {Buffer} [prefix] - Complete records already accepted using a freed retention block.
+ */
+function assertRecovery(logger, torn, maxFiles, prefix = Buffer.alloc(0)) {
+  logger.log("transport.connected", {generation: 77})
+  logger.log("runtime.status", {physicalConnections: 1})
+  const evidence = maxFiles === 1 ? active : `${active}.1`
+  expect(readFileSync(evidence).equals(torn)).toBeTruthy()
+  if (maxFiles === 1) return
+  const recovered = readFileSync(active)
+  expect(recovered.subarray(0, prefix.length).equals(prefix)).toBeTruthy()
+  const contents = recovered.subarray(prefix.length).toString("utf8")
+  expect(contents.endsWith("\n")).toBeTruthy()
+  expect(contents.trimEnd().split("\n").map((line) => JSON.parse(line))).toEqual([
+    {timestamp: identity.now().toISOString(), event: "transport.connected", processId: 1, role: identity.role, generation: 77},
+    {timestamp: identity.now().toISOString(), event: "runtime.status", processId: 1, role: identity.role, physicalConnections: 1}
+  ])
+}
+
+/**
+ * @param {Buffer[]} knownTorn - Explicitly identified incident evidence.
+ * @param {number} maxFiles - Retention count.
+ * @param {number} maxFileBytes - Per-file limit.
+ */
+function assertManagedFiles(knownTorn, maxFiles, maxFileBytes) {
+  const files = readdirSync(directory)
+  expect(files.length <= maxFiles).toBeTruthy()
+  expect(statSync(directory).mode & 0o777).toBe(0o700)
+  for (const file of files) {
+    expect(file).toMatch(/^reverse-gateway-1\.jsonl(?:\.[1-9][0-9]*)?$/)
+    const stats = statSync(`${directory}/${file}`)
+    expect(stats.isFile()).toBeTruthy()
+    expect(stats.size <= maxFileBytes).toBeTruthy()
+    expect(stats.mode & 0o777).toBe(0o600)
+    const contents = readFileSync(`${directory}/${file}`)
+    if (knownTorn.some((torn) => torn.equals(contents))) continue
+    if (contents.length === 0) continue
+    expect(contents.at(-1)).toBe(10)
+    for (const line of contents.toString("utf8").trimEnd().split("\n")) {
+      expect(Buffer.byteLength(`${line}\n`) <= 1024).toBeTruthy()
+      JSON.parse(line)
+    }
+  }
+}
+
+/** Clears only contents owned by the completed disposable case. */
+function resetCase() {
+  expect(readdirSync(root)).toEqual(["logs"])
+  for (const file of readdirSync(directory)) expect(file).toMatch(/^reverse-gateway-1\.jsonl(?:\.[1-9][0-9]*)?$/)
+  rmSync(directory, {recursive: true})
+  expect(readdirSync(root)).toEqual([])
+}

package/test/fixtures/logging/enospc-recovery.mjs

@@ -0,0 +1,146 @@
+import {expect} from "@velocious/testing"
+import {createHash} from "node:crypto"
+import {existsSync, readFileSync, readdirSync, realpathSync, statSync, statfsSync, unlinkSync, writeFileSync} from "node:fs"
+
+import {createJsonlFileLogger, createStructuredLogger} from "../../../src/logging/structured-logger.js"
+
+const root = "/fault-space"
+expect(process.getuid()).toBe(1000)
+expect(process.getgid()).toBe(1000)
+expect(realpathSync(root)).toBe(root)
+const mounts = readFileSync("/proc/self/mountinfo", "utf8").trim().split("\n")
+const mount = mounts.find((line) => line.split(" ")[4] === root)
+expect(mount).toBeTruthy()
+expect(mount.split(" - ")[1].split(" ")[0]).toBe("tmpfs")
+expect(mount.split(" ")[3]).toBe("/")
+const filesystem = statfsSync(root)
+expect(filesystem.type).toBe(0x01021994)
+expect(filesystem.blocks * filesystem.bsize).toBe(64 * 1024)
+expect(readdirSync(root)).toEqual([])
+expect(statSync(root).uid).toBe(1000)
+expect(statSync(root).mode & 0o777).toBe(0o700)
+process.umask(0o077)
+
+const directory = `${root}/logs`
+const active = `${directory}/reverse-gateway-1.jsonl`
+const filler = `${root}/filler`
+const probe = `${root}/no-space-probe`
+const options = {directory, role: "reverse-gateway", processId: 1, now: () => new Date("2026-09-08T06:00:00.000Z")}
+const reports = []
+const logger = createJsonlFileLogger({...options, stderr: {write: (message) => reports.push(message)}})
+const fields = {
+  activeTargets: 10,
+  activeTunnels: 10,
+  attachedSessions: 10,
+  authenticatedConnections: 10,
+  bufferedBytes: 10,
+  bufferedTargetBytes: 10,
+  clientPhysicalConnections: 10,
+  connectionGeneration: 10,
+  connectionIdentities: 10,
+  controlQueuedBytes: 10,
+  dataQueuedBytes: 10,
+  detachedSessions: 10,
+  gatewayPhysicalConnections: 10,
+  gatewayRegistrations: 10,
+  healthyGateways: 10,
+  openFailures: 10,
+  pendingOpens: 10,
+  physicalAccepts: 10,
+  physicalConnections: 10,
+  physicalConnects: 10,
+  rawDataBytes: 10,
+  registeredGateways: 10,
+  rejectedOpens: 10,
+  rejectedRegistrations: 10,
+  retainedClientIdentities: 10,
+  targetOpens: 10,
+  virtualStreams: 10,
+  wireDataBytes: 10
+}
+let largeLine
+createStructuredLogger({...options, writeLine: (line) => { largeLine = line }}).log("runtime.status", fields)
+expect(largeLine).toBeTruthy()
+const largeRecord = Buffer.from(largeLine)
+expect(largeRecord.length <= 1024).toBeTruthy()
+const blockBytes = filesystem.bsize
+let initialEvents = 0
+for (; initialEvents < 100; initialEvents += 1) {
+  logger.log("process.started", {runtimeMode: "reverse-gateway"})
+  const size = statSync(active).size
+  if (size % blockBytes > 0 && blockBytes - size % blockBytes < largeRecord.length) {
+    initialEvents += 1
+    break
+  }
+}
+expect(initialEvents < 100).toBeTruthy()
+const before = readFileSync(active)
+expect(before.at(-1)).toBe(10)
+for (const line of before.toString("utf8").trimEnd().split("\n")) JSON.parse(line)
+expect(reports).toEqual([])
+
+let torn
+try {
+  const freeBytes = statfsSync(root).bavail * blockBytes
+  expect(freeBytes > 0 && freeBytes <= 64 * 1024).toBeTruthy()
+  writeFileSync(filler, Buffer.alloc(freeBytes), {flag: "wx", mode: 0o600})
+  expect(statfsSync(root).bavail).toBe(0)
+  await expect(Promise.resolve().then(() => writeFileSync(probe, Buffer.alloc(blockBytes), {flag: "wx", mode: 0o600}))).rejects.toMatchObject({code: "ENOSPC"})
+  await expect(() => logger.log("runtime.status", fields)).not.toThrow()
+  torn = readFileSync(active)
+  expect(torn.length > before.length).toBeTruthy()
+  expect(torn.length < before.length + largeRecord.length).toBeTruthy()
+  expect(torn.length % blockBytes).toBe(0)
+  expect(torn.subarray(0, before.length).equals(before)).toBeTruthy()
+  const partialRecord = torn.subarray(before.length)
+  expect(partialRecord.equals(largeRecord.subarray(0, partialRecord.length))).toBeTruthy()
+  expect(partialRecord.includes(10)).toBe(false)
+  expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+  console.log(JSON.stringify({
+    phase: "actual-enospc-short-append",
+    uid: process.getuid(),
+    gid: process.getgid(),
+    node: process.version,
+    loggerHash: createHash("sha256").update(readFileSync(new URL("../../../src/logging/structured-logger.js", import.meta.url))).digest("hex"),
+    filesystemError: "ENOSPC",
+    blockBytes,
+    initialEvents,
+    beforeBytes: before.length,
+    attemptedRecordBytes: largeRecord.length,
+    tornBytes: torn.length,
+    partialRecordBytes: partialRecord.length,
+    tornHash: createHash("sha256").update(torn).digest("hex")
+  }))
+} finally {
+  if (existsSync(filler)) unlinkSync(filler)
+  if (existsSync(probe)) unlinkSync(probe)
+}
+
+expect(statfsSync(root).bavail > 0).toBeTruthy()
+expect(torn).toBeTruthy()
+logger.log("transport.connected", {generation: 1, reconnect: true})
+logger.log("runtime.status", {physicalConnections: 1})
+const recovered = readFileSync(active)
+const retainedPath = `${active}.1`
+const preserved = existsSync(retainedPath) && readFileSync(retainedPath).equals(torn)
+const lines = recovered.toString("utf8").trimEnd().split("\n")
+const joinedRecords = lines.filter((line) => (line.match(/\{"timestamp":/g) ?? []).length > 1).length
+console.log(JSON.stringify({phase: "recovery-observed", preserved, joinedRecords, activeBytes: recovered.length, reports}))
+expect(preserved).toBe(true)
+expect(joinedRecords).toBe(0)
+expect(recovered.at(-1)).toBe(10)
+expect(lines.map((line) => JSON.parse(line))).toEqual([
+  {timestamp: options.now().toISOString(), event: "transport.connected", processId: 1, role: options.role, generation: 1, reconnect: true},
+  {timestamp: options.now().toISOString(), event: "runtime.status", processId: 1, role: options.role, physicalConnections: 1}
+])
+for (const line of lines) expect(Buffer.byteLength(`${line}\n`) <= 1024).toBeTruthy()
+expect(readdirSync(directory).sort()).toEqual(["reverse-gateway-1.jsonl", "reverse-gateway-1.jsonl.1"])
+expect(statSync(directory).mode & 0o777).toBe(0o700)
+for (const path of [active, retainedPath]) {
+  expect(statSync(path).mode & 0o777).toBe(0o600)
+  expect(statSync(path).size <= 10 * 1024 * 1024).toBeTruthy()
+}
+expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+expect(existsSync(filler)).toBe(false)
+expect(existsSync(probe)).toBe(false)
+console.log(JSON.stringify({phase: "correct-output-pass", preserved: true, newRecords: lines.length, joinedRecords: 0, fillerRemoved: true}))

package/test/fixtures/logging/process-writer.mjs

@@ -0,0 +1,20 @@
+import {expect} from "@velocious/testing"
+
+import {createJsonlFileLogger} from "../../../src/logging/structured-logger.js"
+
+const [directory, maxFiles, maxFileBytes] = process.argv.slice(2)
+expect(directory).toBeTruthy()
+expect(maxFiles).toBeTruthy()
+expect(maxFileBytes).toBeTruthy()
+const reports = []
+const logger = createJsonlFileLogger({
+  directory,
+  role: "reverse-gateway",
+  processId: 1,
+  maxFiles: Number(maxFiles),
+  maxFileBytes: Number(maxFileBytes),
+  stderr: {write: (message) => reports.push(message)}
+})
+logger.log("process.started", {runtimeMode: "reverse-gateway"})
+logger.log("runtime.status", {physicalConnections: 1})
+console.log(JSON.stringify({processId: process.pid, reports}))

package/test/helpers/tls-certificates.js

@@ -0,0 +1,115 @@
+import {execFileSync} from "node:child_process"
+import {mkdirSync, writeFileSync} from "node:fs"
+import {join} from "node:path"
+
+const EC_CURVE = "prime256v1"
+const DAYS_VALID = 365
+
+/**
+ * @typedef {object} TlsTestCertificates
+ * @property {string} caCertFile - Self-signed CA certificate path.
+ * @property {string} caKeyFile - CA private key path.
+ * @property {string} serverCertFile - Server certificate path (signed by CA).
+ * @property {string} serverKeyFile - Server private key path.
+ * @property {string} clientCertFile - Client certificate path (signed by CA, for mTLS).
+ * @property {string} clientKeyFile - Client private key path.
+ */
+/**
+ * @typedef {object} TlsTestCertificateOptions
+ * @property {string} [serverSubjectAltName] - Server certificate subjectAltName extension.
+ */
+/**
+ * Test-only self-signed TLS certificate material. NEVER use these files for production secrets.
+ * They are generated ephemerally inside temp directories during test runs.
+ * @param {string} dir - Directory to write certificate files into.
+ * @param {TlsTestCertificateOptions} [options] - Certificate overrides.
+ * @returns {TlsTestCertificates} Paths to generated certificate material.
+ */
+export function generateTestCertificates(dir, options = {}) {
+  mkdirSync(dir, {recursive: true})
+
+  const caKeyFile = join(dir, "ca.key")
+  const caCertFile = join(dir, "ca.crt")
+  const serverKeyFile = join(dir, "server.key")
+  const serverCertFile = join(dir, "server.crt")
+  const clientKeyFile = join(dir, "client.key")
+  const clientCertFile = join(dir, "client.crt")
+
+  execFileSync("openssl", [
+    "ecparam", "-genkey", "-name", EC_CURVE, "-out", caKeyFile
+  ], {stdio: "ignore"})
+
+  execFileSync("openssl", [
+    "req", "-x509", "-new", "-key", caKeyFile,
+    "-out", caCertFile,
+    "-days", String(DAYS_VALID),
+    "-subj", "/CN=Socketduct Test CA/O=Socketduct Tests/OU=Test Only",
+    "-addext", "basicConstraints=critical,CA:TRUE,pathlen:0",
+    "-addext", "keyUsage=critical,keyCertSign,cRLSign"
+  ], {stdio: "ignore"})
+
+  const sanExtFile = join(dir, "san.ext")
+  writeFileSync(sanExtFile, `subjectAltName = ${options.serverSubjectAltName ?? "DNS:localhost, IP:127.0.0.1"}\n`, "utf8")
+
+  signCertificate(serverKeyFile, serverCertFile, "socketduct-test-server", caKeyFile, caCertFile, sanExtFile)
+  signCertificate(clientKeyFile, clientCertFile, "socketduct-test-client", caKeyFile, caCertFile)
+
+  return {caCertFile, caKeyFile, serverCertFile, serverKeyFile, clientCertFile, clientKeyFile}
+}
+
+/**
+ * Generates an additional server certificate signed by an existing test CA.
+ * @param {string} dir - Directory to write certificate files into.
+ * @param {{caCertFile: string, caKeyFile: string, subjectAltName: string, commonName?: string}} options - Certificate options.
+ * @returns {{serverCertFile: string, serverKeyFile: string}} Generated server certificate paths.
+ */
+export function generateTestServerCertificate(dir, options) {
+  mkdirSync(dir, {recursive: true})
+  const serverKeyFile = join(dir, "server.key")
+  const serverCertFile = join(dir, "server.crt")
+  const sanExtFile = join(dir, "san.ext")
+  writeFileSync(sanExtFile, `subjectAltName = ${options.subjectAltName}\n`, "utf8")
+  signCertificate(
+    serverKeyFile,
+    serverCertFile,
+    options.commonName ?? "socketduct-test-server",
+    options.caKeyFile,
+    options.caCertFile,
+    sanExtFile
+  )
+  return {serverCertFile, serverKeyFile}
+}
+
+/**
+ * @param {string} keyFile - Output key file path.
+ * @param {string} certFile - Output certificate file path.
+ * @param {string} commonName - Certificate CN.
+ * @param {string} caKeyFile - CA private key path.
+ * @param {string} caCertFile - CA certificate path.
+ * @param {string} [extFile] - Optional extensions file for SAN.
+ */
+function signCertificate(keyFile, certFile, commonName, caKeyFile, caCertFile, extFile) {
+  execFileSync("openssl", [
+    "ecparam", "-genkey", "-name", EC_CURVE, "-out", keyFile
+  ], {stdio: "ignore"})
+
+  const csrFile = certFile.replace(/\.crt$/, ".csr")
+  execFileSync("openssl", [
+    "req", "-new", "-key", keyFile,
+    "-subj", `/CN=${commonName}/O=Socketduct Tests/OU=Test Only`,
+    "-out", csrFile
+  ], {stdio: "ignore"})
+
+  /** @type {string[]} */
+  const signArgs = [
+    "x509", "-req", "-in", csrFile,
+    "-CA", caCertFile, "-CAkey", caKeyFile,
+    "-CAcreateserial",
+    "-out", certFile,
+    "-days", String(DAYS_VALID)
+  ]
+  if (extFile !== undefined) {
+    signArgs.push("-extfile", extFile)
+  }
+  execFileSync("openssl", signArgs, {stdio: "ignore"})
+}