mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-22 16:10:50 +00:00
Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
37e4b8528e | ||
|
|
d1c4b6deb1 |
No files matched your search
@@ -131,6 +131,21 @@ function createZmodemSentry(opts) {
|
||||
const pendingEchoes = [];
|
||||
let pendingTerminalSuppression = null;
|
||||
let pendingTerminalSuppressionAt = 0;
|
||||
let pendingHexHeaderFragment = null;
|
||||
let pendingHexHeaderFragmentTimer = null;
|
||||
// Bytes at the head of the deferred fragment stream that were already
|
||||
// printed to the terminal by the TTL flush. They may still be the head of
|
||||
// a header whose remainder arrives later (e.g. after a transport stall),
|
||||
// so the deferred stream must keep them for stripping — but they must
|
||||
// never be printed a second time (#3660).
|
||||
let flushedHexHeaderPrefix = null;
|
||||
// Fragment index recorded by the most recent deferIncompleteHexHeader()
|
||||
// call, so the terminal pipeline can tell "withheld everything" apart
|
||||
// from "withheld a tail".
|
||||
let deferredHexHeaderFragmentAt = -1;
|
||||
// Set when a stripped hex header's trailing XON (0x11) may arrive in the
|
||||
// next terminal-output chunk; at most one byte is then dropped.
|
||||
let suppressNextTerminalXon = false;
|
||||
|
||||
function setPendingTerminalSuppression(buf) {
|
||||
pendingTerminalSuppression = buf;
|
||||
@@ -152,6 +167,16 @@ function createZmodemSentry(opts) {
|
||||
const COOLDOWN_MS = 2000;
|
||||
const ECHO_TTL_MS = 1500;
|
||||
const ECHO_MAX_BYTES = 256;
|
||||
// "**" + ZDLE + 'B': the start of every ZMODEM hex header.
|
||||
const ZMODEM_HEX_HEADER_PREFIX = Buffer.from([0x2a, 0x2a, 0x18, 0x42]);
|
||||
// 4-byte pattern + 14 hex digits + CR is the most a still-incomplete
|
||||
// header can look like before the final LF (plus optional XON) arrives.
|
||||
const ZMODEM_HEX_HEADER_MAX_PARTIAL = 19;
|
||||
// How long a withheld partial-header fragment may sit unresolved before
|
||||
// it is flushed through to the terminal anyway.
|
||||
const HEX_HEADER_FRAGMENT_TTL_MS = Number.isFinite(opts.hexHeaderFragmentTtlMs)
|
||||
? Math.max(1, opts.hexHeaderFragmentTtlMs)
|
||||
: 1000;
|
||||
/**
|
||||
* Upper bound on how long a drag-drop echo suppression may stay armed.
|
||||
* The suppression hides the terminal echo of the upload command, whose echo
|
||||
@@ -240,6 +265,14 @@ function createZmodemSentry(opts) {
|
||||
return buf;
|
||||
}
|
||||
|
||||
function isHexDigitByte(byte) {
|
||||
return (
|
||||
(byte >= 0x30 && byte <= 0x39)
|
||||
|| (byte >= 0x41 && byte <= 0x46)
|
||||
|| (byte >= 0x61 && byte <= 0x66)
|
||||
);
|
||||
}
|
||||
|
||||
function stripVisibleZmodemHeaders(data) {
|
||||
let buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
|
||||
let searchFrom = 0;
|
||||
@@ -253,12 +286,7 @@ function createZmodemSentry(opts) {
|
||||
|
||||
let isHexHeader = true;
|
||||
for (let i = 0; i < 14; i += 1) {
|
||||
const byte = buf[prefixAt + 4 + i];
|
||||
const isHexDigit =
|
||||
(byte >= 0x30 && byte <= 0x39) ||
|
||||
(byte >= 0x41 && byte <= 0x46) ||
|
||||
(byte >= 0x61 && byte <= 0x66);
|
||||
if (!isHexDigit) {
|
||||
if (!isHexDigitByte(buf[prefixAt + 4 + i])) {
|
||||
isHexHeader = false;
|
||||
break;
|
||||
}
|
||||
@@ -274,6 +302,10 @@ function createZmodemSentry(opts) {
|
||||
headerLength = 20;
|
||||
if (buf[prefixAt + 20] === 0x11) {
|
||||
headerLength = 21;
|
||||
} else if (prefixAt + 20 === buf.length) {
|
||||
// The optional XON that follows the CR/LF may arrive in the next
|
||||
// chunk; strip at most one leading XON byte from it (#3651).
|
||||
suppressNextTerminalXon = true;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -287,6 +319,126 @@ function createZmodemSentry(opts) {
|
||||
return buf;
|
||||
}
|
||||
|
||||
function flushPendingHexHeaderFragment() {
|
||||
pendingHexHeaderFragmentTimer = null;
|
||||
const buf = pendingHexHeaderFragment;
|
||||
if (!buf?.length) return;
|
||||
// The fragment may still be the head of a header whose remainder arrives
|
||||
// later (transport stall). Print its unprinted tail now (deferrals must
|
||||
// never lose output) but keep the whole fragment deferred and mergeable so
|
||||
// the remainder is stripped, not leaked as garble (#3660).
|
||||
const printedLen = flushedHexHeaderPrefix?.length || 0;
|
||||
flushedHexHeaderPrefix = buf;
|
||||
if (buf.length > printedLen) onData(buf.subarray(printedLen));
|
||||
}
|
||||
|
||||
/**
|
||||
* A ZMODEM hex header (the ZRQINIT/ZRINIT preamble of `sz`/`rz`) can be
|
||||
* split across transport chunks. zmodem.js hands each original chunk to
|
||||
* to_terminal verbatim and only complete headers can be stripped, so a
|
||||
* chunk that ends in the middle of the preamble painted it as terminal
|
||||
* garble (#3651). Detect the trailing bytes that may still form one and
|
||||
* hold them back; the next chunk either completes the header (stripped
|
||||
* above) or proves the buffer invalid. A TTL guard flushes held bytes so
|
||||
* deferrals can never lose legitimate terminal output.
|
||||
*
|
||||
* Returns the index from which the buffer should be withheld, or -1.
|
||||
*/
|
||||
function findTrailingHexHeaderFragment(buf) {
|
||||
if (!buf.length) return -1;
|
||||
|
||||
// Longest still-incomplete header tail: the 4-byte pattern, 14 hex
|
||||
// digits, and a CR — i.e. everything up to the final LF (+ optional XON).
|
||||
const windowStart = Math.max(0, buf.length - ZMODEM_HEX_HEADER_MAX_PARTIAL);
|
||||
|
||||
for (let i = windowStart; i <= buf.length - 4; i += 1) {
|
||||
let matched = true;
|
||||
for (let j = 0; j < 4; j += 1) {
|
||||
if (buf[i + j] !== ZMODEM_HEX_HEADER_PREFIX[j]) {
|
||||
matched = false;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (!matched) continue;
|
||||
|
||||
let digits = 0;
|
||||
while (i + 4 + digits < buf.length && isHexDigitByte(buf[i + 4 + digits])) {
|
||||
digits += 1;
|
||||
}
|
||||
|
||||
// Chunk ends inside the hex digits — the header may still complete.
|
||||
if (i + 4 + digits === buf.length) return i;
|
||||
|
||||
// Digit run ended before the 14 required digits, or overshoots them:
|
||||
// not a hex header.
|
||||
if (digits !== 14) continue;
|
||||
|
||||
// A CR (but not yet the trailing LF) may still complete the header.
|
||||
if (buf.length - i <= 19) return i;
|
||||
|
||||
break;
|
||||
}
|
||||
|
||||
// The "**" + ZDLE + 'B' pattern itself may be split: withhold any
|
||||
// trailing bytes that are a prefix of it until the next chunk resolves.
|
||||
for (let k = Math.min(3, buf.length); k >= 1; k -= 1) {
|
||||
let matches = true;
|
||||
for (let j = 0; j < k; j += 1) {
|
||||
if (buf[buf.length - k + j] !== ZMODEM_HEX_HEADER_PREFIX[j]) {
|
||||
matches = false;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (matches) return buf.length - k;
|
||||
}
|
||||
|
||||
return -1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Join any previously withheld partial-header bytes onto the new chunk so
|
||||
* the suppression/stripping stages can see a complete header again. This
|
||||
* must run BEFORE the stripping stages, or a header split across two
|
||||
* chunks would be judged complete too late and reach the terminal.
|
||||
*/
|
||||
function assembleTerminalChunk(octets) {
|
||||
const buf = Buffer.isBuffer(octets) ? octets : Buffer.from(octets);
|
||||
if (!pendingHexHeaderFragment?.length) {
|
||||
return buf;
|
||||
}
|
||||
if (pendingHexHeaderFragmentTimer) {
|
||||
clearTimeout(pendingHexHeaderFragmentTimer);
|
||||
pendingHexHeaderFragmentTimer = null;
|
||||
}
|
||||
const merged = Buffer.concat([pendingHexHeaderFragment, buf]);
|
||||
pendingHexHeaderFragment = null;
|
||||
return merged;
|
||||
}
|
||||
|
||||
/**
|
||||
* Withhold a trailing partial hex header (if any) and arm a timer that
|
||||
* flushes it when no more bytes arrive to resolve it.
|
||||
*/
|
||||
function deferIncompleteHexHeader(data) {
|
||||
const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
|
||||
|
||||
const fragmentAt = findTrailingHexHeaderFragment(buf);
|
||||
deferredHexHeaderFragmentAt = fragmentAt;
|
||||
if (fragmentAt === -1) return buf;
|
||||
|
||||
if (fragmentAt < buf.length) {
|
||||
pendingHexHeaderFragment = Buffer.from(buf.subarray(fragmentAt));
|
||||
if (!pendingHexHeaderFragmentTimer) {
|
||||
pendingHexHeaderFragmentTimer = setTimeout(
|
||||
flushPendingHexHeaderFragment,
|
||||
HEX_HEADER_FRAGMENT_TTL_MS,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
return fragmentAt ? buf.subarray(0, fragmentAt) : Buffer.alloc(0);
|
||||
}
|
||||
|
||||
function looksLikeResidualZmodemData(data) {
|
||||
const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
|
||||
if (!buf.length) return true;
|
||||
@@ -453,8 +605,40 @@ function createZmodemSentry(opts) {
|
||||
const sentry = new Zmodem.Sentry({
|
||||
to_terminal(octets) {
|
||||
// Normal data – pass raw bytes to the caller for charset-aware decoding.
|
||||
let sanitizedOctets = stripPendingTerminalSuppression(Buffer.from(octets));
|
||||
// Bytes that may be the start of a ZMODEM hex header split across
|
||||
// chunks are withheld first (and later stripped or flushed) so the
|
||||
// preamble of sz/rz never reaches the terminal as garble (#3651).
|
||||
let sanitizedOctets = assembleTerminalChunk(octets);
|
||||
if (suppressNextTerminalXon) {
|
||||
suppressNextTerminalXon = false;
|
||||
if (sanitizedOctets[0] === 0x11) {
|
||||
sanitizedOctets = sanitizedOctets.subarray(1);
|
||||
}
|
||||
}
|
||||
sanitizedOctets = stripPendingTerminalSuppression(sanitizedOctets);
|
||||
sanitizedOctets = stripVisibleZmodemHeaders(sanitizedOctets);
|
||||
sanitizedOctets = deferIncompleteHexHeader(sanitizedOctets);
|
||||
// Bytes that the TTL flush already printed must not be printed again:
|
||||
// they still lead the deferred stream (so a header split across a
|
||||
// transport stall can complete and be stripped, #3660), but the moment
|
||||
// anything beyond them is emitted — or a stripped header consumed them —
|
||||
// they are gone from the live stream and the marker must be dropped.
|
||||
if (flushedHexHeaderPrefix?.length) {
|
||||
const printed = flushedHexHeaderPrefix;
|
||||
const stillHead =
|
||||
sanitizedOctets.length >= printed.length &&
|
||||
sanitizedOctets.subarray(0, printed.length).equals(printed);
|
||||
if (sanitizedOctets.length) {
|
||||
if (stillHead) {
|
||||
sanitizedOctets = sanitizedOctets.subarray(printed.length);
|
||||
}
|
||||
flushedHexHeaderPrefix = null;
|
||||
} else if (deferredHexHeaderFragmentAt !== 0) {
|
||||
// Empty output without deferring everything means the flushed
|
||||
// bytes were consumed by a stripped header (or vanished).
|
||||
flushedHexHeaderPrefix = null;
|
||||
}
|
||||
}
|
||||
if (!sanitizedOctets.length) return;
|
||||
onData(sanitizedOctets);
|
||||
},
|
||||
|
||||
@@ -1489,3 +1489,154 @@ test("createZmodemUploadDrainWaiter falls back to a single yield without transpo
|
||||
await waitForDrain();
|
||||
assert.equal(needsDrain, false);
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Split hex-header preamble (#3651): the ZRQINIT/ZRINIT hex header that opens
|
||||
// every sz/rz session can be fragmented across transport chunks; it must
|
||||
// never reach the terminal as garble, and withheld bytes must never be lost.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const ZmodemLib = require("zmodem.js");
|
||||
|
||||
const DOWNLOAD_PREAMBLE_TEXT = "sz: Sending test.bin\r\nrz\r";
|
||||
|
||||
function buildHexHeaderBytes(name, args) {
|
||||
return Buffer.from(ZmodemLib.Header.build(name, ...(args || [])).to_hex());
|
||||
}
|
||||
|
||||
function createProbeSentry(extra) {
|
||||
const terminal = [];
|
||||
const sentry = createZmodemSentry({
|
||||
sessionId: "probe",
|
||||
onData: (buf) => terminal.push(Buffer.from(buf)),
|
||||
writeToRemote: () => true,
|
||||
getWebContents: () => null,
|
||||
selectDownloadDirectory: async () => ({ canceled: true }),
|
||||
selectUploadFiles: async () => null,
|
||||
hexHeaderFragmentTtlMs: 30,
|
||||
...extra,
|
||||
});
|
||||
return { sentry, terminal };
|
||||
}
|
||||
|
||||
function joinedText(terminal) {
|
||||
return Buffer.concat(terminal).toString("latin1");
|
||||
}
|
||||
|
||||
function assertNoZmodemHeaderBytes(terminal, context) {
|
||||
const joined = Buffer.concat(terminal);
|
||||
assert.equal(
|
||||
joined.indexOf(Buffer.from([0x2a, 0x2a, 0x18, 0x42])),
|
||||
-1,
|
||||
`${context}: ZRQINIT/ZRINIT preamble leaked to the terminal`,
|
||||
);
|
||||
assert.equal(
|
||||
joined.includes(Buffer.from([0x18])),
|
||||
false,
|
||||
`${context}: ZDLE/CAN byte leaked to the terminal`,
|
||||
);
|
||||
}
|
||||
|
||||
test("fragmented sz ZRQINIT preamble never reaches the terminal", () => {
|
||||
const { sentry, terminal } = createProbeSentry();
|
||||
const stream = Buffer.concat([
|
||||
Buffer.from(DOWNLOAD_PREAMBLE_TEXT),
|
||||
buildHexHeaderBytes("ZRQINIT"),
|
||||
Buffer.from("$ "),
|
||||
]);
|
||||
|
||||
for (const byte of stream) sentry.consume(Buffer.from([byte]));
|
||||
|
||||
assert.equal(
|
||||
joinedText(terminal),
|
||||
`${DOWNLOAD_PREAMBLE_TEXT}$ `,
|
||||
"only the human-readable sz preamble text should be shown",
|
||||
);
|
||||
assertNoZmodemHeaderBytes(terminal, "byte-at-a-time");
|
||||
});
|
||||
|
||||
test("split sz preamble leaks nothing at any chunk boundary", () => {
|
||||
const header = buildHexHeaderBytes("ZRQINIT");
|
||||
// Header.build().to_hex() already includes the trailing XON byte.
|
||||
const stream = Buffer.concat([
|
||||
Buffer.from(DOWNLOAD_PREAMBLE_TEXT),
|
||||
header,
|
||||
Buffer.from("$ "),
|
||||
]);
|
||||
|
||||
for (let chunkSize = 1; chunkSize <= 24; chunkSize += 1) {
|
||||
const { sentry, terminal } = createProbeSentry();
|
||||
for (let i = 0; i < stream.length; i += chunkSize) {
|
||||
sentry.consume(stream.subarray(i, i + chunkSize));
|
||||
}
|
||||
assert.equal(joinedText(terminal), `${DOWNLOAD_PREAMBLE_TEXT}$ `);
|
||||
assertNoZmodemHeaderBytes(terminal, `chunkSize=${chunkSize}`);
|
||||
}
|
||||
});
|
||||
|
||||
test("fragmented rz ZRINIT preamble never reaches the terminal", () => {
|
||||
const header = buildHexHeaderBytes("ZRINIT", [["CANFDX", "CANOVIO", "CANFC32"]]);
|
||||
const stream = Buffer.concat([Buffer.from("root@host:~$ "), header]);
|
||||
|
||||
for (let chunkSize = 1; chunkSize <= 24; chunkSize += 1) {
|
||||
const { sentry, terminal } = createProbeSentry();
|
||||
for (let i = 0; i < stream.length; i += chunkSize) {
|
||||
sentry.consume(stream.subarray(i, i + chunkSize));
|
||||
}
|
||||
assert.equal(
|
||||
joinedText(terminal),
|
||||
"root@host:~$ ",
|
||||
`split ZRINIT preamble leaked for chunkSize=${chunkSize}`,
|
||||
);
|
||||
assertNoZmodemHeaderBytes(terminal, `rz chunkSize=${chunkSize}`);
|
||||
}
|
||||
});
|
||||
|
||||
test("bytes withheld as a header fragment are flushed after the TTL", async () => {
|
||||
const { sentry, terminal } = createProbeSentry();
|
||||
const stream = Buffer.from("hello *");
|
||||
for (const byte of stream) sentry.consume(Buffer.from([byte]));
|
||||
|
||||
// The trailing "*" may be the start of a hex header, so it is withheld.
|
||||
assert.equal(joinedText(terminal), "hello ");
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 80));
|
||||
assert.equal(joinedText(terminal), "hello *", "TTL flush must not lose terminal output");
|
||||
});
|
||||
|
||||
test("a header completed after the TTL flush still leaks no hex bytes", async () => {
|
||||
const { sentry, terminal } = createProbeSentry();
|
||||
const header = buildHexHeaderBytes("ZRQINIT");
|
||||
|
||||
// A stall splits the header right after its first byte; the TTL then
|
||||
// flushes the withheld "*" to the terminal before the remainder arrives.
|
||||
sentry.consume(header.subarray(0, 1));
|
||||
assert.equal(joinedText(terminal), "");
|
||||
await new Promise((resolve) => setTimeout(resolve, 80));
|
||||
assert.equal(joinedText(terminal), "*", "TTL flush must not lose terminal output");
|
||||
|
||||
// The remainder arrives only now (network stall). It must be merged with
|
||||
// the flushed prefix, recognized as a complete header and stripped — most
|
||||
// of its hex/control bytes must not reach the terminal.
|
||||
for (let i = 1; i < header.length; i += 1) {
|
||||
sentry.consume(header.subarray(i, i + 1));
|
||||
}
|
||||
sentry.consume(Buffer.from("$ "));
|
||||
assert.equal(joinedText(terminal), "*$ ", "header remainder leaked after TTL flush");
|
||||
assertNoZmodemHeaderBytes(terminal, "post-flush header completion");
|
||||
});
|
||||
|
||||
test("output that disproves a header fragment is emitted without delay", () => {
|
||||
const stream = Buffer.from("text **\x18Bxy more");
|
||||
for (let chunkSize = 1; chunkSize <= 6; chunkSize += 1) {
|
||||
const { sentry, terminal } = createProbeSentry();
|
||||
for (let i = 0; i < stream.length; i += chunkSize) {
|
||||
sentry.consume(stream.subarray(i, i + chunkSize));
|
||||
}
|
||||
assert.equal(
|
||||
joinedText(terminal),
|
||||
"text **\x18Bxy more",
|
||||
"a non-hex byte after the pattern stops the deferral",
|
||||
);
|
||||
}
|
||||
});
|
||||
Reference in new issue
Block a user