diff options
Diffstat (limited to '')
| -rw-r--r-- | src/encode.js | 124 | ||||
| -rw-r--r-- | src/text.js | 33 | ||||
| -rw-r--r-- | src/zcrc.js | 143 | ||||
| -rw-r--r-- | src/zdle.js | 240 | ||||
| -rw-r--r-- | src/zerror.js | 47 | ||||
| -rw-r--r-- | src/zheader.js | 763 | ||||
| -rw-r--r-- | src/zmlib.js | 102 | ||||
| -rw-r--r-- | src/zmodem.js | 4 | ||||
| -rw-r--r-- | src/zmodem_browser.js | 182 | ||||
| -rw-r--r-- | src/zsentry.js | 394 | ||||
| -rw-r--r-- | src/zsession.js | 1677 | ||||
| -rw-r--r-- | src/zsubpacket.js | 241 | ||||
| -rw-r--r-- | src/zvalidation.js | 130 |
13 files changed, 4080 insertions, 0 deletions
diff --git a/src/encode.js b/src/encode.js new file mode 100644 index 0000000..5cb6344 --- /dev/null +++ b/src/encode.js @@ -0,0 +1,124 @@ +"use strict"; + +var Zmodem = module.exports; + +const HEX_DIGITS = [ 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 97, 98, 99, 100, 101, 102 ]; + +const HEX_OCTET_VALUE = {}; +for (var hd=0; hd<HEX_DIGITS.length; hd++) { + HEX_OCTET_VALUE[ HEX_DIGITS[hd] ] = hd; +} + +/** + * General, non-ZMODEM-specific encoding logic. + * + * @exports ENCODELIB + */ +Zmodem.ENCODELIB = { + + /** + * Return an array with the given number as 2 big-endian bytes. + * + * @param {number} number - The number to encode. + * + * @returns {number[]} The octet values. + */ + pack_u16_be: function pack_u16_be(number) { + if (number > 0xffff) throw( "Number cannot exceed 16 bits: " + number ) + + return [ number >> 8, number & 0xff ]; + }, + + /** + * Return an array with the given number as 4 little-endian bytes. + * + * @param {number} number - The number to encode. + * + * @returns {number[]} The octet values. + */ + pack_u32_le: function pack_u32_le(number) { + //Can’t bit-shift because that runs into JS’s bit-shift problem. + //(See _updcrc32() for an example.) + var high_bytes = number / 65536; //fraction is ok + + //a little-endian 4-byte sequence + return [ + number & 0xff, + (number & 65535) >> 8, + high_bytes & 0xff, + high_bytes >> 8, + ]; + }, + + /** + * The inverse of pack_u16_be() - i.e., take in 2 octet values + * and parse them as an unsigned, 2-byte big-endian number. + * + * @param {number[]} octets - The octet values (2 of them). + * + * @returns {number} The decoded number. + */ + unpack_u16_be: function unpack_u16_be(bytes_arr) { + return (bytes_arr[0] << 8) + bytes_arr[1]; + }, + + /** + * The inverse of pack_u32_le() - i.e., take in a 4-byte sequence + * and parse it as an unsigned, 4-byte little-endian number. + * + * @param {number[]} octets - The octet values (4 of them). + * + * @returns {number} The decoded number. + */ + unpack_u32_le: function unpack_u32_le(octets) { + //<sigh> … (254 << 24 is -33554432, according to JavaScript) + return octets[0] + (octets[1] << 8) + (octets[2] << 16) + (octets[3] * 16777216); + }, + + /** + * Encode a series of octet values to be the octet values that + * correspond to the ASCII hex characters for each octet. The + * returned array is suitable for use as binary data. + * + * For example: + * + * Original Hex Returned + * 254 fe 102, 101 + * 12 0c 48, 99 + * 129 81 56, 49 + * + * @param {number[]} octets - The original octet values. + * + * @returns {number[]} The octet values that correspond to an ASCII + * representation of the given octets. + */ + octets_to_hex: function octets_to_hex(octets) { + var hex = []; + for (var o=0; o<octets.length; o++) { + hex.push( + HEX_DIGITS[ octets[o] >> 4 ], + HEX_DIGITS[ octets[o] & 0x0f ] + ); + } + + return hex; + }, + + /** + * The inverse of octets_to_hex(): takes an array + * of hex octet pairs and returns their octet values. + * + * @param {number[]} hex_octets - The hex octet values. + * + * @returns {number[]} The parsed octet values. + */ + parse_hex_octets: function parse_hex_octets(hex_octets) { + var octets = new Array(hex_octets.length / 2); + + for (var i=0; i<octets.length; i++) { + octets[i] = (HEX_OCTET_VALUE[ hex_octets[2 * i] ] << 4) + HEX_OCTET_VALUE[ hex_octets[1 + 2 * i] ]; + } + + return octets; + }, +}; diff --git a/src/text.js b/src/text.js new file mode 100644 index 0000000..d267817 --- /dev/null +++ b/src/text.js @@ -0,0 +1,33 @@ +class _my_TextEncoder { + encode(text) { + text = unescape(encodeURIComponent(text)); + + var bytes = new Array( text.length ); + + for (var b = 0; b < text.length; b++) { + bytes[b] = text.charCodeAt(b); + } + + return new Uint8Array(bytes); + } +} + +class _my_TextDecoder { + decode(bytes) { + return decodeURIComponent( escape( String.fromCharCode.apply(String, bytes) ) ); + } +} + +var Zmodem = module.exports; + +/** + * A limited-use compatibility shim for TextEncoder and TextDecoder. + * Useful because both Edge and node.js still lack support for these + * as of October 2017. + * + * @exports Text + */ +Zmodem.Text = { + Encoder: (typeof TextEncoder !== "undefined") ? TextEncoder : _my_TextEncoder, + Decoder: (typeof TextDecoder !== "undefined") ? TextDecoder : _my_TextDecoder, +}; diff --git a/src/zcrc.js b/src/zcrc.js new file mode 100644 index 0000000..831f835 --- /dev/null +++ b/src/zcrc.js @@ -0,0 +1,143 @@ +"use strict"; + +const CRC32_MOD = require('crc-32'); + +var Zmodem = module.exports; + +Object.assign( + Zmodem, + require("./zerror"), + require("./encode") +); + +//---------------------------------------------------------------------- +// BEGIN adapted from crc-js by Johannes Rudolph + +var _crctab; + +const + crc_width = 16, + crc_polynomial = 0x1021, + crc_castmask = 0xffff, + crc_msbmask = 1 << (crc_width - 1) +; + +function _compute_crctab() { + _crctab = new Array(256); + + var divident_shift = crc_width - 8; + + for (var divident = 0; divident < 256; divident++) { + var currByte = (divident << divident_shift) & crc_castmask; + + for (var bit = 0; bit < 8; bit++) { + + if ((currByte & crc_msbmask) !== 0) { + currByte <<= 1; + currByte ^= crc_polynomial; + } + else { + currByte <<= 1; + } + } + + _crctab[divident] = (currByte & crc_castmask); + } +} + +// END adapted from crc-js by Johannes Rudolph +//---------------------------------------------------------------------- + +function _updcrc(cp, crc) { + if (!_crctab) _compute_crctab(); + + return( + _crctab[((crc >> 8) & 255)] + ^ ((255 & crc) << 8) + ^ cp + ); +} + +function __verify(expect, got) { + var err; + + if ( expect.join() !== got.join() ) { + throw new Zmodem.Error("crc", got, expect); + } +} + +//TODO: use external implementation(s) +Zmodem.CRC = { + + //https://www.lammertbies.nl/comm/info/crc-calculation.html + //CRC-CCITT (XModem) + + /** + * Deduce a given set of octet values’ CRC16, as per the CRC16 + * variant that ZMODEM uses (CRC-CCITT/XModem). + * + * @param {Array} octets - The array of octet values. + * Each array member should be an 8-bit unsigned integer (0-255). + * + * @returns {Array} crc - The CRC, expressed as an array of octet values. + */ + crc16: function crc16(octet_nums) { + var crc = octet_nums[0]; + for (var b=1; b<octet_nums.length; b++) { + crc = _updcrc( octet_nums[b], crc ); + } + + crc = _updcrc( 0, _updcrc(0, crc) ); + + //a big-endian 2-byte sequence + return Zmodem.ENCODELIB.pack_u16_be(crc); + }, + + /** + * Deduce a given set of octet values’ CRC32. + * + * @param {Array} octets - The array of octet values. + * Each array member should be an 8-bit unsigned integer (0-255). + * + * @returns {Array} crc - The CRC, expressed as an array of octet values. + */ + crc32: function crc32(octet_nums) { + return Zmodem.ENCODELIB.pack_u32_le( + CRC32_MOD.buf(octet_nums) >>> 0 //bit-shift to get unsigned + ); + }, + + /** + * Verify a given set of octet values’ CRC16. + * An exception is thrown on failure. + * + * @param {Array} bytes_arr - The array of octet values. + * Each array member should be an 8-bit unsigned integer (0-255). + * + * @param {Array} crc - The CRC to check against, expressed as + * an array of octet values. + */ + verify16: function verify16(bytes_arr, got) { + return __verify( this.crc16(bytes_arr), got ); + }, + + /** + * Verify a given set of octet values’ CRC32. + * An exception is thrown on failure. + * + * @param {Array} bytes_arr - The array of octet values. + * Each array member should be an 8-bit unsigned integer (0-255). + * + * @param {Array} crc - The CRC to check against, expressed as + * an array of octet values. + */ + verify32: function verify32(bytes_arr, crc) { + try { + __verify( this.crc32(bytes_arr), crc ); + } + catch(err) { + err.input = bytes_arr.slice(0); + throw err; + } + }, +}; diff --git a/src/zdle.js b/src/zdle.js new file mode 100644 index 0000000..989222e --- /dev/null +++ b/src/zdle.js @@ -0,0 +1,240 @@ +"use strict"; + +var Zmodem = module.exports; + +Object.assign( + Zmodem, + require("./zmlib") +); + +//encode() variables - declare them here so we don’t +//create them in the function. +var encode_cur, encode_todo; + +const ZDLE = Zmodem.ZMLIB.ZDLE; + +/** + * Class that handles ZDLE encoding and decoding. + * Encoding is subject to a given configuration--specifically, whether + * we want to escape all control characters. Decoding is static; however + * a given string is encoded we can always decode it. + */ +Zmodem.ZDLE = class ZmodemZDLE { + /** + * Create a ZDLE encoder. + * + * @param {object} [config] - The initial configuration. + * @param {object} config.escape_ctrl_chars - Whether the ZDLE encoder + * should escape control characters. + */ + constructor(config) { + this._config = {}; + if (config) { + this.set_escape_ctrl_chars(!!config.escape_ctrl_chars); + } + } + + /** + * Enable or disable control-character escaping. + * You should probably enable this for sender sessions. + * + * @param {boolean} value - Whether to enable (true) or disable (false). + */ + set_escape_ctrl_chars(value) { + if (typeof value !== "boolean") throw "need boolean!"; + + if (value !== this._config.escape_ctrl_chars) { + this._config.escape_ctrl_chars = value; + this._setup_zdle_table(); + } + } + + /** + * Whether or not control-character escaping is enabled. + * + * @return {boolean} Whether the escaping is on (true) or off (false). + */ + escapes_ctrl_chars() { + return !!this._config.escape_ctrl_chars; + } + + //I don’t know of any Zmodem implementations that use ZESC8 + //(“escape_8th_bit”)?? + + /* + ZMODEM software escapes ZDLE, 020, 0220, 021, 0221, 023, and 0223. If + preceded by 0100 or 0300 (@), 015 and 0215 are also escaped to protect the + Telenet command escape CR-@-CR. + */ + + /** + * Encode an array of octet values and return it. + * This will mutate the given array. + * + * @param {number[]} octets - The octet values to transform. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @returns {number[]} The passed-in array, transformed. This is the + * same object that is passed in. + */ + encode(octets) { + //NB: Performance matters here! + + if (!this._zdle_table) throw "No ZDLE encode table configured!"; + + var zdle_table = this._zdle_table; + + var last_code = this._lastcode; + + var arrbuf = new ArrayBuffer( 2 * octets.length ); + var arrbuf_uint8 = new Uint8Array(arrbuf); + + var escctl_yn = this._config.escape_ctrl_chars; + + var arrbuf_i = 0; + + for (encode_cur=0; encode_cur<octets.length; encode_cur++) { + + encode_todo = zdle_table[octets[encode_cur]]; + if (!encode_todo) { + console.trace(); + console.error("bad encode() call:", JSON.stringify(octets)); + this._lastcode = last_code; + throw( "Invalid octet: " + octets[encode_cur] ); + } + + last_code = octets[encode_cur]; + + if (encode_todo === 1) { + //Do nothing; we append last_code below. + } + + //0x40 = '@'; i.e., only escape if the last + //octet was '@'. + else if (escctl_yn || (encode_todo === 2) || ((last_code & 0x7f) === 0x40)) { + arrbuf_uint8[arrbuf_i] = ZDLE; + arrbuf_i++; + + last_code ^= 0x40; //0100 + } + + arrbuf_uint8[arrbuf_i] = last_code; + + arrbuf_i++; + } + + this._lastcode = last_code; + + octets.splice(0); + octets.push.apply(octets, new Uint8Array( arrbuf, 0, arrbuf_i )); + + return octets; + } + + /** + * Decode an array of octet values and return it. + * This will mutate the given array. + * + * @param {number[]} octets - The octet values to transform. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @returns {number[]} The passed-in array. + * This is the same object that is passed in. + */ + static decode(octets) { + for (var o=octets.length-1; o>=0; o--) { + if (octets[o] === ZDLE) { + octets.splice( o, 2, octets[o+1] - 64 ); + } + } + + return octets; + } + + /** + * Remove, ZDLE-decode, and return bytes from the passed-in array. + * If the requested number of ZDLE-encoded bytes isn’t available, + * then the passed-in array is unmodified (and the return is undefined). + * + * @param {number[]} octets - The octet values to transform. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @param {number} offset - The number of (undecoded) bytes to skip + * at the beginning of the “octets” array. + * + * @param {number} count - The number of bytes (octet values) to return. + * + * @returns {number[]|undefined} An array with the requested number of + * decoded octet values, or undefined if that number of decoded + * octets isn’t available (given the passed-in offset). + */ + static splice(octets, offset, count) { + var so_far = 0; + + if (!offset) offset = 0; + + for (var i = offset; i<octets.length && so_far<count; i++) { + so_far++; + + if (octets[i] === ZDLE) i++; + } + + if (so_far === count) { + + //Don’t accept trailing ZDLE. This check works + //because of the i++ logic above. + if (octets.length === (i - 1)) return; + + octets.splice(0, offset); + return ZmodemZDLE.decode( octets.splice(0, i - offset) ); + } + + return; + } + + _setup_zdle_table() { + var zsendline_tab = new Array(256); + for (var i=0; i<zsendline_tab.length; i++) { + + //1 = never escape + //2 = always escape + //3 = escape only if the previous byte was '@' + + //Never escape characters from 0x20 (32) to 0x7f (127). + //This is the range of printable characters, plus DEL. + //I guess ZMODEM doesn’t consider DEL to be a control character? + if ( i & 0x60 ) { + zsendline_tab[i] = 1; + } + else { + switch(i) { + case ZDLE: //NB: no (ZDLE | 0x80) + case Zmodem.ZMLIB.XOFF: + case Zmodem.ZMLIB.XON: + case (Zmodem.ZMLIB.XOFF | 0x80): + case (Zmodem.ZMLIB.XON | 0x80): + zsendline_tab[i] = 2; + break; + + case 0x10: // 020 + case 0x90: // 0220 + zsendline_tab[i] = this._config.turbo_escape ? 1 : 2; + break; + + case 0x0d: // 015 + case 0x8d: // 0215 + zsendline_tab[i] = this._config.escape_ctrl_chars ? 2 : !this._config.turbo_escape ? 3 : 1; + break; + + default: + zsendline_tab[i] = this._config.escape_ctrl_chars ? 2 : 1; + } + } + } + + this._zdle_table = zsendline_tab; + } +} diff --git a/src/zerror.js b/src/zerror.js new file mode 100644 index 0000000..1a779de --- /dev/null +++ b/src/zerror.js @@ -0,0 +1,47 @@ +"use strict"; + +var Zmodem = module.exports; + +function _crc_message(got, expected) { + this.got = got.slice(0); + this.expected = expected.slice(0); + return "CRC check failed! (got: " + got.join() + "; expected: " + expected.join() + ")"; +} + +function _pass(val) { return val } + +const TYPE_MESSAGE = { + aborted: "Session aborted", + peer_aborted: "Peer aborted session", + already_aborted: "Session already aborted", + crc: _crc_message, + validation: _pass, +}; + +function _generate_message(type) { + const msg = TYPE_MESSAGE[type]; + switch (typeof msg) { + case "string": + return msg; + case "function": + var args_after_type = [].slice.call(arguments).slice(1); + return msg.apply(this, args_after_type); + } + + return null; +} + +Zmodem.Error = class ZmodemError extends Error { + constructor(msg_or_type) { + super(); + + var generated = _generate_message.apply(this, arguments); + if (generated) { + this.type = msg_or_type; + this.message = generated; + } + else { + this.message = msg_or_type; + } + } +}; diff --git a/src/zheader.js b/src/zheader.js new file mode 100644 index 0000000..56c22fc --- /dev/null +++ b/src/zheader.js @@ -0,0 +1,763 @@ +"use strict"; + +var Zmodem = module.exports; + +Object.assign( + Zmodem, + require("./encode"), + require("./zdle"), + require("./zmlib"), + require("./zcrc"), + require("./zerror") +); + +const ZPAD = '*'.charCodeAt(0), + ZBIN = 'A'.charCodeAt(0), + ZHEX = 'B'.charCodeAt(0), + ZBIN32 = 'C'.charCodeAt(0) +; + +//NB: lrzsz uses \x8a rather than \x0a where the specs +//say to use LF. For simplicity, we avoid that and just use +//the 7-bit LF character. +const HEX_HEADER_CRLF = [ 0x0d, 0x0a ]; +const HEX_HEADER_CRLF_XON = HEX_HEADER_CRLF.slice(0).concat( [Zmodem.ZMLIB.XON] ); + +//These are more or less duplicated by the logic in trim_leading_garbage(). +// +//"**" + ZDLE_CHAR + "B" +const HEX_HEADER_PREFIX = [ ZPAD, ZPAD, Zmodem.ZMLIB.ZDLE, ZHEX ]; +const BINARY16_HEADER_PREFIX = [ ZPAD, Zmodem.ZMLIB.ZDLE, ZBIN ]; +const BINARY32_HEADER_PREFIX = [ ZPAD, Zmodem.ZMLIB.ZDLE, ZBIN32 ]; + +/** Class that represents a ZMODEM header. */ +Zmodem.Header = class ZmodemHeader { + + //lrzsz’s “sz” command sends a random (?) CR/0x0d byte + //after ZEOF. Let’s accommodate 0x0a, 0x0d, 0x8a, and 0x8d. + // + //Also, when you skip a file, sz outputs a message about it. + // + //It appears that we’re supposed to ignore anything until + //[ ZPAD, ZDLE ] when we’re looking for a header. + + /** + * Weed out the leading bytes that aren’t valid to start a ZMODEM header. + * + * @param {number[]} ibuffer - The octet values to parse. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @returns {number[]} The octet values that were removed from the start + * of “ibuffer”. Order is preserved. + */ + static trim_leading_garbage(ibuffer) { + //Since there’s no escaping of the output it’s possible + //that the garbage could trip us up, e.g., by having a filename + //be a legit ZMODEM header. But that’s pretty unlikely. + + //Everything up to the first ZPAD: garbage + //If first ZPAD has asterisk + ZDLE + + var garbage = []; + + var discard_all, parser, next_ZPAD_at_least = 0; + + TRIM_LOOP: + while (ibuffer.length && !parser) { + var first_ZPAD = ibuffer.indexOf(ZPAD); + + //No ZPAD? Then we purge the input buffer cuz it’s all garbage. + if (first_ZPAD === -1) { + discard_all = true; + break TRIM_LOOP; + } + else { + garbage.push.apply( garbage, ibuffer.splice(0, first_ZPAD) ); + + //buffer has only an asterisk … gotta see about more + if (ibuffer.length < 2) { + break TRIM_LOOP; + } + else if (ibuffer[1] === ZPAD) { + //Two leading ZPADs should be a hex header. + + //We’re assuming the length of the header is 4 in + //this logic … but ZMODEM isn’t likely to change, so. + if (ibuffer.length < HEX_HEADER_PREFIX.length) { + if (ibuffer.join() === HEX_HEADER_PREFIX.slice(0, ibuffer.length).join()) { + //We have an incomplete fragment that matches + //HEX_HEADER_PREFIX. So don’t trim any more. + break TRIM_LOOP; + } + + //Otherwise, we’ll discard one. + } + else if ((ibuffer[2] === HEX_HEADER_PREFIX[2]) && (ibuffer[3] === HEX_HEADER_PREFIX[3])) { + parser = _parse_hex; + } + } + else if (ibuffer[1] === Zmodem.ZMLIB.ZDLE) { + //ZPAD + ZDLE should be a binary header. + if (ibuffer.length < BINARY16_HEADER_PREFIX.length) { + break TRIM_LOOP; + } + + if (ibuffer[2] === BINARY16_HEADER_PREFIX[2]) { + parser = _parse_binary16; + } + else if (ibuffer[2] === BINARY32_HEADER_PREFIX[2]) { + parser = _parse_binary32; + } + } + + if (!parser) { + garbage.push( ibuffer.shift() ); + } + } + } + + if (discard_all) { + garbage.push.apply( garbage, ibuffer.splice(0) ); + } + + //For now we’ll throw away the parser. + //It’s not hard for parse() to discern anyway. + + return garbage; + } + + /** + * Parse out a Header object from a given array of octet values. + * + * An exception is thrown if the given bytes are definitively invalid + * as header values. + * + * @param {number[]} octets - The octet values to parse. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @returns {Header|undefined} An instance of the appropriate Header + * subclass, or undefined if not enough octet values are given + * to determine whether there is a valid header here or not. + */ + static parse(octets) { + var hdr; + if (octets[1] === ZPAD) { + hdr = _parse_hex(octets); + return hdr && [ hdr, 16 ]; + } + + else if (octets[2] === ZBIN) { + hdr = _parse_binary16(octets, 3); + return hdr && [ hdr, 16 ]; + } + + else if (octets[2] === ZBIN32) { + hdr = _parse_binary32(octets); + return hdr && [ hdr, 32 ]; + } + + if (octets.length < 3) return; + + throw( "Unrecognized/unsupported octets: " + octets.join() ); + } + + /** + * Build a Header subclass given a name and arguments. + * + * @param {string} name - The header type name, e.g., “ZRINIT”. + * + * @param {...*} args - The arguments to pass to the appropriate + * subclass constructor. These aren’t documented currently + * but are pretty easy to glean from the code. + * + * @returns {Header} An instance of the appropriate Header subclass. + */ + static build(name /*, args */) { + var args = (arguments.length === 1 ? [arguments[0]] : Array.apply(null, arguments)); + + //TODO: make this better + var Ctr = FRAME_NAME_CREATOR[name]; + if (!Ctr) throw("No frame class “" + name + "” is defined!"); + + args.shift(); + + //Plegh! + //https://stackoverflow.com/questions/33193310/constr-applythis-args-in-es6-classes + var hdr = new (Ctr.bind.apply(Ctr, [null].concat(args))); + + return hdr; + } + + /** + * Return the octet values array that represents the object + * in ZMODEM hex encoding. + * + * @returns {number[]} An array of octet values suitable for sending + * as binary data. + */ + to_hex() { + var to_crc = this._crc_bytes(); + + return HEX_HEADER_PREFIX.concat( + Zmodem.ENCODELIB.octets_to_hex( to_crc.concat( Zmodem.CRC.crc16(to_crc) ) ), + this._hex_header_ending + ); + } + + /** + * Return the octet values array that represents the object + * in ZMODEM binary encoding with a 16-bit CRC. + * + * @param {ZDLE} zencoder - A ZDLE instance to use for + * ZDLE encoding. + * + * @returns {number[]} An array of octet values suitable for sending + * as binary data. + */ + to_binary16(zencoder) { + return this._to_binary(zencoder, BINARY16_HEADER_PREFIX, Zmodem.CRC.crc16); + } + + /** + * Return the octet values array that represents the object + * in ZMODEM binary encoding with a 32-bit CRC. + * + * @param {ZDLE} zencoder - A ZDLE instance to use for + * ZDLE encoding. + * + * @returns {number[]} An array of octet values suitable for sending + * as binary data. + */ + to_binary32(zencoder) { + return this._to_binary(zencoder, BINARY32_HEADER_PREFIX, Zmodem.CRC.crc32); + } + + //This is never called directly, but only as super(). + constructor() { + if (!this._bytes4) { + this._bytes4 = [0, 0, 0, 0]; + } + } + + _to_binary(zencoder, prefix, crc_func) { + var to_crc = this._crc_bytes(); + + //Both the 4-byte payload and the CRC bytes are ZDLE-encoded. + var octets = prefix.concat( + zencoder.encode( to_crc.concat( crc_func(to_crc) ) ) + ); + + return octets; + } + + _crc_bytes() { + return [ this.TYPENUM ].concat(this._bytes4); + } +} +Zmodem.Header.prototype._hex_header_ending = HEX_HEADER_CRLF_XON; + +class ZRQINIT_HEADER extends Zmodem.Header {}; + +//---------------------------------------------------------------------- + +const ZRINIT_FLAG = { + + //---------------------------------------------------------------------- + // Bit Masks for ZRINIT flags byte ZF0 + //---------------------------------------------------------------------- + CANFDX: 0x01, // Rx can send and receive true FDX + CANOVIO: 0x02, // Rx can receive data during disk I/O + CANBRK: 0x04, // Rx can send a break signal + CANCRY: 0x08, // Receiver can decrypt -- nothing does this + CANLZW: 0x10, // Receiver can uncompress -- nothing does this + CANFC32: 0x20, // Receiver can use 32 bit Frame Check + ESCCTL: 0x40, // Receiver expects ctl chars to be escaped + ESC8: 0x80, // Receiver expects 8th bit to be escaped +}; + +function _get_ZRINIT_flag_num(fl) { + if (!ZRINIT_FLAG[fl]) { + throw new Zmodem.Error("Invalid ZRINIT flag: " + fl); + } + return ZRINIT_FLAG[fl]; +} + +class ZRINIT_HEADER extends Zmodem.Header { + constructor(flags_arr, bufsize) { + super(); + var flags_num = 0; + if (!bufsize) bufsize = 0; + + flags_arr.forEach( function(fl) { + flags_num |= _get_ZRINIT_flag_num(fl); + } ); + + this._bytes4 = [ + bufsize & 0xff, + bufsize >> 8, + 0, + flags_num, + ]; + } + + //undefined if nonstop I/O is allowed + get_buffer_size() { + return Zmodem.ENCODELIB.unpack_u16_be( this._bytes4.slice(0, 2) ) || undefined; + } + + //Unimplemented: + // can_decrypt + // can_decompress + + //---------------------------------------------------------------------- + //function names taken from Jacques Mattheij’s implementation, + //as used in syncterm. + + can_full_duplex() { + return !!( this._bytes4[3] & ZRINIT_FLAG.CANFDX ); + } + + can_overlap_io() { + return !!( this._bytes4[3] & ZRINIT_FLAG.CANOVIO ); + } + + can_break() { + return !!( this._bytes4[3] & ZRINIT_FLAG.CANBRK ); + } + + can_fcs_32() { + return !!( this._bytes4[3] & ZRINIT_FLAG.CANFC32 ); + } + + escape_ctrl_chars() { + return !!( this._bytes4[3] & ZRINIT_FLAG.ESCCTL ); + } + + //Is this used? I don’t see it used in lrzsz or syncterm + //Looks like it was a “foreseen” feature that Forsberg + //never implemented. (The need for it went away, maybe?) + escape_8th_bit() { + return !!( this._bytes4[3] & ZRINIT_FLAG.ESC8 ); + } +}; + +//---------------------------------------------------------------------- + +//Since context makes clear what’s going on, we use these +//rather than the T-prefixed constants in the specification. +const ZSINIT_FLAG = { + ESCCTL: 0x40, // Transmitter will escape ctl chars + ESC8: 0x80, // Transmitter will escape 8th bit +}; + +function _get_ZSINIT_flag_num(fl) { + if (!ZSINIT_FLAG[fl]) { + throw("Invalid ZSINIT flag: " + fl); + } + return ZSINIT_FLAG[fl]; +} + +class ZSINIT_HEADER extends Zmodem.Header { + constructor( flags_arr, attn_seq_arr ) { + super(); + var flags_num = 0; + + flags_arr.forEach( function(fl) { + flags_num |= _get_ZSINIT_flag_num(fl); + } ); + + this._bytes4 = [ 0, 0, 0, flags_num ]; + + if (attn_seq_arr) { + if (attn_seq_arr.length > 31) { + throw("Attn sequence must be <= 31 bytes"); + } + if (attn_seq_arr.some( function(num) { return num > 255 } )) { + throw("Attn sequence (" + attn_seq_arr + ") must be <256"); + } + this._data = attn_seq_arr.concat([0]); + } + } + + escape_ctrl_chars() { + return !!( this._bytes4[3] & ZSINIT_FLAG.ESCCTL ); + } + + //Is this used? I don’t see it used in lrzsz or syncterm + escape_8th_bit() { + return !!( this._bytes4[3] & ZSINIT_FLAG.ESC8 ); + } +} + +//Thus far it doesn’t seem we really need this header except to respond +//to ZSINIT, which doesn’t require a payload. +class ZACK_HEADER extends Zmodem.Header { + constructor(payload4) { + super(); + + if (payload4) { + this._bytes4 = payload4.slice(); + } + } +} +ZACK_HEADER.prototype._hex_header_ending = HEX_HEADER_CRLF; + +//---------------------------------------------------------------------- + +const ZFILE_VALUES = { + + //ZF3 (i.e., first byte) + extended: { + sparse: 0x40, //ZXSPARS + }, + + //ZF2 + transport: [ + undefined, + "compress", //ZTLZW + "encrypt", //ZTCRYPT + "rle", //ZTRLE + ], + + //ZF1 + management: [ + undefined, + "newer_or_longer", //ZF1_ZMNEWL + "crc", //ZF1_ZMCRC + "append", //ZF1_ZMAPND + "clobber", //ZF1_ZMCLOB + "newer", //ZF1_ZMNEW + "mtime_or_length", //ZF1_ZMNEW + "protect", //ZF1_ZMPROT + "rename", //ZF1_ZMPROT + ], + + //ZF0 (i.e., last byte) + conversion: [ + undefined, + "binary", //ZCBIN + "text", //ZCNL + "resume", //ZCRESUM + ], +}; + +const ZFILE_ORDER = ["extended", "transport", "management", "conversion"]; + +const ZMSKNOLOC = 0x80, + MANAGEMENT_MASK = 0x1f, + ZXSPARS = 0x40 +; + +class ZFILE_HEADER extends Zmodem.Header { + + //TODO: allow options on instantiation + get_options() { + var opts = { + sparse: !!(this._bytes4[0] & ZXSPARS), + }; + + var bytes_copy = this._bytes4.slice(0); + + ZFILE_ORDER.forEach( function(key, i) { + if (ZFILE_VALUES[key] instanceof Array) { + if (key === "management") { + opts.skip_if_absent = !!(bytes_copy[i] & ZMSKNOLOC); + bytes_copy[i] &= MANAGEMENT_MASK; + } + + opts[key] = ZFILE_VALUES[key][ bytes_copy[i] ]; + } + else { + for (var extkey in ZFILE_VALUES[key]) { + opts[extkey] = !!(bytes_copy[i] & ZFILE_VALUES[key][extkey]); + if (opts[extkey]) { + bytes_copy[i] ^= ZFILE_VALUES[key][extkey] + } + } + } + + if (!opts[key] && bytes_copy[i]) { + opts[key] = "unknown:" + bytes_copy[i]; + } + } ); + + return opts; + } +} + +//---------------------------------------------------------------------- + +//Empty headers - in addition to ZRQINIT +class ZSKIP_HEADER extends Zmodem.Header {} +//No need for ZNAK +class ZABORT_HEADER extends Zmodem.Header {} +class ZFIN_HEADER extends Zmodem.Header {} +class ZFERR_HEADER extends Zmodem.Header {} + +ZFIN_HEADER.prototype._hex_header_ending = HEX_HEADER_CRLF; + +class ZOffsetHeader extends Zmodem.Header { + constructor(offset) { + super(); + this._bytes4 = Zmodem.ENCODELIB.pack_u32_le(offset); + } + + get_offset() { + return Zmodem.ENCODELIB.unpack_u32_le(this._bytes4); + } +} + +class ZRPOS_HEADER extends ZOffsetHeader {}; +class ZDATA_HEADER extends ZOffsetHeader {}; +class ZEOF_HEADER extends ZOffsetHeader {}; + +//As request, receiver creates. +/* UNIMPLEMENTED FOR NOW +class ZCRC_HEADER extends ZHeader { + constructor(crc_le_bytes) { + super(); + if (crc_le_bytes) { //response, sender creates + this._bytes4 = crc_le_bytes; + } + } +} +*/ + +//No ZCHALLENGE implementation + +//class ZCOMPL_HEADER extends ZHeader {} +//class ZCAN_HEADER extends Zmodem.Header {} + +//As described, this header represents an information disclosure. +//It could be interpreted, I suppose, merely as “this is how much space +//I have FOR YOU.” +//TODO: implement if needed/requested +//class ZFREECNT_HEADER extends ZmodemHeader {} + +//---------------------------------------------------------------------- + +const FRAME_CLASS_TYPES = [ + [ ZRQINIT_HEADER, "ZRQINIT" ], + [ ZRINIT_HEADER, "ZRINIT" ], + [ ZSINIT_HEADER, "ZSINIT" ], + [ ZACK_HEADER, "ZACK" ], + [ ZFILE_HEADER, "ZFILE" ], + [ ZSKIP_HEADER, "ZSKIP" ], + undefined, // [ ZNAK_HEADER, "ZNAK" ], + [ ZABORT_HEADER, "ZABORT" ], + [ ZFIN_HEADER, "ZFIN" ], + [ ZRPOS_HEADER, "ZRPOS" ], + [ ZDATA_HEADER, "ZDATA" ], + [ ZEOF_HEADER, "ZEOF" ], + [ ZFERR_HEADER, "ZFERR" ], //see note + undefined, //[ ZCRC_HEADER, "ZCRC" ], + undefined, //[ ZCHALLENGE_HEADER, "ZCHALLENGE" ], + undefined, //[ ZCOMPL_HEADER, "ZCOMPL" ], + undefined, //[ ZCAN_HEADER, "ZCAN" ], + undefined, //[ ZFREECNT_HEADER, "ZFREECNT" ], + undefined, //[ ZCOMMAND_HEADER, "ZCOMMAND" ], + undefined, //[ ZSTDERR_HEADER, "ZSTDERR" ], +]; + +/* +ZFERR is described as “error in reading or writing file”. It’s really +not a good idea from a security angle for the endpoint to expose this +information. We should parse this and handle it as ZABORT but never send it. + +Likewise with ZFREECNT: the sender shouldn’t ask how much space is left +on the other box; rather, the receiver should decide what to do with the +file size as the sender reports it. +*/ + +var FRAME_NAME_CREATOR = {}; + +for (var fc=0; fc<FRAME_CLASS_TYPES.length; fc++) { + if (!FRAME_CLASS_TYPES[fc]) continue; + + FRAME_NAME_CREATOR[ FRAME_CLASS_TYPES[fc][1] ] = FRAME_CLASS_TYPES[fc][0]; + + Object.assign( + FRAME_CLASS_TYPES[fc][0].prototype, + { + TYPENUM: fc, + NAME: FRAME_CLASS_TYPES[fc][1], + } + ); +} + +//---------------------------------------------------------------------- + +const CREATORS = [ + ZRQINIT_HEADER, + ZRINIT_HEADER, + ZSINIT_HEADER, + ZACK_HEADER, + ZFILE_HEADER, + ZSKIP_HEADER, + 'ZNAK', + ZABORT_HEADER, + ZFIN_HEADER, + ZRPOS_HEADER, + ZDATA_HEADER, + ZEOF_HEADER, + ZFERR_HEADER, + 'ZCRC', //ZCRC_HEADER, -- leaving unimplemented? + 'ZCHALLENGE', + 'ZCOMPL', + 'ZCAN', + 'ZFREECNT', // ZFREECNT_HEADER, + 'ZCOMMAND', + 'ZSTDERR', +]; + +function _get_blank_header(typenum) { + var creator = CREATORS[typenum]; + if (typeof(creator) === "string") { + throw( "Received unsupported header: " + creator ); + } + + /* + if (creator === ZCRC_HEADER) { + return new creator([0, 0, 0, 0]); + } + */ + + return _get_blank_header_from_constructor(creator); +} + +//referenced outside TODO +function _get_blank_header_from_constructor(creator) { + if (creator.prototype instanceof ZOffsetHeader) { + return new creator(0); + } + + return new creator([]); +} + +function _parse_binary16(bytes_arr) { + + //The max length of a ZDLE-encoded binary header w/ 16-bit CRC is: + // 3 initial bytes, NOT ZDLE-encoded + // 2 typenum bytes (1 decoded) + // 8 data bytes (4 decoded) + // 4 CRC bytes (2 decoded) + + //A 16-bit payload has 7 ZDLE-encoded octets. + //The ZDLE-encoded octets follow the initial prefix. + var zdle_decoded = Zmodem.ZDLE.splice( bytes_arr, BINARY16_HEADER_PREFIX.length, 7 ); + + return zdle_decoded && _parse_non_zdle_binary16(zdle_decoded); +} + +function _parse_non_zdle_binary16(decoded) { + Zmodem.CRC.verify16( + decoded.slice(0, 5), + decoded.slice(5) + ); + + var typenum = decoded[0]; + var hdr = _get_blank_header(typenum); + hdr._bytes4 = decoded.slice( 1, 5 ); + + return hdr; +} + +function _parse_binary32(bytes_arr) { + + //Same deal as with 16-bit CRC except there are two more + //potentially ZDLE-encoded bytes, for a total of 9. + var zdle_decoded = Zmodem.ZDLE.splice( + bytes_arr, //omit the leading "*", ZDLE, and "C" + BINARY32_HEADER_PREFIX.length, + 9 + ); + + if (!zdle_decoded) return; + + Zmodem.CRC.verify32( + zdle_decoded.slice(0, 5), + zdle_decoded.slice(5) + ); + + var typenum = zdle_decoded[0]; + var hdr = _get_blank_header(typenum); + hdr._bytes4 = zdle_decoded.slice( 1, 5 ); + + return hdr; +} + +function _parse_hex(bytes_arr) { + + //A hex header always has: + // 4 bytes for the ** . ZDLE . 'B' + // 2 hex bytes for the header type + // 8 hex bytes for the header content + // 4 hex bytes for the CRC + // 1-2 bytes for (CR/)LF + // (...and at this point the trailing XON is already stripped) + // + //---------------------------------------------------------------------- + //A carriage return and line feed are sent with HEX headers. The + //receive routine expects to see at least one of these characters, two + //if the first is CR. + //---------------------------------------------------------------------- + // + //^^ I guess it can be either CR/LF or just LF … though those two + //sentences appear to be saying contradictory things. + + var lf_pos = bytes_arr.indexOf( 0x8a ); //lrzsz sends this + + if (-1 === lf_pos) { + lf_pos = bytes_arr.indexOf( 0x0a ); + } + + var hdr_err, hex_bytes; + + if (-1 === lf_pos) { + if (bytes_arr.length > 11) { + hdr_err = "Invalid hex header - no LF detected within 12 bytes!"; + } + + //incomplete header + return; + } + else { + hex_bytes = bytes_arr.splice( 0, lf_pos ); + + //Trim off the LF + bytes_arr.shift(); + + if ( hex_bytes.length === 19 ) { + + //NB: The spec says CR but seems to treat high-bit variants + //of control characters the same as the regulars; should we + //also allow 0x8d? + var preceding = hex_bytes.pop(); + if ( preceding !== 0x0d && preceding !== 0x8d ) { + hdr_err = "Invalid hex header: (CR/)LF doesn’t have CR!"; + } + } + else if ( hex_bytes.length !== 18 ) { + hdr_err = "Invalid hex header: invalid number of bytes before LF!"; + } + } + + if (hdr_err) { + hdr_err += " (" + hex_bytes.length + " bytes: " + hex_bytes.join() + ")"; + throw hdr_err; + } + + hex_bytes.splice(0, 4); + + //Should be 7 bytes ultimately: + // 1 for typenum + // 4 for header data + // 2 for CRC + var octets = Zmodem.ENCODELIB.parse_hex_octets(hex_bytes); + + return _parse_non_zdle_binary16(octets); +} + +Zmodem.Header.parse_hex = _parse_hex; diff --git a/src/zmlib.js b/src/zmlib.js new file mode 100644 index 0000000..f86070d --- /dev/null +++ b/src/zmlib.js @@ -0,0 +1,102 @@ +"use strict"; + +var Zmodem = module.exports; + +const + ZDLE = 0x18, + XON = 0x11, + XOFF = 0x13, + XON_HIGH = 0x80 | XON, + XOFF_HIGH = 0x80 | XOFF, + CAN = 0x18 //NB: same character as ZDLE +; + +/** + * Tools and constants that are useful for ZMODEM. + * + * @exports ZMLIB + */ +Zmodem.ZMLIB = { + + /** + * @property {number} The ZDLE constant, which ZMODEM uses for escaping + */ + ZDLE: ZDLE, + + /** + * @property {number} XON - ASCII XON + */ + XON: XON, + + /** + * @property {number} XOFF - ASCII XOFF + */ + XOFF: XOFF, + + /** + * @property {number[]} ABORT_SEQUENCE - ZMODEM’s abort sequence + */ + ABORT_SEQUENCE: [ CAN, CAN, CAN, CAN, CAN ], + + /** + * Remove octet values from the given array that ZMODEM always ignores. + * This will mutate the given array. + * + * @param {number[]} octets - The octet values to transform. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @returns {number[]} The passed-in array. This is the same object that is + * passed in. + */ + strip_ignored_bytes: function strip_ignored_bytes(octets) { + for (var o=octets.length-1; o>=0; o--) { + switch (octets[o]) { + case XON: + case XON_HIGH: + case XOFF: + case XOFF_HIGH: + octets.splice(o, 1); + continue; + } + } + + return octets; + }, + + /** + * Like Array.prototype.indexOf, but searches for a subarray + * rather than just a particular value. + * + * @param {Array} haystack - The array to search, i.e., the bigger. + * + * @param {Array} needle - The array whose values to find, + * i.e., the smaller. + * + * @returns {number} The position in “haystack” where “needle” + * first appears—or, -1 if “needle” doesn’t appear anywhere + * in “haystack”. + */ + find_subarray: function find_subarray(haystack, needle) { + var h=0, n; + + var start = Date.now(); + + HAYSTACK: + while (h !== -1) { + h = haystack.indexOf( needle[0], h ); + if (h === -1) break HAYSTACK; + + for (n=1; n<needle.length; n++) { + if (haystack[h + n] !== needle[n]) { + h++; + continue HAYSTACK; + } + } + + return h; + } + + return -1; + }, +}; diff --git a/src/zmodem.js b/src/zmodem.js new file mode 100644 index 0000000..c16bcfe --- /dev/null +++ b/src/zmodem.js @@ -0,0 +1,4 @@ +Object.assign( + module.exports, + require("./zsentry"), +); diff --git a/src/zmodem_browser.js b/src/zmodem_browser.js new file mode 100644 index 0000000..7405f54 --- /dev/null +++ b/src/zmodem_browser.js @@ -0,0 +1,182 @@ +"use strict"; + +var Zmodem = module.exports; + +//TODO: Make this usable without require.js or what not. +window.Zmodem = Zmodem; + +Object.assign( + Zmodem, + require("./zmodem") +); + +function _check_aborted(session) { + if (session.aborted()) { + throw new Zmodem.Error("aborted"); + } +} + +/** Browser-specific tools + * + * @exports Browser + */ +Zmodem.Browser = { + + /** + * Send a batch of files in sequence. The session is left open + * afterward, which allows for more files to be sent if desired. + * + * @param {Zmodem.Session} session - The send session + * + * @param {FileList|Array} files - A list of File objects + * + * @param {Object} [options] + * @param {Function} [options.on_offer_response] - Called when an + * offer response arrives. Arguments are: + * + * - (File) - The File object that corresponds to the offer. + * - (Transfer|undefined) - If the receiver accepts the offer, then + * this is a Transfer object; otherwise it’s undefined. + * + * @param {Function} [options.on_progress] - Called immediately + * after a chunk of a file is sent. Arguments are: + * + * - (File) - The File object that corresponds to the file. + * - (Transfer) - The Transfer object for the current transfer. + * - (Uint8Array) - The chunk of data that was just loaded from disk + * and sent to the receiver. + * + * @param {Function} [options.on_file_complete] - Called immediately + * after the last file packet is sent. Arguments are: + * + * - (File) - The File object that corresponds to the file. + * - (Transfer) - The Transfer object for the now-completed transfer. + * + * @return {Promise} A Promise that fulfills when the batch is done. + * Note that skipped files are not considered an error condition. + */ + send_files: function send_files(session, files, options) { + if (!options) options = {}; + + //Populate the batch in reverse order to simplify sending + //the remaining files/bytes components. + var batch = []; + var total_size = 0; + for (var f=files.length - 1; f>=0; f--) { + var fobj = files[f]; + total_size += fobj.size; + batch[f] = { + obj: fobj, + name: fobj.name, + size: fobj.size, + mtime: new Date(fobj.lastModified), + files_remaining: files.length - f, + bytes_remaining: total_size, + }; + } + + var file_idx = 0; + function promise_callback() { + var cur_b = batch[file_idx]; + + if (!cur_b) { + return Promise.resolve(); //batch done! + } + + file_idx++; + + return session.send_offer(cur_b).then( function after_send_offer(xfer) { + if (options.on_offer_response) { + options.on_offer_response(cur_b.obj, xfer); + } + + if (xfer === undefined) { + return promise_callback(); //skipped + } + + return new Promise( function(res) { + var reader = new FileReader(); + + //This really shouldn’t happen … so let’s + //blow up if it does. + reader.onerror = function reader_onerror(e) { + console.error("file read error", e); + throw("File read error: " + e); + }; + + var piece; + reader.onprogress = function reader_onprogress(e) { + + //Some browsers (e.g., Chrome) give partial returns, + //while others (e.g., Firefox) don’t. + if (e.target.result) { + piece = new Uint8Array(e.target.result, xfer.get_offset()) + + _check_aborted(session); + + xfer.send(piece); + + if (options.on_progress) { + options.on_progress(cur_b.obj, xfer, piece); + } + } + }; + + reader.onload = function reader_onload(e) { + piece = new Uint8Array(e.target.result, xfer, piece) + + _check_aborted(session); + + xfer.end(piece).then( function() { + if (options.on_progress && piece.length) { + options.on_progress(cur_b.obj, xfer, piece); + } + + if (options.on_file_complete) { + options.on_file_complete(cur_b.obj, xfer); + } + + //Resolve the current file-send promise with + //another promise. That promise resolves immediately + //if we’re done, or with another file-send promise + //if there’s more to send. + res( promise_callback() ); + } ); + }; + + reader.readAsArrayBuffer(cur_b.obj); + } ); + } ); + } + + return promise_callback(); + }, + + /** + * Prompt a user to save the given packets as a file by injecting an + * `<a>` element (with `display: none` styling) into the page and + * calling the element’s `click()` + * method. The element is removed immediately after. + * + * @param {Array} packets - Same as the first argument to [Blob’s constructor](https://developer.mozilla.org/en-US/docs/Web/API/Blob). + * @param {string} name - The name to give the file. + */ + save_to_disk: function save_to_disk(packets, name) { + var blob = new Blob(packets); + var url = URL.createObjectURL(blob); + + var el = document.createElement("a"); + el.style.display = "none"; + el.href = url; + el.download = name; + document.body.appendChild(el); + + //It seems like a security problem that this actually works; + //I’d think there would need to be some confirmation before + //a browser could save arbitrarily many bytes onto the disk. + //But, hey. + el.click(); + + document.body.removeChild(el); + }, +}; diff --git a/src/zsentry.js b/src/zsentry.js new file mode 100644 index 0000000..470769a --- /dev/null +++ b/src/zsentry.js @@ -0,0 +1,394 @@ +"use strict"; + +var Zmodem = module.exports; + +Object.assign( + Zmodem, + require("./zmlib"), + require("./zsession") +); + +const + MIN_ZM_HEX_START_LENGTH = 20, + MAX_ZM_HEX_START_LENGTH = 21, + + // **, ZDLE, 'B0' + //ZRQINIT’s next byte will be '0'; ZRINIT’s will be '1'. + COMMON_ZM_HEX_START = [ 42, 42, 24, 66, 48 ], + + SENTRY_CONSTRUCTOR_REQUIRED_ARGS = [ + "to_terminal", + "on_detect", + "on_retract", + "sender", + ], + + ASTERISK = 42 +; + +/** + * An instance of this object is passed to the Sentry’s on_detect + * callback each time the Sentry object sees what looks like the + * start of a ZMODEM session. + * + * Note that it is possible for a detection to be “retracted” + * if the Sentry consumes bytes afterward that are not ZMODEM. + * When this happens, the Sentry’s `retract` event will fire, + * after which the Detection object is no longer usable. + */ +class Detection { + + /** + * Not called directly. + */ + constructor(session_type, accepter, denier, checker) { + + //confirm() - user confirms that ZMODEM is desired + this._confirmer = accepter; + + //deny() - user declines ZMODEM; send abort sequence + // + //TODO: It might be ideal to forgo the session “peaceably”, + //i.e., such that the peer doesn’t end in error. That’s + //possible if we’re the sender, we accept the session, + //then we just send a close(), but it doesn’t seem to be + //possible for a receiver. Thus, let’s just leave it so + //it’s at least consistent (and simpler, too). + this._denier = denier; + + this._is_valid = checker; + + this._session_type = session_type; + } + + /** + * Confirm that the detected ZMODEM sequence indicates the + * start of a ZMODEM session. + * + * @return {Session} The ZMODEM Session object (i.e., either a + * Send or Receive instance). + */ + confirm() { + return this._confirmer.apply(this, arguments); + } + + /** + * Tell the Sentry that the detected bytes sequence is + * **NOT** intended to be the start of a ZMODEM session. + */ + deny() { + return this._denier.apply(this, arguments); + } + + /** + * Tells whether the Detection is still valid; i.e., whether + * the Sentry has `consume()`d bytes that invalidate the + * Detection. + * + * @returns {boolean} Whether the Detection is valid. + */ + is_valid() { + return this._is_valid.apply(this, arguments); + } + + /** + * Gives the session’s role. + * + * @returns {string} One of: + * - `receive` + * - `send` + */ + get_session_role() { return this._session_type } +} + +/** + * Class that parses an input stream for the beginning of a + * ZMODEM session. We look for the tell-tale signs + * of a ZMODEM transfer and allow the client to determine whether + * it’s really ZMODEM or not. + * + * This is the “mother” class for zmodem.js; + * all other class instances are created, directly or indirectly, + * by an instance of this class. + * + * This logic is not unlikely to need tweaking, and it can never + * be fully bulletproof; if it could be bulletproof it would be + * simpler since there wouldn’t need to be the .confirm()/.deny() + * step. + * + * One thing you could do to make things a bit simpler *is* just + * to make that assumption for your users--i.e., to .confirm() + * Detection objects automatically. That’ll be one less step + * for the user, but an unaccustomed user might find that a bit + * confusing. It’s also then possible to have a “false positive”: + * a text stream that contains a ZMODEM initialization string but + * isn’t, in fact, meant to start a ZMODEM session. + * + * Workflow: + * - parse all input with .consume(). As long as nothing looks + * like ZMODEM, all the traffic will go to to_terminal(). + * + * - when a “tell-tale” sequence of bytes arrives, we create a + * Detection object and pass it to the “on_detect” handler. + * + * - Either .confirm() or .deny() with the Detection object. + * This is the user’s chance to say, “yeah, I know those + * bytes look like ZMODEM, but they’re not. So back off!” + * + * If you .confirm(), the Session object is returned, and + * further input that goes to the Sentry’s .consume() will + * go to the (now-active) Session object. + * + * - Sometimes additional traffic arrives that makes it apparent + * that no ZMODEM session is intended to start; in this case, + * the Sentry marks the Detection as “stale” and calls the + * `on_retract` handler. Any attempt from here to .confirm() + * on the Detection object will prompt an exception. + * + * (This “retraction” behavior will only happen prior to + * .confirm() or .deny() being called on the Detection object. + * Beyond that point, either the Session has to deal with the + * “garbage”, or it’s back to the terminal anyway. + * + * - Once the Session object is done, the Sentry will again send + * all traffic to to_terminal(). + */ +Zmodem.Sentry = class ZmodemSentry { + + /** + * Invoked directly. Creates a new Sentry that inspects all + * traffic before it goes to the terminal. + * + * @param {Object} options - The Sentry parameters + * + * @param {Function} options.to_terminal - Handler that sends + * traffic to the terminal object. Receives an iterable object + * (e.g., an Array) that contains octet numbers. + * + * @param {Function} options.on_detect - Handler for new + * detection events. Receives a new Detection object. + * + * @param {Function} options.on_retract - Handler for retraction + * events. Receives no input. + * + * @param {Function} options.sender - Handler that sends traffic to + * the peer. If, for example, your application uses WebSocket to talk + * to the peer, use this to send data to the WebSocket instance. + */ + constructor(options) { + if (!options) throw "Need options!"; + + var sentry = this; + SENTRY_CONSTRUCTOR_REQUIRED_ARGS.forEach( function(arg) { + if (!options[arg]) { + throw "Need “" + arg + "”!"; + } + sentry["_" + arg] = options[arg]; + } ); + + this._cache = []; + } + + _after_session_end() { + this._zsession = null; + } + + /** + * “Consumes” a piece of input: + * + * - If there is no active or pending ZMODEM session, the text is + * all output. (This is regardless of whether we’ve got a new + * Detection.) + * + * - If there is no active ZMODEM session and the input **ends** with + * a ZRINIT or ZRQINIT, then a new Detection object is created, + * and it is passed to the “on_detect” function. + * If there was another pending Detection object, it is retracted. + * + * - If there is no active ZMODEM session and the input does NOT end + * with a ZRINIT or ZRQINIT, then any pending Detection object is + * retracted. + * + * - If there is an active ZMODEM session, the input is passed to it. + * Any non-ZMODEM data (i.e., “garbage”) parsed from the input + * is sent to output. + * If the ZMODEM session ends, any post-ZMODEM part of the input + * is sent to output. + * + * @param {number[] | ArrayBuffer} input - Octets to parse as input. + */ + consume(input) { + if (!(input instanceof Array)) { + input = Array.prototype.slice.call( new Uint8Array(input) ); + } + + if (this._zsession) { + var session_before_consume = this._zsession; + + session_before_consume.consume(input); + + if (session_before_consume.has_ended()) { + if (session_before_consume.type === "receive") { + input = session_before_consume.get_trailing_bytes(); + } + else { + input = []; + } + } + else return; + } + + var new_session = this._parse(input); + var to_terminal = input; + + if (new_session) { + let replacement_detect = !!this._parsed_session; + + if (replacement_detect) { + //no terminal output if the new session is of the + //same type as the old + if (this._parsed_session.type === new_session.type) { + to_terminal = []; + } + + this._on_retract(); + } + + this._parsed_session = new_session; + + var sentry = this; + + function checker() { + return sentry._parsed_session === new_session; + } + + //This runs with the Sentry object as the context. + function accepter() { + if (!this.is_valid()) { + throw "Stale ZMODEM session!"; + } + + new_session.on("garbage", sentry._to_terminal); + + new_session.on( + "session_end", + sentry._after_session_end.bind(sentry) + ); + + new_session.set_sender(sentry._sender); + + delete sentry._parsed_session; + + return sentry._zsession = new_session; + }; + + function denier() { + if (!this.is_valid()) return; + }; + + this._on_detect( new Detection( + new_session.type, + accepter, + this._send_abort.bind(this), + checker + ) ); + } + else { + /* + if (this._parsed_session) { + this._session_stale_because = 'Non-ZMODEM output received after ZMODEM initialization.'; + } + */ + + var expired_session = this._parsed_session; + + this._parsed_session = null; + + if (expired_session) { + + //If we got a single “C” after parsing a session, + //that means our peer is trying to downgrade to YMODEM. + //That won’t work, so we just send the ABORT_SEQUENCE + //right away. + if (to_terminal.length === 1 && to_terminal[0] === 67) { + this._send_abort(); + } + + this._on_retract(); + } + } + + this._to_terminal(to_terminal); + } + + /** + * @return {Session|null} The sentry’s current Session object, or + * null if there is none. + */ + get_confirmed_session() { + return this._zsession || null; + } + + _send_abort() { + this._sender( Zmodem.ZMLIB.ABORT_SEQUENCE ); + } + + /** + * Parse an input stream and decide how much of it goes to the + * terminal or to a new Session object. + * + * This will accommodate input strings that are fragmented + * across calls to this function; e.g., if you send the first + * two bytes at the end of one parse() call then send the rest + * at the beginning of the next, parse() will recognize it as + * the beginning of a ZMODEM session. + * + * In order to keep from blocking any actual useful data to the + * terminal in real-time, this will send on the initial + * ZRINIT/ZRQINIT bytes to the terminal. They’re meant to go to the + * terminal anyway, so that should be fine. + * + * @private + * + * @param {Array|Uint8Array} array_like - The input bytes. + * Each member should be a number between 0 and 255 (inclusive). + * + * @return {Array} A two-member list: + * 0) the bytes that should be printed on the terminal + * 1) the created Session object (if any) + */ + _parse(array_like) { + var cache = this._cache; + + cache.push.apply( cache, array_like ); + + while (true) { + let common_hex_at = Zmodem.ZMLIB.find_subarray( cache, COMMON_ZM_HEX_START ); + if (-1 === common_hex_at) break; + + let before_common_hex = cache.splice(0, common_hex_at); + let zsession; + try { + zsession = Zmodem.Session.parse(cache); + } catch(err) { //ignore errors + //console.log(err); + } + + if (!zsession) break; + + //Don’t need to parse the trailing XON. + if ((cache.length === 1) && (cache[0] === Zmodem.ZMLIB.XON)) { + cache.shift(); + } + + //If there are still bytes in the cache, + //then we don’t have a ZMODEM session. This logic depends + //on the sender only sending one initial header. + return cache.length ? null : zsession; + } + + cache.splice( MAX_ZM_HEX_START_LENGTH ); + + return null; + } +} diff --git a/src/zsession.js b/src/zsession.js new file mode 100644 index 0000000..5f0b8f9 --- /dev/null +++ b/src/zsession.js @@ -0,0 +1,1677 @@ +"use strict"; + +var Zmodem = module.exports; + +/** + * This is where the protocol-level logic lives: the interaction of ZMODEM + * headers and subpackets. The logic here is not unlikely to need tweaking + * as little edge cases crop up. + */ + +Zmodem.DEBUG = false; + +Object.assign( + Zmodem, + require("./encode"), + require("./text"), + require("./zdle"), + require("./zmlib"), + require("./zheader"), + require("./zsubpacket"), + require("./zvalidation"), + require("./zerror") +); + +const + //pertinent to this module + KEEPALIVE_INTERVAL = 5000, + + //We ourselves don’t need ESCCTL, so we don’t send it; + //however, we always expect to receive it in ZRINIT. + //See _ensure_receiver_escapes_ctrl_chars() for more details. + ZRINIT_FLAGS = [ + "CANFDX", //full duplex + "CANOVIO", //overlap I/O + + //lsz has a buffer overflow bug that shows itself when: + // + // - 16-bit CRC is used, and + // - lsz receives the abort sequence while sending a file + // + //To avoid this, we just tell lsz to use 32-bit CRC + //even though there is otherwise no reason. This ensures that + //unfixed lsz versions will avoid the buffer overflow. + "CANFC32", + ], + + //We do this because some WebSocket shell servers + //(e.g., xterm.js’s demo server) enable the IEXTEN termios flag, + //which bars 0x0f and 0x16 from reaching the shell process, + //which results in transmission errors. + FORCE_ESCAPE_CTRL_CHARS = true, + + DEFAULT_RECEIVE_INPUT_MODE = "spool_uint8array", + + //pertinent to ZMODEM + MAX_CHUNK_LENGTH = 8192, //1 KiB officially, but lrzsz allows 8192 + BS = 0x8, + OVER_AND_OUT = [ 79, 79 ], + ABORT_SEQUENCE = Zmodem.ZMLIB.ABORT_SEQUENCE +; + +/** + * A base class for objects that have events. + * + * @private + */ +class _Eventer { + + /** + * Not called directly. + */ + constructor() { + this._on_evt = {}; + this._evt_once_index = {}; + } + + _Add_event(evt_name) { + this._on_evt[evt_name] = []; + this._evt_once_index[evt_name] = []; + } + + _get_evt_queue(evt_name) { + if (!this._on_evt[evt_name]) { + throw( "Bad event: " + evt_name ); + } + + return this._on_evt[evt_name]; + } + + /** + * Register a callback for a given event. + * + * @param {string} evt_name - The name of the event. + * + * @param {Function} todo - The function to execute when the event happens. + */ + on(evt_name, todo) { + var queue = this._get_evt_queue(evt_name); + + queue.push(todo); + + return this; + } + + /** + * Unregister a callback for a given event. + * + * @param {string} evt_name - The name of the event. + * + * @param {Function} [todo] - The function to execute when the event + * happens. If not given, the last event registered for the event + * is unregistered. + */ + off(evt_name, todo) { + var queue = this._get_evt_queue(evt_name); + + if (todo) { + var at = queue.indexOf(todo); + if (at === -1) { + throw("“" + todo + "” is not in the “" + evt_name + "” queue."); + } + queue.splice(at, 1); + } + else { + queue.pop(); + } + + return this; + } + + _Happen(evt_name /*, arg0, arg1, .. */) { + var queue = this._get_evt_queue(evt_name); //might as well validate + + //console.info("EVENT", this, arguments); + + var args = Array.apply(null, arguments); + args.shift(); + + var sess = this; + + queue.forEach( function(cb) { cb.apply(sess, args) } ); + + return queue.length; + } +} + +/** + * The Session classes handle the protocol-level logic. + * These shield the user from dealing with headers and subpackets. + * This is a base class with functionality common to both Receive + * and Send subclasses. + * + * @extends _Eventer +*/ +Zmodem.Session = class ZmodemSession extends _Eventer { + + /** + * Parse out a hex header from the given array. + * If there’s a ZRQINIT or ZRINIT at the beginning, + * we’ll return it. If the input isn’t a header, + * for whatever reason, we return undefined. + * + * @param {number[]} octets - The bytes to parse. + * + * @return {Session|undefined} A Session object if the beginning + * of a session was parsable in “octets”; otherwise undefined. + */ + static parse( octets ) { + + //Will need to trap errors. + var hdr; + try { + hdr = Zmodem.Header.parse_hex(octets); + } + catch(e) { //Don’t report since we aren’t in session + + //debug + //console.warn("No hex header: ", e); + + return; + } + + if (!hdr) return; + + switch (hdr.NAME) { + case "ZRQINIT": + //throw if ZCOMMAND + return new Zmodem.Session.Receive(); + case "ZRINIT": + return new Zmodem.Session.Send(hdr); + } + + //console.warn("Invalid first Zmodem header", hdr); + } + + /** + * Sets the sender function that a Session object will use. + * + * @param {Function} sender_func - The function to call. + * It will receive an Array with the relevant octets. + * + * @return {Session} The session object (for chaining). + */ + set_sender(sender_func) { + this._sender = sender_func; + return this; + } + + /** + * Whether the current Session has ended. + * + * @returns {boolean} The ended state. + */ + has_ended() { return this._has_ended() } + + /** + * Consumes an array of octets as ZMODEM session input. + * + * @param {number[]} octets - The input octets. + */ + consume(octets) { + this._before_consume(octets); + + if (this._aborted) throw new Zmodem.Error('already_aborted'); + + if (!octets.length) return; + + this._strip_and_enqueue_input(octets); + + if (!this._check_for_abort_sequence(octets)) { + this._consume_first(); + } + + return; + } + + /** + * Whether the current Session has been `abort()`ed. + * + * @returns {boolean} The aborted state. + */ + aborted() { return !!this._aborted } + + /** + * Not called directly. + */ + constructor() { + super(); + //if (!sender_func) throw "Need sender!"; + + //this._first_header = first_header; + //this._sender = sender_func; + this._config = {}; + + //this._input = new ZInput(); + + this._input_buffer = []; + + //This is mostly for debugging. + this._Add_event("receive"); + this._Add_event("garbage"); + this._Add_event("session_end"); + } + + /** + * Returns the Session object’s role. + * + * @returns {string} One of: + * - `receive` + * - `send` + */ + get_role() { return this.type } + + _trim_leading_garbage_until_header() { + var garbage = Zmodem.Header.trim_leading_garbage(this._input_buffer); + + if (garbage.length) { + if (this._Happen("garbage", garbage) === 0) { + console.debug( + "Garbage: ", + String.fromCharCode.apply(String, garbage), + garbage + ); + } + } + } + + _parse_and_consume_header() { + this._trim_leading_garbage_until_header(); + + var new_header_and_crc = Zmodem.Header.parse(this._input_buffer); + if (!new_header_and_crc) return; + + if (Zmodem.DEBUG) { + this._log_header( "RECEIVED HEADER", new_header_and_crc[0] ); + } + + this._consume_header(new_header_and_crc[0]); + + this._last_header_name = new_header_and_crc[0].NAME; + this._last_header_crc = new_header_and_crc[1]; + + return new_header_and_crc[0]; + } + + _log_header(label, header) { + console.debug(this.type, label, header.NAME, header._bytes4.join()); + } + + _consume_header(new_header) { + this._on_receive(new_header); + + var handler = this._next_header_handler && this._next_header_handler[ new_header.NAME ]; + if (!handler) { + console.error("Unhandled header!", new_header, this._next_header_handler); + throw new Zmodem.Error( "Unhandled header: " + new_header.NAME ); + } + + this._next_header_handler = null; + + handler.call(this, new_header); + } + + //TODO: strip out the abort sequence + _check_for_abort_sequence() { + var abort_at = Zmodem.ZMLIB.find_subarray( this._input_buffer, ABORT_SEQUENCE ); + + if (abort_at !== -1) { + + //TODO: expose this to caller + this._input_buffer.splice( 0, abort_at + ABORT_SEQUENCE.length ); + + this._aborted = true; + + //TODO compare response here to lrzsz. + this._on_session_end(); + + //We shouldn’t ever expect to receive an abort. Even if we + //have sent an abort ourselves, the Sentry should have stopped + //directing input to this Session object. + //if (this._expect_abort) { + // return true; + //} + + throw new Zmodem.Error("peer_aborted"); + } + } + + _send_header(name /*, args */) { + if (!this._sender) throw "Need sender!"; + + var args = Array.apply( null, arguments ); + + var bytes_hdr = this._create_header_bytes(args); + + if (Zmodem.DEBUG) { + this._log_header( "SENDING HEADER", bytes_hdr[1] ); + } + + this._sender(bytes_hdr[0]); + + this._last_sent_header = bytes_hdr[1]; + } + + _create_header_bytes(name_and_args) { + + var hdr = Zmodem.Header.build.apply( Zmodem.Header, name_and_args ); + + var formatter = this._get_header_formatter(name_and_args[0]); + + return [ + hdr[formatter](this._zencoder), + hdr + ]; + } + + _strip_and_enqueue_input(input) { + Zmodem.ZMLIB.strip_ignored_bytes(input); + + //It’s possible that “input” is empty at this point. + //It doesn’t seem to hurt anything to keep processing, though. + + this._input_buffer.push.apply( this._input_buffer, input ); + } + + /** + * **STOP!** You probably want to `skip()` an Offer rather than + * `abort()`. See below. + * + * Abort the current session by sending the ZMODEM abort sequence. + * This function will cause the Session object to refuse to send + * any further data. + * + * Zmodem.Sentry is configured to send all output to the terminal + * after a session’s `abort()`. That could result in lots of + * ZMODEM garble being sent to the JavaScript terminal, which you + * probably don’t want. + * + * `skip()` on an Offer is better because Session will continue to + * discard data until we reach either another file or the + * sender-initiated end of the ZMODEM session. So no ZMODEM garble, + * and the session will end successfully. + * + * The behavior of `abort()` is subject to change since it’s not + * very useful as currently implemented. + */ + abort() { + + //this._expect_abort = true; + + //From Forsberg: + // + //The Cancel sequence consists of eight CAN characters + //and ten backspace characters. ZMODEM only requires five + //Cancel characters; the other three are "insurance". + //The trailing backspace characters attempt to erase + //the effects of the CAN characters if they are + //received by a command interpreter. + // + //FG: Since we assume our connection is reliable, there’s + //no reason to send more than 5 CANs. + this._sender( + ABORT_SEQUENCE.concat([ BS, BS, BS, BS, BS ]) + ); + + this._aborted = true; + this._sender = function() { + throw new Zmodem.Error('already_aborted'); + }; + + this._on_session_end(); + + return; + } + + //---------------------------------------------------------------------- + _on_session_end() { + this._Happen("session_end"); + } + + _on_receive(hdr_or_pkt) { + this._Happen("receive", hdr_or_pkt); + } + + _before_consume() {} +} + +function _trim_OO(array) { + if (0 === Zmodem.ZMLIB.find_subarray(array, OVER_AND_OUT)) { + array.splice(0, OVER_AND_OUT.length); + } + + //TODO: This assumes OVER_AND_OUT is 2 bytes long. No biggie, but. + else if ( array[0] === OVER_AND_OUT[ OVER_AND_OUT.length - 1 ] ) { + array.splice(0, 1); + } + + return array; +} + +/** A class for ZMODEM receive sessions. + * + * @extends Session + */ +Zmodem.Session.Receive = class ZmodemReceiveSession extends Zmodem.Session { + //We only get 1 file at a time, so on each consume() either + //continue state for the current file or start a new one. + + /** + * Not called directly. + */ + constructor() { + super(); + + this._Add_event("offer"); + this._Add_event("data_in"); + this._Add_event("file_end"); + } + + /** + * Consume input bytes from the sender. + * + * @private + * @param {number[]} octets - The bytes to consume. + */ + _before_consume(octets) { + if (this._bytes_after_OO) { + throw "PROTOCOL: Session is completed!"; + } + + //Put this here so that our logic later on has access to the + //input string and can populate _bytes_after_OO when the + //session ends. + this._bytes_being_consumed = octets; + } + + /** + * Return any bytes that have been `consume()`d but + * came after the end of the ZMODEM session. + * + * @returns {number[]} The trailing bytes. + */ + get_trailing_bytes() { + if (this._aborted) return []; + + if (!this._bytes_after_OO) { + throw "PROTOCOL: Session is not completed!"; + } + + return this._bytes_after_OO.slice(0); + } + + _has_ended() { return this.aborted() || !!this._bytes_after_OO } + + //Receiver always sends hex headers. + _get_header_formatter() { return "to_hex" } + + _parse_and_consume_subpacket() { + var parse_func; + if (this._last_header_crc === 16) { + parse_func = "parse16"; + } + else { + parse_func = "parse32"; + } + + var subpacket = Zmodem.Subpacket[parse_func](this._input_buffer); + + if (subpacket) { + if (Zmodem.DEBUG) { + console.debug(this.type, "RECEIVED SUBPACKET", subpacket); + } + + this._consume_data(subpacket); + + //What state are we in if the subpacket indicates frame end + //but we haven’t gotten ZEOF yet? Can anything other than ZEOF + //follow after a ZDATA? + if (subpacket.frame_end()) { + this._next_subpacket_handler = null; + } + } + + return subpacket; + } + + _consume_first() { + if (this._got_ZFIN) { + if (this._input_buffer.length < 2) return; + + //if it’s OO, then set this._bytes_after_OO + if (Zmodem.ZMLIB.find_subarray(this._input_buffer, OVER_AND_OUT) === 0) { + + //This doubles as an indication that the session has ended. + //We need to set this right away so that handlers like + //"session_end" will have access to it. + this._bytes_after_OO = _trim_OO(this._bytes_being_consumed.slice(0)); + this._on_session_end(); + + return; + } + else { + throw( "PROTOCOL: Only thing after ZFIN should be “OO” (79,79), not: " + this._input_buffer.join() ); + } + } + + var parsed; + do { + if (this._next_subpacket_handler) { + parsed = this._parse_and_consume_subpacket(); + } + else { + parsed = this._parse_and_consume_header(); + } + } while (parsed && this._input_buffer.length); + } + + _consume_data(subpacket) { + this._on_receive(subpacket); + + if (!this._next_subpacket_handler) { + throw( "PROTOCOL: Received unexpected data packet after " + this._last_header_name + " header: " + subpacket.get_payload().join() ); + } + + this._next_subpacket_handler.call(this, subpacket); + } + + _octets_to_string(octets) { + if (!this._textdecoder) { + this._textdecoder = new Zmodem.Text.Decoder(); + } + + return this._textdecoder.decode( new Uint8Array(octets) ); + } + + _consume_ZFILE_data(hdr, subpacket) { + if (this._file_info) { + throw "PROTOCOL: second ZFILE data subpacket received"; + } + + var packet_payload = subpacket.get_payload(); + var nul_at = packet_payload.indexOf(0); + + // + var fname = this._octets_to_string( packet_payload.slice(0, nul_at) ); + var the_rest = this._octets_to_string( packet_payload.slice( 1 + nul_at ) ).split(" "); + + var mtime = the_rest[1] && parseInt( the_rest[1], 8 ) || undefined; + if (mtime) { + mtime = new Date(mtime * 1000); + } + + this._file_info = { + name: fname, + size: the_rest[0] ? parseInt( the_rest[0], 10 ) : null, + mtime: mtime || null, + mode: the_rest[2] && parseInt( the_rest[2], 8 ) || null, + serial: the_rest[3] && parseInt( the_rest[3], 10 ) || null, + + files_remaining: the_rest[4] ? parseInt( the_rest[4], 10 ) : null, + bytes_remaining: the_rest[5] ? parseInt( the_rest[5], 10 ) : null, + }; + + //console.log("ZFILE", hdr); + + var xfer = new Offer( + hdr.get_options(), + this._file_info, + this._accept.bind(this), + this._skip.bind(this) + ); + this._current_transfer = xfer; + + //this._Happen("offer", xfer); + } + + _consume_ZDATA_data(subpacket) { + if (!this._accepted_offer) { + throw "PROTOCOL: Received data without accepting!"; + } + + //TODO: Probably should include some sort of preventive against + //infinite loop here: if the peer hasn’t sent us what we want after, + //say, 10 ZRPOS headers then we should send ZABORT and just end. + if (!this._offset_ok) { + console.warn("offset not ok!"); + _send_ZRPOS(); + return; + } + + this._file_offset += subpacket.get_payload().length; + this._on_data_in(subpacket); + + /* + console.warn("received error from data_in callback; retrying", e); + throw "unimplemented"; + */ + + if (subpacket.ack_expected() && !subpacket.frame_end()) { + this._send_header( "ZACK", Zmodem.ENCODELIB.pack_u32_le(this._file_offset) ); + } + } + + _make_promise_for_between_files() { + var sess = this; + + return new Promise( function(res) { + var between_files_handler = { + ZFILE: function(hdr) { + this._next_subpacket_handler = function(subpacket) { + this._next_subpacket_handler = null; + this._consume_ZFILE_data(hdr, subpacket); + this._Happen("offer", this._current_transfer); + res(this._current_transfer); + }; + }, + + //We use this as a keep-alive. Maybe other + //implementations do, too? + ZSINIT: function(hdr) { + //The content of this header doesn’t affect us + //since all it does is tell us details of how + //the sender will ZDLE-encode binary data. Our + //ZDLE parser doesn’t need to know in advance. + + sess._next_subpacket_handler = function(spkt) { + sess._next_subpacket_handler = null; + sess._consume_ZSINIT_data(spkt); + sess._send_header('ZACK'); + sess._next_header_handler = between_files_handler; + }; + }, + + ZFIN: function() { + this._consume_ZFIN(); + res(); + }, + }; + + sess._next_header_handler = between_files_handler; + } ); + } + + _consume_ZSINIT_data(spkt) { + + //TODO: Should this be used when we signal a cancellation? + this._attn = spkt.get_payload(); + } + + /** + * Start the ZMODEM session by signaling to the sender that + * we are ready for the first file offer. + * + * @returns {Promise} A promise that resolves with an Offer object + * or, if the sender closes the session immediately without offering + * anything, nothing. + */ + start() { + if (this._started) throw "Already started!"; + this._started = true; + + var ret = this._make_promise_for_between_files(); + + this._send_ZRINIT(); + + return ret; + } + + //Returns a promise that’s fulfilled when the file + //transfer is done. + // + // That ZEOF promise return is another promise that’s + // fulfilled when we get either ZFIN or another ZFILE. + _accept(offset) { + this._accepted_offer = true; + this._file_offset = offset || 0; + + var sess = this; + + var ret = new Promise( function(resolve_accept) { + var last_ZDATA; + + sess._next_header_handler = { + ZDATA: function on_ZDATA(hdr) { + this._consume_ZDATA(hdr); + + this._next_subpacket_handler = this._consume_ZDATA_data; + + this._next_header_handler = { + ZEOF: function on_ZEOF(hdr) { + + // Do this first to verify the ZEOF. + // This also fires the “file_end” event. + this._consume_ZEOF(hdr); + + this._next_subpacket_handler = null; + + // We don’t care about this promise. + // Prior to v0.1.8 we did because we called + // resolve_accept() at the resolution of this + // promise, but that was a bad idea and was + // never documented, so 0.1.8 changed it. + this._make_promise_for_between_files(); + + resolve_accept(); + + this._send_ZRINIT(); + }, + }; + }, + }; + } ); + + this._send_ZRPOS(); + + return ret; + } + + _skip() { + var ret = this._make_promise_for_between_files(); + + if (this._accepted_offer) { + // There’s a race condition where we might attempt to + // skip() an in-progress transfer near its end but actually + // the skip() will fire after the transfer is complete. + // While there might be ways to prevent this, they likely + // would require extra work on the part of implementations. + // + // It seems far simpler just to make this function a no-op + // in these cases. + if (!this._current_transfer) return; + + //For cancel of an in-progress transfer from lsz, + //it’s necessary to avoid this buffer overflow bug: + // + // https://github.com/gooselinux/lrzsz/blob/master/lrzsz-0.12.20.patch + // + //… which we do by asking for CRC32 from lsz. + + //We might or might not have consumed ZDATA. + //The sender also might or might not send a ZEOF before it + //parses the ZSKIP. Thus, we want to ignore the following: + // + // - ZDATA + // - ZDATA then ZEOF + // - ZEOF + // + //… and just look for the next between-file header. + + var bound_make_promise_for_between_files = function() { + + //Once this happens we fail on any received data packet. + //So it needs not to happen until we’ve received a header. + this._accepted_offer = false; + this._next_subpacket_handler = null; + + this._make_promise_for_between_files(); + }.bind(this); + + Object.assign( + this._next_header_handler, + { + ZEOF: bound_make_promise_for_between_files, + ZDATA: function() { + bound_make_promise_for_between_files(); + this._next_header_handler.ZEOF = bound_make_promise_for_between_files; + }.bind(this), + } + ); + } + + //this._accepted_offer = false; + + this._file_info = null; + + this._send_header( "ZSKIP" ); + + return ret; + } + + _send_ZRINIT() { + this._send_header( "ZRINIT", ZRINIT_FLAGS ); + } + + _consume_ZFIN() { + this._got_ZFIN = true; + this._send_header( "ZFIN" ); + } + + _consume_ZEOF(header) { + if (this._file_offset !== header.get_offset()) { + throw( "ZEOF offset mismatch; unimplemented (local: " + this._file_offset + "; ZEOF: " + header.get_offset() + ")" ); + } + + this._on_file_end(); + + //Preserve these two so that file_end callbacks + //will have the right information. + this._file_info = null; + this._current_transfer = null; + } + + _consume_ZDATA(header) { + if ( this._file_offset === header.get_offset() ) { + this._offset_ok = true; + } + else { + throw "Error correction is unimplemented."; + } + } + + _send_ZRPOS() { + this._send_header( "ZRPOS", this._file_offset ); + } + + //---------------------------------------------------------------------- + //events + + _on_file_end() { + this._Happen("file_end"); + + if (this._current_transfer) { + this._current_transfer._Happen("complete"); + this._current_transfer = null; + } + } + + _on_data_in(subpacket) { + this._Happen("data_in", subpacket); + + if (this._current_transfer) { + this._current_transfer._Happen("input", subpacket.get_payload()); + } + } +} + +Object.assign( + Zmodem.Session.Receive.prototype, + { + type: "receive", + } +); + +//---------------------------------------------------------------------- + +/** + * @typedef {Object} FileDetails + * + * @property {string} name - The name of the file. + * + * @property {number} [size] - The file size, in bytes. + * + * @property {number} [mode] - The file mode (e.g., 0100644). + * + * @property {Date|number} [mtime] - The file’s modification time. + * When expressed as a number, the unit is epoch seconds. + * + * @property {number} [files_remaining] - Inclusive of the current file, + * so this value is never less than 1. + * + * @property {number} [bytes_remaining] - Inclusive of the current file. + */ + +/** + * Common methods for Transfer and Offer objects. + * + * @mixin + */ +var Transfer_Offer_Mixin = { + /** + * Returns the file details object. + * @returns {FileDetails} `mtime` is a Date. + */ + get_details: function get_details() { + return Object.assign( {}, this._file_info ); + }, + + /** + * Returns a parse of the ZFILE header’s payload. + * + * @returns {Object} Members are: + * + * - `conversion` (string | undefined) + * - `management` (string | undefined) + * - `transfer` (string | undefined) + * - `sparse` (boolean) + */ + get_options: function get_options() { + return Object.assign( {}, this._zfile_opts ); + }, + + /** + * Returns the offset based on the last transferred chunk. + * @returns {number} The file offset (i.e., number of bytes after + * the start of the file). + */ + get_offset: function get_offset() { + return this._file_offset; + }, +}; + +/** + * A class to represent a sender’s interaction with a single file + * transfer within a batch. When a receiver accepts an offer, the + * Session instantiates this class and passes the instance as the + * promise resolution from send_offer(). + * + * @mixes Transfer_Offer_Mixin + */ +class Transfer { + + /** + * Not called directly. + */ + constructor(file_info, offset, send_func, end_func) { + this._file_info = file_info; + this._file_offset = offset || 0; + + this._send = send_func; + this._end = end_func; + } + + /** + * Send a (non-terminal) piece of the file. + * + * @param { number[] | Uint8Array } array_like - The bytes to send. + */ + send(array_like) { + this._send(array_like); + this._file_offset += array_like.length; + } + + /** + * Complete the file transfer. + * + * @param { number[] | Uint8Array } [array_like] - The last bytes to send. + * + * @return { Promise } Resolves when the receiver has indicated + * acceptance of the end of the file transfer. + */ + end(array_like) { + var ret = this._end(array_like || []); + if (array_like) this._file_offset += array_like.length; + return ret; + } +} +Object.assign( Transfer.prototype, Transfer_Offer_Mixin ); + +/** + * A class to represent a receiver’s interaction with a single file + * transfer offer within a batch. There is functionality here to + * skip or accept offered files and either to spool the packet + * payloads or to handle them yourself. + * + * @mixes Transfer_Offer_Mixin + */ +class Offer extends _Eventer { + + /** + * Not called directly. + */ + constructor(zfile_opts, file_info, accept_func, skip_func) { + super(); + + this._zfile_opts = zfile_opts; + this._file_info = file_info; + + this._accept_func = accept_func; + this._skip_func = skip_func; + + this._Add_event("input"); + this._Add_event("complete"); + + //Register this first so that application handlers receive + //the updated offset. + this.on("input", this._input_handler); + } + + _verify_not_skipped() { + if (this._skipped) { + throw new Zmodem.Error("Already skipped!"); + } + } + + /** + * Tell the sender that you don’t want the offered file. + * + * You can send this in lieu of `accept()` or after it, e.g., + * if you find that the transfer is taking too long. Note that, + * if you `skip()` after you `accept()`, you’ll likely have to + * wait for buffers to clear out. + * + */ + skip() { + this._verify_not_skipped(); + this._skipped = true; + + return this._skip_func.apply(this, arguments); + } + + /** + * Tell the sender to send the offered file. + * + * @param {Object} [opts] - Can be: + * @param {string} [opts.oninput=spool_uint8array] - Can be: + * + * - `spool_uint8array`: Stores the ZMODEM + * packet payloads as Uint8Array instances. + * This makes for an easy transition to a Blob, + * which JavaScript can use to save the file to disk. + * + * - `spool_array`: Stores the ZMODEM packet payloads + * as Array instances. Each value is an octet value. + * + * - (function): A handler that receives each payload + * as it arrives. The Offer object does not store + * the payloads internally when thus configured. + * + * @return { Promise } Resolves when the file is fully received. + * If the Offer has been spooling + * the packet payloads, the promise resolves with an Array + * that contains those payloads. + */ + accept(opts) { + this._verify_not_skipped(); + + if (this._accepted) { + throw new Zmodem.Error("Already accepted!"); + } + this._accepted = true; + + if (!opts) opts = {}; + + this._file_offset = opts.offset || 0; + + switch (opts.on_input) { + case null: + case undefined: + case "spool_array": + case DEFAULT_RECEIVE_INPUT_MODE: //default + this._spool = []; + break; + default: + if (typeof opts.on_input !== "function") { + throw "Invalid “on_input”: " + opts.on_input; + } + } + + this._input_handler_mode = opts.on_input || DEFAULT_RECEIVE_INPUT_MODE; + + return this._accept_func(this._file_offset).then( this._get_spool.bind(this) ); + } + + _input_handler(payload) { + this._file_offset += payload.length; + + if (typeof this._input_handler_mode === "function") { + this._input_handler_mode(payload); + } + else { + if (this._input_handler_mode === DEFAULT_RECEIVE_INPUT_MODE) { + payload = new Uint8Array(payload); + } + + //sanity + else if (this._input_handler_mode !== "spool_array") { + throw new Zmodem.Error("WTF?? _input_handler_mode = " + this._input_handler_mode); + } + + this._spool.push(payload); + } + } + + _get_spool() { + return this._spool; + } +} +Object.assign( Offer.prototype, Transfer_Offer_Mixin ); + +//Curious that ZSINIT isn’t here … but, lsz sends it as hex. +const SENDER_BINARY_HEADER = { + ZFILE: true, + ZDATA: true, +}; + +/** + * A class that encapsulates behavior for a ZMODEM sender. + * + * @extends Session + */ +Zmodem.Session.Send = class ZmodemSendSession extends Zmodem.Session { + + /** + * Not called directly. + */ + constructor(zrinit_hdr) { + super(); + + if (!zrinit_hdr) { + throw "Need first header!"; + } + else if (zrinit_hdr.NAME !== "ZRINIT") { + throw("First header should be ZRINIT, not " + zrinit_hdr.NAME); + } + + this._last_header_name = 'ZRINIT'; + + //We don’t need to send crc32. Even if the other side can grok it, + //there’s no point to sending it since, for now, we assume we’re + //on a reliable connection, e.g., TCP. Ideally we’d just forgo + //CRC checks completely, but ZMODEM doesn’t allow that. + // + //If we *were* to start using crc32, we’d update this every time + //we send a header. + this._subpacket_encode_func = 'encode16'; + + this._zencoder = new Zmodem.ZDLE(); + + this._consume_ZRINIT(zrinit_hdr); + + this._file_offset = 0; + + var zrqinit_count = 0; + + this._start_keepalive_on_set_sender = true; + + //lrzsz will send ZRINIT until it gets an offer. (keep-alive?) + //It sends 4 additional ones after the initial ZRINIT and, if + //no response is received, starts sending “C” (0x43, 67) as if to + //try to downgrade to XMODEM or YMODEM. + //var sess = this; + //this._prepare_to_receive_ZRINIT( function keep_alive() { + // sess._prepare_to_receive_ZRINIT(keep_alive); + //} ); + + //queue up the ZSINIT flag to send -- but seems useless?? + + /* + Object.assign( + this._on_evt, + { + file_received: [], + }, + }; + */ + } + + /** + * Sets the sender function. The first time this is called, + * it will also initiate a keepalive using ZSINIT until the + * first file is sent. + * + * @param {Function} func - The function to call. + * It will receive an Array with the relevant octets. + * + * @return {Session} The session object (for chaining). + */ + set_sender(func) { + super.set_sender(func); + + if (this._start_keepalive_on_set_sender) { + this._start_keepalive_on_set_sender = false; + this._start_keepalive(); + } + + return this; + } + + //7.3.3 .. The sender also uses hex headers when they are + //not followed by binary data subpackets. + // + //FG: … or when the header is ZSINIT? That’s what lrzsz does, anyway. + //Then it sends a single NUL byte as the payload to an end_ack subpacket. + _get_header_formatter(name) { + return SENDER_BINARY_HEADER[name] ? "to_binary16" : "to_hex"; + } + + //In order to keep lrzsz from timing out, we send ZSINIT every 5 seconds. + //Maybe make this configurable? + _start_keepalive() { + //if (this._keepalive_promise) throw "Keep-alive already started!"; + if (!this._keepalive_promise) { + var sess = this; + + this._keepalive_promise = new Promise(function(resolve) { + //console.log("SETTING KEEPALIVE TIMEOUT"); + sess._keepalive_timeout = setTimeout(resolve, KEEPALIVE_INTERVAL); + }).then( function() { + sess._next_header_handler = { + ZACK: function() { + + //We’re going to need to ensure that the + //receiver is ready for all control characters + //to be escaped. If we’ve already sent a ZSINIT + //and gotten a response, then we know that that + //work is already done later on when we actually + //send an offer. + sess._got_ZSINIT_ZACK = true; + }, + }; + sess._send_ZSINIT(); + + sess._keepalive_promise = null; + sess._start_keepalive(); + }); + } + } + + _stop_keepalive() { + if (this._keepalive_promise) { + //console.log("STOPPING KEEPALIVE"); + clearTimeout(this._keepalive_timeout); + this._keep_alive_promise = null; + } + } + + _send_ZSINIT() { + //See note at _ensure_receiver_escapes_ctrl_chars() + //for why we have to pass ESCCTL. + + var zsinit_flags = []; + if (this._zencoder.escapes_ctrl_chars()) { + zsinit_flags.push("ESCCTL"); + } + + this._send_header_and_data( + ["ZSINIT", zsinit_flags], + [0], + "end_ack" + ); + } + + _consume_ZRINIT(hdr) { + this._last_ZRINIT = hdr; + + if (hdr.get_buffer_size()) { + throw( "Buffer size (" + hdr.get_buffer_size() + ") is unsupported!" ); + } + + if (!hdr.can_full_duplex()) { + throw( "Half-duplex I/O is unsupported!" ); + } + + if (!hdr.can_overlap_io()) { + throw( "Non-overlap I/O is unsupported!" ); + } + + if (hdr.escape_8th_bit()) { + throw( "8-bit escaping is unsupported!" ); + } + + if (FORCE_ESCAPE_CTRL_CHARS) { + this._zencoder.set_escape_ctrl_chars(true); + if (!hdr.escape_ctrl_chars()) { + console.debug("Peer didn’t request escape of all control characters. Will send ZSINIT to force recognition of escaped control characters."); + } + } + else { + this._zencoder.set_escape_ctrl_chars(hdr.escape_ctrl_chars()); + } + } + + //https://stackoverflow.com/questions/23155939/missing-0xf-and-0x16-when-binary-data-through-virtual-serial-port-pair-created-b + //^^ Because of that, we always escape control characters. + //The alternative would be that lrz would never receive those + //two bytes from zmodem.js. + _ensure_receiver_escapes_ctrl_chars() { + var promise; + + var needs_ZSINIT = !this._last_ZRINIT.escape_ctrl_chars() && !this._got_ZSINIT_ZACK; + + if (needs_ZSINIT) { + var sess = this; + promise = new Promise( function(res) { + sess._next_header_handler = { + ZACK: (hdr) => { + res(); + }, + }; + sess._send_ZSINIT(); + } ); + } + else { + promise = Promise.resolve(); + } + + return promise; + } + + _convert_params_to_offer_payload_array(params) { + params = Zmodem.Validation.offer_parameters(params); + + var subpacket_payload = params.name + "\x00"; + + var subpacket_space_pieces = [ + (params.size || 0).toString(10), + params.mtime ? params.mtime.toString(8) : "0", + params.mode ? (0x8000 | params.mode).toString(8) : "0", + "0", //serial + ]; + + if (params.files_remaining) { + subpacket_space_pieces.push( params.files_remaining ); + + if (params.bytes_remaining) { + subpacket_space_pieces.push( params.bytes_remaining ); + } + } + + subpacket_payload += subpacket_space_pieces.join(" "); + return this._string_to_octets(subpacket_payload); + } + + /** + * Send an offer to the receiver. + * + * @param {FileDetails} params - All about the file you want to transfer. + * + * @returns {Promise} If the receiver accepts the offer, then the + * resolution is a Transfer object; otherwise the resolution is + * undefined. + */ + send_offer(params) { + if (Zmodem.DEBUG) { + console.debug("SENDING OFFER", params); + } + + if (!params) throw "need file params!"; + + if (this._sending_file) throw "Already sending file!"; + + var payload_array = this._convert_params_to_offer_payload_array(params); + + this._stop_keepalive(); + + var sess = this; + + function zrpos_handler_setter_func() { + sess._next_header_handler = { + + // The receiver may send ZRPOS in at least two cases: + // + // 1) A malformed subpacket arrived, so we need to + // “rewind” a bit and continue from the receiver’s + // last-successful location in the file. + // + // 2) The receiver hasn’t gotten any data for a bit, + // so it sends ZRPOS as a “ping”. + // + // Case #1 shouldn’t happen since zmodem.js requires a + // reliable transport. Case #2, though, can happen due + // to either normal network congestion or errors in + // implementation. In either case, there’s nothing for + // us to do but to ignore the ZRPOS, with an optional + // warning. + // + ZRPOS: function(hdr) { + if (Zmodem.DEBUG) { + console.warn("Mid-transfer ZRPOS … implementation error?"); + } + + zrpos_handler_setter_func(); + }, + }; + }; + + var doer_func = function() { + + //return Promise object that is fulfilled when the ZRPOS or ZSKIP arrives. + //The promise value is the byte offset, or undefined for ZSKIP. + //If ZRPOS arrives, then send ZDATA(0) and set this._sending_file. + var handler_setter_promise = new Promise( function(res) { + sess._next_header_handler = { + ZSKIP: function() { + sess._start_keepalive(); + res(); + }, + ZRPOS: function(hdr) { + sess._sending_file = true; + + zrpos_handler_setter_func(); + + res( + new Transfer( + params, + hdr.get_offset(), + sess._send_interim_file_piece.bind(sess), + sess._end_file.bind(sess) + ) + ); + }, + }; + } ); + + sess._send_header_and_data( ["ZFILE"], payload_array, "end_ack" ); + + delete sess._sent_ZDATA; + + return handler_setter_promise; + }; + + if (FORCE_ESCAPE_CTRL_CHARS) { + return this._ensure_receiver_escapes_ctrl_chars().then(doer_func); + } + + return doer_func(); + } + + _send_header_and_data( hdr_name_and_args, data_arr, frameend ) { + var bytes_hdr = this._create_header_bytes(hdr_name_and_args); + + var data_bytes = this._build_subpacket_bytes(data_arr, frameend); + + bytes_hdr[0].push.apply( bytes_hdr[0], data_bytes ); + + if (Zmodem.DEBUG) { + this._log_header( "SENDING HEADER", bytes_hdr[1] ); + console.debug( this.type, "-- HEADER PAYLOAD:", frameend, data_bytes.length ); + } + + this._sender( bytes_hdr[0] ); + + this._last_sent_header = bytes_hdr[1]; + } + + _build_subpacket_bytes( bytes_arr, frameend ) { + var subpacket = Zmodem.Subpacket.build(bytes_arr, frameend); + + return subpacket[this._subpacket_encode_func]( this._zencoder ); + } + + _build_and_send_subpacket( bytes_arr, frameend ) { + this._sender( this._build_subpacket_bytes(bytes_arr, frameend) ); + } + + _string_to_octets(string) { + if (!this._textencoder) { + this._textencoder = new Zmodem.Text.Encoder(); + } + + var uint8arr = this._textencoder.encode(string); + return Array.prototype.slice.call(uint8arr); + } + + /* + Potential future support for responding to ZRPOS: + send_file_offset(offset) { + } + */ + + /* + Sending logic works thus: + - ASSUME the receiver can overlap I/O (CANOVIO) + (so fail if !CANFDX || !CANOVIO) + - Sender opens the firehose … all ZCRCG (!end/!ack) + until the end, when we send a ZCRCE (end/!ack) + NB: try 8k/32k/64k chunk sizes? Looks like there’s + no need to change the packet otherwise. + */ + //TODO: Put this on a Transfer object similar to what Receive uses? + _send_interim_file_piece(bytes_obj) { + + //We don’t ask the receiver to confirm because there’s no need. + this._send_file_part(bytes_obj, "no_end_no_ack"); + + //This pattern will allow + //error-correction without buffering the entire stream in JS. + //For now the promise is always resolved, but in the future we + //can make it only resolve once we’ve gotten acknowledgement. + return Promise.resolve(); + } + + _ensure_we_are_sending() { + if (!this._sending_file) throw "Not sending a file currently!"; + } + + //This resolves once we receive ZEOF. + _end_file(bytes_obj) { + this._ensure_we_are_sending(); + + //Is the frame-end-ness of this last packet redundant + //with the ZEOF packet?? - No. It signals the receiver that + //the next thing to expect is a header, not a packet. + + //no-ack, following lrzsz’s example + this._send_file_part(bytes_obj, "end_no_ack"); + + var sess = this; + + //Register this before we send ZEOF in case of local round-trip. + //(Basically just for synchronous testing, but.) + var ret = new Promise( function(res) { + //console.log("UNSETTING SENDING FLAG"); + sess._sending_file = false; + sess._prepare_to_receive_ZRINIT(res); + } ); + + this._send_header( "ZEOF", this._file_offset ); + + this._file_offset = 0; + + return ret; + } + + //Called at the beginning of our session + //and also when we’re done sending a file. + _prepare_to_receive_ZRINIT(after_consume) { + this._next_header_handler = { + ZRINIT: function(hdr) { + this._consume_ZRINIT(hdr); + if (after_consume) after_consume(); + }, + }; + } + + /** + * Signal to the receiver that the ZMODEM session is wrapping up. + * + * @returns {Promise} Resolves when the receiver has responded to + * our signal that the session is over. + */ + close() { + var ok_to_close = (this._last_header_name === "ZRINIT") + if (!ok_to_close) { + ok_to_close = (this._last_header_name === "ZSKIP"); + } + if (!ok_to_close) { + ok_to_close = (this._last_sent_header.name === "ZSINIT") && (this._last_header_name === "ZACK"); + } + + if (!ok_to_close) { + throw( "Can’t close; last received header was “" + this._last_header_name + "”" ); + } + + var sess = this; + + var ret = new Promise( function(res, rej) { + sess._next_header_handler = { + ZFIN: function() { + sess._sender( OVER_AND_OUT ); + sess._sent_OO = true; + sess._on_session_end(); + res(); + }, + }; + } ); + + this._send_header("ZFIN"); + + return ret; + } + + _has_ended() { + return this.aborted() || !!this._sent_OO; + } + + _send_file_part(bytes_obj, final_packetend) { + if (!this._sent_ZDATA) { + this._send_header( "ZDATA", this._file_offset ); + this._sent_ZDATA = true; + } + + var obj_offset = 0; + + var bytes_count = bytes_obj.length; + + //We have to go through at least once in event of an + //empty buffer, e.g., an empty end_file. + while (true) { + var chunk_size = Math.min(obj_offset + MAX_CHUNK_LENGTH, bytes_count) - obj_offset; + + var at_end = (chunk_size + obj_offset) >= bytes_count; + + var chunk = bytes_obj.slice( obj_offset, obj_offset + chunk_size ); + if (!(chunk instanceof Array)) { + chunk = Array.prototype.slice.call(chunk); + } + + this._build_and_send_subpacket( + chunk, + at_end ? final_packetend : "no_end_no_ack" + ); + + this._file_offset += chunk_size; + obj_offset += chunk_size; + + if (obj_offset >= bytes_count) break; + } + } + + _consume_first() { + if (!this._parse_and_consume_header()) { + + //When the ZMODEM receive program starts, it immediately sends + //a ZRINIT header to initiate ZMODEM file transfers, or a + //ZCHALLENGE header to verify the sending program. The receive + //program resends its header at response time (default 10 second) + //intervals for a suitable period of time (40 seconds total) + //before falling back to YMODEM protocol. + if (this._input_buffer.join() === "67") { + throw "Receiver has fallen back to YMODEM."; + } + } + } + + _on_session_end() { + this._stop_keepalive(); + super._on_session_end(); + } +} + +Object.assign( + Zmodem.Session.Send.prototype, + { + type: "send", + } +); diff --git a/src/zsubpacket.js b/src/zsubpacket.js new file mode 100644 index 0000000..f77a527 --- /dev/null +++ b/src/zsubpacket.js @@ -0,0 +1,241 @@ +"use strict"; + +var Zmodem = module.exports; + +Object.assign( + Zmodem, + require("./zcrc"), + require("./zdle"), + require("./zmlib"), + require("./zerror") +); + +const + ZCRCE = 0x68, // 'h', 104, frame ends, header packet follows + ZCRCG = 0x69, // 'i', 105, frame continues nonstop + ZCRCQ = 0x6a, // 'j', 106, frame continues, ZACK expected + ZCRCW = 0x6b // 'k', 107, frame ends, ZACK expected +; + +var SUBPACKET_BUILDER; + +/** Class that represents a ZMODEM data subpacket. */ +Zmodem.Subpacket = class ZmodemSubpacket { + + /** + * Build a Subpacket subclass given a payload and frame end string. + * + * @param {Array} octets - The octet values to parse. + * Each array member should be an 8-bit unsigned integer (0-255). + * + * @param {string} frameend - One of: + * - `no_end_no_ack` + * - `end_no_ack` + * - `no_end_ack` (unused currently) + * - `end_ack` + * + * @returns {Subpacket} An instance of the appropriate Subpacket subclass. + */ + static build(octets, frameend) { + + //TODO: make this better + var Ctr = SUBPACKET_BUILDER[frameend]; + if (!Ctr) { + throw("No subpacket type “" + frameend + "” is defined! Try one of: " + Object.keys(SUBPACKET_BUILDER).join(", ")); + } + + return new Ctr(octets); + } + + /** + * Return the octet values array that represents the object + * encoded with a 16-bit CRC. + * + * @param {ZDLE} zencoder - A ZDLE instance to use for ZDLE encoding. + * + * @returns {number[]} An array of octet values suitable for sending + * as binary data. + */ + encode16(zencoder) { + return this._encode( zencoder, Zmodem.CRC.crc16 ); + } + + /** + * Return the octet values array that represents the object + * encoded with a 32-bit CRC. + * + * @param {ZDLE} zencoder - A ZDLE instance to use for ZDLE encoding. + * + * @returns {number[]} An array of octet values suitable for sending + * as binary data. + */ + encode32(zencoder) { + return this._encode( zencoder, Zmodem.CRC.crc32 ); + } + + /** + * Return the subpacket payload’s octet values. + * + * NOTE: For speed, this returns the actual data in the subpacket; + * if you mutate this return value, you alter the Subpacket object + * internals. This is OK if you won’t need the Subpacket anymore, but + * just be careful. + * + * @returns {number[]} The subpacket’s payload, represented as an + * array of octet values. **DO NOT ALTER THIS ARRAY** unless you + * no longer need the Subpacket. + */ + get_payload() { return this._payload } + + /** + * Parse out a Subpacket object from a given array of octet values, + * assuming a 16-bit CRC. + * + * An exception is thrown if the given bytes are definitively invalid + * as subpacket values with 16-bit CRC. + * + * @param {number[]} octets - The octet values to parse. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @returns {Subpacket|undefined} An instance of the appropriate Subpacket + * subclass, or undefined if not enough octet values are given + * to determine whether there is a valid subpacket here or not. + */ + static parse16(octets) { + return ZmodemSubpacket._parse(octets, 2); + } + + //parse32 test: + //[102, 105, 108, 101, 110, 97, 109, 101, 119, 105, 116, 104, 115, 112, 97, 99, 101, 115, 0, 49, 55, 49, 51, 49, 52, 50, 52, 51, 50, 49, 55, 50, 49, 48, 48, 54, 52, 52, 48, 49, 49, 55, 0, 43, 8, 63, 115, 23, 17] + + /** + * Same as parse16(), but assuming a 32-bit CRC. + * + * @param {number[]} octets - The octet values to parse. + * Each array member should be an 8-bit unsigned integer (0-255). + * This object is mutated in the function. + * + * @returns {Subpacket|undefined} An instance of the appropriate Subpacket + * subclass, or undefined if not enough octet values are given + * to determine whether there is a valid subpacket here or not. + */ + static parse32(octets) { + return ZmodemSubpacket._parse(octets, 4); + } + + /** + * Not used directly. + */ + constructor(payload) { + this._payload = payload; + } + + _encode(zencoder, crc_func) { + return zencoder.encode( this._payload.slice(0) ).concat( + [ Zmodem.ZMLIB.ZDLE, this._frameend_num ], + zencoder.encode( crc_func( this._payload.concat(this._frameend_num) ) ) + ); + } + + //Because of ZDLE encoding, we’ll never see any of the frame-end octets + //in a stream except as the ends of data payloads. + static _parse(bytes_arr, crc_len) { + + var end_at; + var creator; + + //These have to be written in decimal since they’re lookup keys. + var _frame_ends_lookup = { + 104: ZEndNoAckSubpacket, + 105: ZNoEndNoAckSubpacket, + 106: ZNoEndAckSubpacket, + 107: ZEndAckSubpacket, + }; + + var zdle_at = 0; + while (zdle_at < bytes_arr.length) { + zdle_at = bytes_arr.indexOf( Zmodem.ZMLIB.ZDLE, zdle_at ); + if (zdle_at === -1) return; + + var after_zdle = bytes_arr[ zdle_at + 1 ]; + creator = _frame_ends_lookup[ after_zdle ]; + if (creator) { + end_at = zdle_at + 1; + break; + } + + zdle_at++; + } + + if (!creator) return; + + var frameend_num = bytes_arr[end_at]; + + //sanity check + if (bytes_arr[end_at - 1] !== Zmodem.ZMLIB.ZDLE) { + throw( "Byte before frame end should be ZDLE, not " + bytes_arr[end_at - 1] ); + } + + var zdle_encoded_payload = bytes_arr.splice( 0, end_at - 1 ); + + var got_crc = Zmodem.ZDLE.splice( bytes_arr, 2, crc_len ); + if (!got_crc) { + //got payload but no CRC yet .. should be rare! + + //We have to put the ZDLE-encoded payload back before returning. + bytes_arr.unshift.apply(bytes_arr, zdle_encoded_payload); + + return; + } + + var payload = Zmodem.ZDLE.decode(zdle_encoded_payload); + + //We really shouldn’t need to do this, but just for good measure. + //I suppose it’s conceivable this may run over UDP or something? + Zmodem.CRC[ (crc_len === 2) ? "verify16" : "verify32" ]( + payload.concat( [frameend_num] ), + got_crc + ); + + return new creator(payload, got_crc); + } +} + +class ZEndSubpacketBase extends Zmodem.Subpacket { + frame_end() { return true } +} +class ZNoEndSubpacketBase extends Zmodem.Subpacket { + frame_end() { return false } +} + +//Used for end-of-file. +class ZEndNoAckSubpacket extends ZEndSubpacketBase { + ack_expected() { return false } +} +ZEndNoAckSubpacket.prototype._frameend_num = ZCRCE; + +//Used for ZFILE and ZSINIT payloads. +class ZEndAckSubpacket extends ZEndSubpacketBase { + ack_expected() { return true } +} +ZEndAckSubpacket.prototype._frameend_num = ZCRCW; + +//Used for ZDATA, prior to end-of-file. +class ZNoEndNoAckSubpacket extends ZNoEndSubpacketBase { + ack_expected() { return false } +} +ZNoEndNoAckSubpacket.prototype._frameend_num = ZCRCG; + +//only used if receiver can full-duplex +class ZNoEndAckSubpacket extends ZNoEndSubpacketBase { + ack_expected() { return true } +} +ZNoEndAckSubpacket.prototype._frameend_num = ZCRCQ; + +SUBPACKET_BUILDER = { + end_no_ack: ZEndNoAckSubpacket, + end_ack: ZEndAckSubpacket, + no_end_no_ack: ZNoEndNoAckSubpacket, + no_end_ack: ZNoEndAckSubpacket, +}; diff --git a/src/zvalidation.js b/src/zvalidation.js new file mode 100644 index 0000000..e8618e9 --- /dev/null +++ b/src/zvalidation.js @@ -0,0 +1,130 @@ +"use strict"; + +var Zmodem = module.exports; + +Object.assign( + Zmodem, + require("./zerror") +); + +const LOOKS_LIKE_ZMODEM_HEADER = /\*\x18[AC]|\*\*\x18B/; + +function _validate_number(key, value) { + if (value < 0) { + throw new Zmodem.Error("validation", "“" + key + "” (" + value + ") must be nonnegative."); + } + + if (value !== Math.floor(value)) { + throw new Zmodem.Error("validation", "“" + key + "” (" + value + ") must be an integer."); + } +} + +/** Validation logic for zmodem.js + * + * @exports Validation + */ +Zmodem.Validation = { + + /** + * Validates and normalizes a set of parameters for an offer to send. + * NOTE: This returns “mtime” as epoch seconds, not a Date. This is + * inconsistent with the get_details() method in Session, but it’s + * more useful for sending over the wire. + * + * @param {FileDetails} params - The file details. Some fairly trivial + * variances from the specification are allowed. + * + * @return {FileDetails} The parameters that should be sent. `mtime` + * will be a Date rather than a number. + */ + offer_parameters: function offer_parameters(params) { + if (!params.name) { + throw new Zmodem.Error("validation", "Need “name”!"); + } + + if (typeof params.name !== "string") { + throw new Zmodem.Error("validation", "“name” (" + params.name + ") must be a string!"); + } + + //So that we can override values as is useful + //without affecting the passed-in object. + params = Object.assign({}, params); + + if (LOOKS_LIKE_ZMODEM_HEADER.test(params.name)) { + console.warn("The filename " + JSON.stringify(name) + " contains characters that look like a ZMODEM header. This could corrupt the ZMODEM session; consider renaming it so that the filename doesn’t contain control characters."); + } + + if (params.serial !== null && params.serial !== undefined) { + throw new Zmodem.Error("validation", "“serial” is meaningless."); + } + + params.serial = null; + + ["size", "mode", "files_remaining", "bytes_remaining"].forEach( + function(k) { + var ok; + switch (typeof params[k]) { + case "object": + ok = (params[k] === null); + break; + case "undefined": + params[k] = null; + ok = true; + break; + case "number": + _validate_number(k, params[k]); + + ok = true; + break; + } + + if (!ok) { + throw new Zmodem.Error("validation", "“" + k + "” (" + params[k] + ") must be null, undefined, or a number."); + } + } + ); + + if (typeof params.mode === "number") { + params.mode |= 0x8000; + } + + if (params.files_remaining === 0) { + throw new Zmodem.Error("validation", "“files_remaining”, if given, must be positive."); + } + + var mtime_ok; + switch (typeof params.mtime) { + case "object": + mtime_ok = true; + + if (params.mtime instanceof Date) { + + var date_obj = params.mtime; + params.mtime = Math.floor( date_obj.getTime() / 1000 ); + if (params.mtime < 0) { + throw new Zmodem.Error("validation", "“mtime” (" + date_obj + ") must not be earlier than 1970."); + } + } + else if (params.mtime !== null) { + mtime_ok = false; + } + + break; + + case "undefined": + params.mtime = null; + mtime_ok = true; + break; + case "number": + _validate_number("mtime", params.mtime); + mtime_ok = true; + break; + } + + if (!mtime_ok) { + throw new Zmodem.Error("validation", "“mtime” (" + params.mtime + ") must be null, undefined, a Date, or a number."); + } + + return params; + }, +}; |