@amxts/ftp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kukson777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+<div align="center">
+
+<img src="assets/logo.svg" width="96" alt="FTP">
+
+# FTP
+
+*FTP, FTPS and SFTP for amxts plugins*
+
+[![amxts module](https://img.shields.io/badge/amxts-module-3178c6?style=flat-square)](https://amxts.github.io/)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+[Features](#features) • [Installation](#installation) • [Usage](#usage) • [API](#api)
+
+**English** | [Русский](README.ru.md)
+
+</div>
+
+Game hosts give access to a server's files over FTP, FTPS or SFTP. This library lets an amxts plugin log in to such a server and upload, download and list files there: a log backed up every night, a map list read from a shared server, a demo sent away after a match.
+
+```ts
+import { ftp } from "@amxts/ftp";
+
+const client = await ftp.connect("sftp://backup@example.com", { password });
+await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+const maps = await client.readFile("/configs/maps.ini");
+const entries = await client.list("/configs");             // { name, size, isDirectory, modified }
+await client.close();
+```
+
+## Features
+
+- **FTP, FTPS and SFTP, by the address.** `ftp://`, `ftpes://` (FTP with TLS asked for - explicit FTPS), `ftps://` (TLS from the first byte - implicit FTPS) and `sftp://`.
+- **Never holds the game up.** Every call is a promise; the transfer runs on the server's network client, on a thread of its own, and the promise settles on a later frame.
+- **Files byte for byte.** `upload` and `download` move a file of the game folder - a map, a demo, a log - between the disk and the network without it passing through the plugin, whatever its size.
+- **A password or a key.** SFTP logs in with a password or a private key, and can check the server's host key.
+- **Errors that say what failed.** A wrong password, a missing file, a refused connection or a timeout rejects with an `Error` whose message names the call, the path and the reason - never the password.
+- **A timeout and a signal on every call,** as `fetch` has them.
+
+## Installation
+
+Nothing to install on the game server: the network client is part of amxts.
+
+```bash
+npx amxts module add ftp
+```
+
+It installs the package and adds it to your project's `amxts.config.ts`:
+
+```ts
+export default defineConfig({
+	modules: ["@amxts/ftp"],
+});
+```
+
+`@amxts/ftp` is a library: the build compiles it into each plugin that imports it. A plugin imports it by name - `import { ftp } from "@amxts/ftp"` - and each plugin has its own clients.
+
+## Usage
+
+### Where the password goes
+
+The server's address and password are the server owner's, not the plugin's: keep them in a config file beside the server's other configs, and read it with [config-core](https://github.com/amxts/config-core) (`npx amxts module add config-core`):
+
+```yaml
+# addons/amxmodx/configs/backup.yaml
+url: sftp://backup@files.example.com/cstrike
+password: "correct horse battery staple"
+```
+
+```ts
+import { ftp } from "@amxts/ftp";
+
+interface BackupSettings {
+	/** The server and folder to back up to. */
+	url: string;
+	/** The account's password. */
+	password: string;
+}
+
+const settings = configs.load<BackupSettings>("backup", { url: "", password: "" });
+
+server.addServerCommand("backup_log", backUpLog);
+
+async function backUpLog() {
+	try {
+		const client = await ftp.connect(settings.url, { password: settings.password, timeout: 60_000 });
+		await client.upload("addons/amxmodx/logs/today.log", "logs/today.log");
+		await client.close();
+		console.log("backup: done");
+	} catch (error) {
+		console.error(`backup: ${error.message}`);
+	}
+}
+```
+
+> [!WARNING]
+> **A password in the code goes wherever the code goes** - into git, into a plugin shared with someone else. Keep it in a config file on the server, as above, readable by the server's account only. Prefer an account that may write only to its backup folder; for SFTP, a key (`keyFile`) is better still than a password.
+
+### The address
+
+`ftp.connect(url, options)` logs in and gives a client; it rejects when the login fails.
+
+| Scheme | What it is | Port by default |
+| --- | --- | --- |
+| `ftp://` | plain FTP: the password and the files go unencrypted | 21 |
+| `ftpes://` | FTP with TLS asked for (`AUTH TLS`), required for the commands and the files - explicit FTPS | 21 |
+| `ftps://` | TLS from the first byte - implicit FTPS | 990 |
+| `sftp://` | SFTP over SSH | 22 |
+
+The user can be in the address (`sftp://backup@example.com`) or in `options.user`, and so can the password, though `options.password` keeps it out of an address you might log. A folder in the address (`sftp://example.com/cstrike`) is where relative paths start; a path that starts with `/` starts at the server's root.
+
+### Files
+
+```ts
+await client.upload("demos/match.dem", "demos/match.dem");     // the game folder's file up, its folders made
+await client.download("/maps/de_dust2.bsp", "maps/de_dust2.bsp"); // down into the game folder
+```
+
+A local path is a path of the game folder (`cstrike/`), as everywhere in amxts. A download that fails leaves a file already there as it was.
+
+Text reads and writes without a file on the game server:
+
+```ts
+const maps = await client.readFile("/configs/maps.ini");
+await client.writeFile("/status/online.txt", `${server.players.length}`);
+```
+
+### Listing a folder
+
+```ts
+const entries = await client.list("/configs");
+for (const entry of entries) console.log(`${entry.name} ${entry.isDirectory ? "<dir>" : `${entry.size} B`}`);
+```
+
+Each entry is `{ name, size, isDirectory, modified }`: `modified` is a `Date`, to the minute as the server lists it (to the day for a file older than half a year).
+
+### Errors
+
+A call rejects with an `Error` whose message says what failed:
+
+```
+download /maps/de_dust3.bsp: no such file or folder on files.example.com
+connect ftp://backup@files.example.com: files.example.com refused the login - a wrong user, password or key (reply 530)
+upload logs/today.log: timed out
+```
+
+The message never holds the password.
+
+### Timeouts and cancelling
+
+```ts
+const client = await ftp.connect(url, { password, timeout: 30_000 });   // every call: 30 seconds at most
+await client.download("/maps/big.bsp", "maps/big.bsp", { timeout: 300_000 });
+
+const controller = new AbortController();
+const pending = client.list("/", { signal: controller.signal });
+controller.abort();                                               // rejects with the signal's reason
+```
+
+Without a `timeout`, a call has no limit, besides 30 seconds to connect. In an async command handler or a player's event, the player leaving cancels the call.
+
+### SFTP with a key
+
+```ts
+const client = await ftp.connect("sftp://backup@files.example.com", {
+	keyFile: "addons/amxmodx/data/backup_key",                     // a file of the game folder
+	keyPassphrase: settings.keyPassphrase,                          // when the key is encrypted
+	hostKey: "nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8",        // ssh-keygen -lf, without SHA256:
+});
+```
+
+> [!WARNING]
+> **An SSH key is RSA in PEM:** `ssh-keygen -t rsa -m PEM -f backup_key`. A key in OpenSSH's own format (`BEGIN OPENSSH PRIVATE KEY`, what `ssh-keygen` writes by default) or an Ed25519 key is not read; convert one with `ssh-keygen -p -m PEM -f backup_key`.
+>
+> **Without `hostKey`, any server key is taken.** Give the fingerprint to be sure the server is the one you mean.
+
+## API
+
+| Member | What it is |
+| --- | --- |
+| `ftp.connect(url, options?)` | Logs in and gives an `FtpClient`; rejects when the login fails. `options`: `user`, `password`, `keyFile`, `keyPassphrase`, `hostKey`, `ca` (FTPS: the certificate authorities, PEM, for a certificate of the server's own), `timeout` (ms, every call). |
+| `client.upload(localPath, remotePath, options?)` | A file of the game folder up, byte for byte, its remote folders made. |
+| `client.download(remotePath, localPath, options?)` | A remote file down into the game folder, byte for byte. |
+| `client.readFile(remotePath, options?)` | A remote file's text, as UTF-8. |
+| `client.writeFile(remotePath, text, options?)` | Text into a remote file, as UTF-8, its remote folders made. |
+| `client.list(remotePath?, options?)` | The folder's entries: `{ name, size, isDirectory, modified }`. |
+| `client.close()` | Ends the client: a call after it rejects. |
+
+Each call's `options` are `{ timeout, signal }`.

package/README.ru.md

@@ -0,0 +1,188 @@
+<div align="center">
+
+<img src="assets/logo.svg" width="96" alt="FTP">
+
+# FTP
+
+*FTP, FTPS и SFTP для плагинов amxts*
+
+[![amxts module](https://img.shields.io/badge/amxts-module-3178c6?style=flat-square)](https://amxts.github.io/)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+[Возможности](#возможности) • [Установка](#установка) • [Использование](#использование) • [API](#api)
+
+[English](README.md) | **Русский**
+
+</div>
+
+Игровые хостинги дают доступ к файлам сервера по FTP, FTPS или SFTP. Эта библиотека позволяет плагину amxts войти на такой сервер и загружать, скачивать и перечислять там файлы: лог, который каждую ночь уходит в резервную копию, список карт с общего сервера, демо, отправленное после матча.
+
+```ts
+import { ftp } from "@amxts/ftp";
+
+const client = await ftp.connect("sftp://backup@example.com", { password });
+await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+const maps = await client.readFile("/configs/maps.ini");
+const entries = await client.list("/configs");             // { name, size, isDirectory, modified }
+await client.close();
+```
+
+## Возможности
+
+- **FTP, FTPS и SFTP — по адресу.** `ftp://`, `ftpes://` (FTP с запросом TLS — явный FTPS), `ftps://` (TLS с первого байта — неявный FTPS) и `sftp://`.
+- **Никогда не держит игру.** Каждый вызов — промис; передача идёт в сетевом клиенте сервера, в отдельном потоке, а промис выполняется на одном из следующих кадров.
+- **Файлы байт в байт.** `upload` и `download` переносят файл игровой папки — карту, демо, лог — между диском и сетью, не пропуская его через плагин, какого бы размера он ни был.
+- **Пароль или ключ.** SFTP входит по паролю или закрытому ключу и может проверить ключ хоста сервера.
+- **Ошибки говорят, что не так.** Неверный пароль, отсутствующий файл, отказ в соединении или таймаут отклоняют промис с `Error`, в сообщении которого — вызов, путь и причина, но никогда не пароль.
+- **Таймаут и сигнал у каждого вызова,** как у `fetch`.
+
+## Установка
+
+На игровой сервер ничего ставить не нужно: сетевой клиент — часть amxts.
+
+```bash
+npx amxts module add ftp
+```
+
+Команда ставит пакет и добавляет его в `amxts.config.ts` проекта:
+
+```ts
+export default defineConfig({
+	modules: ["@amxts/ftp"],
+});
+```
+
+`@amxts/ftp` — библиотека: сборка компилирует её в каждый плагин, который её импортирует. Плагин импортирует её по имени — `import { ftp } from "@amxts/ftp"`, — и у каждого плагина свои клиенты.
+
+## Использование
+
+### Где хранить пароль
+
+Адрес сервера и пароль принадлежат владельцу сервера, а не плагину: храните их в конфиге рядом с остальными конфигами сервера и читайте его через [config-core](https://github.com/amxts/config-core) (`npx amxts module add config-core`):
+
+```yaml
+# addons/amxmodx/configs/backup.yaml
+url: sftp://backup@files.example.com/cstrike
+password: "correct horse battery staple"
+```
+
+```ts
+import { ftp } from "@amxts/ftp";
+
+interface BackupSettings {
+	/** Сервер и папка для резервных копий. */
+	url: string;
+	/** Пароль учётной записи. */
+	password: string;
+}
+
+const settings = configs.load<BackupSettings>("backup", { url: "", password: "" });
+
+server.addServerCommand("backup_log", backUpLog);
+
+async function backUpLog() {
+	try {
+		const client = await ftp.connect(settings.url, { password: settings.password, timeout: 60_000 });
+		await client.upload("addons/amxmodx/logs/today.log", "logs/today.log");
+		await client.close();
+		console.log("backup: done");
+	} catch (error) {
+		console.error(`backup: ${error.message}`);
+	}
+}
+```
+
+> [!WARNING]
+> **Пароль в коде уходит туда же, куда и код** — в git, в плагин, которым поделились с кем-то ещё. Храните его в конфиге на сервере, как выше, доступном для чтения только учётной записи сервера. Лучше учётная запись, которая может писать только в свою папку для копий; для SFTP ключ (`keyFile`) ещё лучше пароля.
+
+### Адрес
+
+`ftp.connect(url, options)` входит на сервер и даёт клиент; промис отклоняется, если вход не удался.
+
+| Схема | Что это | Порт по умолчанию |
+| --- | --- | --- |
+| `ftp://` | обычный FTP: пароль и файлы идут без шифрования | 21 |
+| `ftpes://` | FTP с запросом TLS (`AUTH TLS`), обязательным для команд и файлов, — явный FTPS | 21 |
+| `ftps://` | TLS с первого байта — неявный FTPS | 990 |
+| `sftp://` | SFTP поверх SSH | 22 |
+
+Пользователь может быть в адресе (`sftp://backup@example.com`) или в `options.user`, как и пароль, хотя `options.password` не даёт ему попасть в адрес, который может оказаться в логе. Папка в адресе (`sftp://example.com/cstrike`) — то, откуда начинаются относительные пути; путь, начинающийся с `/`, начинается от корня сервера.
+
+### Файлы
+
+```ts
+await client.upload("demos/match.dem", "demos/match.dem");     // файл игровой папки наверх, его папки создаются
+await client.download("/maps/de_dust2.bsp", "maps/de_dust2.bsp"); // вниз, в игровую папку
+```
+
+Локальный путь — путь игровой папки (`cstrike/`), как и везде в amxts. Неудачное скачивание оставляет уже существующий файл как был.
+
+Текст читается и пишется без файла на игровом сервере:
+
+```ts
+const maps = await client.readFile("/configs/maps.ini");
+await client.writeFile("/status/online.txt", `${server.players.length}`);
+```
+
+### Содержимое папки
+
+```ts
+const entries = await client.list("/configs");
+for (const entry of entries) console.log(`${entry.name} ${entry.isDirectory ? "<dir>" : `${entry.size} B`}`);
+```
+
+Каждая запись — `{ name, size, isDirectory, modified }`: `modified` — `Date` с точностью до минуты, как её даёт сервер (до дня у файла старше полугода).
+
+### Ошибки
+
+Вызов отклоняется с `Error`, в сообщении которого сказано, что не так:
+
+```
+download /maps/de_dust3.bsp: no such file or folder on files.example.com
+connect ftp://backup@files.example.com: files.example.com refused the login - a wrong user, password or key (reply 530)
+upload logs/today.log: timed out
+```
+
+Пароля в сообщении нет никогда.
+
+### Таймауты и отмена
+
+```ts
+const client = await ftp.connect(url, { password, timeout: 30_000 });   // каждый вызов — не дольше 30 секунд
+await client.download("/maps/big.bsp", "maps/big.bsp", { timeout: 300_000 });
+
+const controller = new AbortController();
+const pending = client.list("/", { signal: controller.signal });
+controller.abort();                                               // отклоняется с причиной сигнала
+```
+
+Без `timeout` у вызова нет ограничения, кроме 30 секунд на соединение. В асинхронном обработчике команды или события игрока уход игрока отменяет вызов.
+
+### SFTP с ключом
+
+```ts
+const client = await ftp.connect("sftp://backup@files.example.com", {
+	keyFile: "addons/amxmodx/data/backup_key",                     // файл игровой папки
+	keyPassphrase: settings.keyPassphrase,                          // если ключ зашифрован
+	hostKey: "nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8",        // ssh-keygen -lf, без SHA256:
+});
+```
+
+> [!WARNING]
+> **Ключ SSH — RSA в PEM:** `ssh-keygen -t rsa -m PEM -f backup_key`. Ключ в собственном формате OpenSSH (`BEGIN OPENSSH PRIVATE KEY`, его `ssh-keygen` пишет по умолчанию) или ключ Ed25519 не читается; переведите его командой `ssh-keygen -p -m PEM -f backup_key`.
+>
+> **Без `hostKey` принимается любой ключ сервера.** Укажите отпечаток, чтобы быть уверенным, что сервер — тот самый.
+
+## API
+
+| Член | Что это |
+| --- | --- |
+| `ftp.connect(url, options?)` | Входит на сервер и даёт `FtpClient`; отклоняется, если вход не удался. `options`: `user`, `password`, `keyFile`, `keyPassphrase`, `hostKey`, `ca` (FTPS: удостоверяющие центры, PEM, для собственного сертификата сервера), `timeout` (мс, каждый вызов). |
+| `client.upload(localPath, remotePath, options?)` | Файл игровой папки наверх байт в байт, удалённые папки создаются. |
+| `client.download(remotePath, localPath, options?)` | Удалённый файл вниз, в игровую папку, байт в байт. |
+| `client.readFile(remotePath, options?)` | Текст удалённого файла как UTF-8. |
+| `client.writeFile(remotePath, text, options?)` | Текст в удалённый файл как UTF-8, удалённые папки создаются. |
+| `client.list(remotePath?, options?)` | Записи папки: `{ name, size, isDirectory, modified }`. |
+| `client.close()` | Закрывает клиент: вызов после этого отклоняется. |
+
+`options` каждого вызова — `{ timeout, signal }`.

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@amxts/ftp",
+	"type": "module",
+	"version": "0.1.0",
+	"description": "FTP, FTPS and SFTP for amxts plugins: upload, download and list files on another server, every call a promise that never holds the game up.",
+	"author": {
+		"name": "kukson777",
+		"url": "https://github.com/kukson777"
+	},
+	"license": "MIT",
+	"homepage": "https://github.com/amxts/ftp#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/amxts/ftp.git"
+	},
+	"keywords": [
+		"amxts-module",
+		"amxts-ftp",
+		"ftp",
+		"ftps",
+		"sftp",
+		"amxmodx",
+		"counter-strike"
+	],
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"types": "./src/index.ts",
+	"files": [
+		"README.md",
+		"README.ru.md",
+		"scripts/docs",
+		"src"
+	],
+	"amxts": {
+		"module": "src/index.ts",
+		"library": true
+	},
+	"scripts": {
+		"test": "bun test",
+		"check": "amxts check",
+		"lint": "oxlint && oxfmt --check",
+		"lint:fix": "oxfmt && oxlint --fix --silent || oxlint --fix --silent || oxlint --fix"
+	},
+	"peerDependencies": {
+		"@amxts/core": "^0.2.0"
+	},
+	"devDependencies": {
+		"@e18e/eslint-plugin": "^0.8.1",
+		"@eslint-community/eslint-plugin-eslint-comments": "^4.8.1",
+		"@stylistic/eslint-plugin": "^5.10.0",
+		"@types/bun": "^1.4.2",
+		"basic-ftp": "^6.2.1",
+		"eslint-plugin-antfu": "^3.2.3",
+		"eslint-plugin-command": "^4.0.0",
+		"eslint-plugin-n": "^18.4.0",
+		"eslint-plugin-perfectionist": "^5.12.1",
+		"eslint-plugin-regexp": "^3.3.1",
+		"ftp-srv": "^4.6.3",
+		"oxfmt": "^0.70.0",
+		"oxlint": "^1.85.0",
+		"ssh2": "^1.17.0",
+		"ssh2-sftp-client": "^12.1.1",
+		"typescript": "^6.0.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/scripts/docs/src/index.ts

@@ -0,0 +1,256 @@
+// The tooltips of src/index.ts, in both languages: scripts/apply-docs.ts writes the
+// one AMXTS_DOCS_LANG picks into the JSDoc above each element.
+export default {
+	'FtpOptions': {
+		en: `How \`ftp.connect\` logs in, and what every call of the client takes by default.`,
+		ru: `Как \`ftp.connect\` входит на сервер и что каждый вызов клиента берёт по умолчанию.`,
+	},
+	'FtpOptions.user': {
+		en: `The user to log in as; the address's own (\`sftp://admin@example.com\`) when left out.`,
+		ru: `Пользователь для входа; если не указан — из адреса (\`sftp://admin@example.com\`).`,
+	},
+	'FtpOptions.password': {
+		en: `The password to log in with; the address's own when left out.`,
+		ru: `Пароль для входа; если не указан — из адреса.`,
+	},
+	'FtpOptions.keyFile': {
+		en: `
+			SFTP: the private key to log in with, a file of the game folder
+			(\`addons/amxmodx/data/backup_key\`) - an RSA key in PEM.
+		`,
+		ru: `
+			SFTP: закрытый ключ для входа, файл игровой папки
+			(\`addons/amxmodx/data/backup_key\`), — ключ RSA в PEM.
+		`,
+	},
+	'FtpOptions.keyPassphrase': {
+		en: `SFTP: the passphrase \`keyFile\` is encrypted with.`,
+		ru: `SFTP: пароль, которым зашифрован \`keyFile\`.`,
+	},
+	'FtpOptions.hostKey': {
+		en: `
+			SFTP: the server's host key, its SHA-256 fingerprint in base64 as
+			\`ssh-keygen -lf\` prints it, without \`SHA256:\`. A server with another key
+			is refused; left out, any host key is taken.
+		`,
+		ru: `
+			SFTP: ключ хоста сервера — его отпечаток SHA-256 в base64, как его печатает
+			\`ssh-keygen -lf\`, без \`SHA256:\`. Сервер с другим ключом отвергается;
+			если не указан, принимается любой ключ хоста.
+		`,
+	},
+	'FtpOptions.ca': {
+		en: `
+			FTPS: the certificate authorities the server's certificate must come
+			from, as PEM text - for a server with a certificate of its own making.
+			Left out, the ones a browser trusts.
+		`,
+		ru: `
+			FTPS: удостоверяющие центры, которыми должен быть выдан сертификат
+			сервера, текстом PEM, — для сервера с самодельным сертификатом.
+			Если не указаны — те, которым доверяет браузер.
+		`,
+	},
+	'FtpOptions.timeout': {
+		en: `Milliseconds each call may take before it fails; no limit by default.`,
+		ru: `Сколько миллисекунд может длиться каждый вызов, прежде чем он завершится ошибкой; по умолчанию без ограничения.`,
+	},
+	'FtpCallOptions': {
+		en: `One call's own options: \`upload\`'s, \`download\`'s and the others' last argument.`,
+		ru: `Параметры одного вызова: последний аргумент \`upload\`, \`download\` и остальных.`,
+	},
+	'FtpCallOptions.timeout': {
+		en: `Milliseconds this call may take before it fails; the client's \`timeout\` when left out.`,
+		ru: `Сколько миллисекунд может длиться этот вызов, прежде чем он завершится ошибкой; если не указано — \`timeout\` клиента.`,
+	},
+	'FtpCallOptions.signal': {
+		en: `A signal that cancels the call; the promise then rejects with the signal's reason.`,
+		ru: `Сигнал, отменяющий вызов; промис тогда отклоняется с причиной сигнала.`,
+	},
+	'FtpEntry': {
+		en: `A file or a folder in a listing.`,
+		ru: `Файл или папка в списке.`,
+	},
+	'FtpEntry.name': {
+		en: `The entry's name, without its folder, e.g. \`"maps.ini"\`.`,
+		ru: `Имя записи без папки, например \`"maps.ini"\`.`,
+	},
+	'FtpEntry.size': {
+		en: `The entry's size in bytes; a folder's as the server gives it.`,
+		ru: `Размер записи в байтах; у папки — какой даёт сервер.`,
+	},
+	'FtpEntry.isDirectory': {
+		en: `\`true\` for a folder.`,
+		ru: `\`true\` для папки.`,
+	},
+	'FtpEntry.modified': {
+		en: `The entry's last change, as the server lists it: to the minute, or to the day for an older file.`,
+		ru: `Время последнего изменения записи, как его даёт сервер: с точностью до минуты, у старого файла — до дня.`,
+	},
+	'FtpClient': {
+		en: `
+			A connection to an FTP, FTPS or SFTP server, from \`ftp.connect\`. Every call
+			returns a promise and runs on the server's network client.
+
+			\`\`\`ts
+			await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+			const entries = await client.list("/backup");
+			await client.close();
+			\`\`\`
+		`,
+		ru: `
+			Подключение к серверу FTP, FTPS или SFTP из \`ftp.connect\`. Каждый вызов
+			возвращает промис и выполняется сетевым клиентом сервера.
+
+			\`\`\`ts
+			await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+			const entries = await client.list("/backup");
+			await client.close();
+			\`\`\`
+		`,
+	},
+	'FtpClient.upload': {
+		en: `
+			Sends a file of the game folder to \`remotePath\`, byte for byte - a log, a
+			map, a demo - making the remote folders that are not there.
+
+			\`\`\`ts
+			await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+			\`\`\`
+		`,
+		ru: `
+			Отправляет файл игровой папки в \`remotePath\` байт в байт — лог, карту,
+			демо, — создавая удалённые папки, которых нет.
+
+			\`\`\`ts
+			await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+			\`\`\`
+		`,
+	},
+	'FtpClient.download': {
+		en: `
+			Fetches \`remotePath\` into a file of the game folder, byte for byte. A
+			download that fails leaves a file already there as it was.
+
+			\`\`\`ts
+			await client.download("/maps/de_dust2.bsp", "maps/de_dust2.bsp");
+			\`\`\`
+		`,
+		ru: `
+			Скачивает \`remotePath\` в файл игровой папки байт в байт. Неудачная
+			загрузка оставляет уже существующий файл как был.
+
+			\`\`\`ts
+			await client.download("/maps/de_dust2.bsp", "maps/de_dust2.bsp");
+			\`\`\`
+		`,
+	},
+	'FtpClient.readFile': {
+		en: `
+			The text of \`remotePath\`, read as UTF-8 - a config, a list.
+
+			\`\`\`ts
+			const maps = await client.readFile("/configs/maps.ini");
+			\`\`\`
+		`,
+		ru: `
+			Текст \`remotePath\`, прочитанный как UTF-8, — конфиг, список.
+
+			\`\`\`ts
+			const maps = await client.readFile("/configs/maps.ini");
+			\`\`\`
+		`,
+	},
+	'FtpClient.writeFile': {
+		en: `
+			Writes \`text\` to \`remotePath\` as UTF-8, in place of what was there,
+			making the remote folders that are not there.
+
+			\`\`\`ts
+			await client.writeFile("/status/online.txt", \`\${server.players.length}\`);
+			\`\`\`
+		`,
+		ru: `
+			Записывает \`text\` в \`remotePath\` как UTF-8 вместо того, что там было,
+			создавая удалённые папки, которых нет.
+
+			\`\`\`ts
+			await client.writeFile("/status/online.txt", \`\${server.players.length}\`);
+			\`\`\`
+		`,
+	},
+	'FtpClient.list': {
+		en: `
+			The files and folders in \`remotePath\` - the folder of \`ftp.connect\`'s
+			address when left out.
+
+			\`\`\`ts
+			const entries = await client.list("/configs");
+			const big = entries.filter((entry) => !entry.isDirectory && entry.size > 1_000_000);
+			\`\`\`
+		`,
+		ru: `
+			Файлы и папки в \`remotePath\`; если путь не указан — в папке адреса
+			\`ftp.connect\`.
+
+			\`\`\`ts
+			const entries = await client.list("/configs");
+			const big = entries.filter((entry) => !entry.isDirectory && entry.size > 1_000_000);
+			\`\`\`
+		`,
+	},
+	'FtpClient.close': {
+		en: `Ends the client: a call after it rejects.`,
+		ru: `Закрывает клиент: вызов после этого отклоняется.`,
+	},
+	'Ftp': {
+		en: `
+			Connects to an FTP, FTPS or SFTP server - \`ftp\`, imported from
+			\`@amxts/ftp\`.
+
+			\`\`\`ts
+			import { ftp } from "@amxts/ftp";
+
+			const client = await ftp.connect("sftp://backup@example.com", { password });
+			\`\`\`
+		`,
+		ru: `
+			Подключается к серверу FTP, FTPS или SFTP — \`ftp\`, импортированный из
+			\`@amxts/ftp\`.
+
+			\`\`\`ts
+			import { ftp } from "@amxts/ftp";
+
+			const client = await ftp.connect("sftp://backup@example.com", { password });
+			\`\`\`
+		`,
+	},
+	'Ftp.connect': {
+		en: `
+			Logs in to the server of \`url\` and gives a client for it; rejects when
+			the login fails. The scheme says how: \`ftp:\` plain FTP, \`ftpes:\` FTP
+			with TLS asked for (explicit FTPS), \`ftps:\` TLS from the first byte
+			(implicit FTPS), \`sftp:\` SFTP over SSH. A folder in the address is where
+			relative paths start.
+
+			\`\`\`ts
+			const client = await ftp.connect("ftpes://files.example.com:2121/backup", { user: "cs", password });
+			\`\`\`
+		`,
+		ru: `
+			Входит на сервер \`url\` и даёт клиент для него; отклоняется, если вход не
+			удался. Схема говорит как: \`ftp:\` — обычный FTP, \`ftpes:\` — FTP с
+			запросом TLS (явный FTPS), \`ftps:\` — TLS с первого байта (неявный
+			FTPS), \`sftp:\` — SFTP поверх SSH. Папка в адресе — то, откуда
+			начинаются относительные пути.
+
+			\`\`\`ts
+			const client = await ftp.connect("ftpes://files.example.com:2121/backup", { user: "cs", password });
+			\`\`\`
+		`,
+	},
+	'ftp': {
+		en: `Connects to an FTP, FTPS or SFTP server: \`ftp.connect(url, options)\`.`,
+		ru: `Подключается к серверу FTP, FTPS или SFTP: \`ftp.connect(url, options)\`.`,
+	},
+};

package/src/index.ts

@@ -0,0 +1,378 @@
+/**
+ * FTP, FTPS and SFTP for amxts plugins: a client that logs in once, then
+ * uploads, downloads and lists files - every call a request of the server's
+ * network client, settled on a later frame, so the game never waits. A
+ * library: the build compiles it into each plugin that imports it. How to
+ * use it: README.md.
+ */
+import { URL } from "@amxts/core";
+import { request, RequestOptions, RequestResult } from "@amxts/core/kit";
+
+/** How `ftp.connect` logs in, and what every call of the client takes by default. */
+export interface FtpOptions {
+	/** The user to log in as; the address's own (`sftp://admin@example.com`) when left out. */
+	user?: string;
+	/** The password to log in with; the address's own when left out. */
+	password?: string;
+	/**
+	 * SFTP: the private key to log in with, a file of the game folder
+	 * (`addons/amxmodx/data/backup_key`) - an RSA key in PEM.
+	 */
+	keyFile?: string;
+	/** SFTP: the passphrase `keyFile` is encrypted with. */
+	keyPassphrase?: string;
+	/**
+	 * SFTP: the server's host key, its SHA-256 fingerprint in base64 as
+	 * `ssh-keygen -lf` prints it, without `SHA256:`. A server with another key
+	 * is refused; left out, any host key is taken.
+	 */
+	hostKey?: string;
+	/**
+	 * FTPS: the certificate authorities the server's certificate must come
+	 * from, as PEM text - for a server with a certificate of its own making.
+	 * Left out, the ones a browser trusts.
+	 */
+	ca?: string;
+	/** Milliseconds each call may take before it fails; no limit by default. */
+	timeout?: number;
+}
+
+/** One call's own options: `upload`'s, `download`'s and the others' last argument. */
+export interface FtpCallOptions {
+	/** Milliseconds this call may take before it fails; the client's `timeout` when left out. */
+	timeout?: number;
+	/** A signal that cancels the call; the promise then rejects with the signal's reason. */
+	signal?: AbortSignal | null;
+}
+
+/** A file or a folder in a listing. */
+export interface FtpEntry {
+	/** The entry's name, without its folder, e.g. `"maps.ini"`. */
+	name: string;
+	/** The entry's size in bytes; a folder's as the server gives it. */
+	size: number;
+	/** `true` for a folder. */
+	isDirectory: boolean;
+	/** The entry's last change, as the server lists it: to the minute, or to the day for an older file. */
+	modified: Date;
+}
+
+/** Where a client's addresses start: the protocol, the host and the folder of `ftp.connect`'s address. */
+interface Origin {
+	/** `"ftp:"`, `"ftpes:"`, `"ftps:"` or `"sftp:"`, as the address has it. */
+	scheme: string;
+	/** The host and its port, e.g. `"example.com:2121"`. */
+	host: string;
+	/** The address's folder, encoded, without a slash at the end: `""` or `"/backup"`. */
+	folder: string;
+}
+
+/**
+ * A connection to an FTP, FTPS or SFTP server, from `ftp.connect`. Every call
+ * returns a promise and runs on the server's network client.
+ *
+ * ```ts
+ * await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+ * const entries = await client.list("/backup");
+ * await client.close();
+ * ```
+ */
+export class FtpClient {
+	private closed = false;
+
+	constructor(private readonly origin: Origin, private readonly user: string, private readonly login: FtpOptions) {}
+
+	/**
+	 * Sends a file of the game folder to `remotePath`, byte for byte - a log, a
+	 * map, a demo - making the remote folders that are not there.
+	 *
+	 * ```ts
+	 * await client.upload("addons/amxmodx/logs/today.log", "/backup/today.log");
+	 * ```
+	 */
+	async upload(localPath: string, remotePath: string, options: FtpCallOptions = {}) {
+		const transfer = this.requestOptions(options);
+		transfer.upload = true;
+		transfer.createDirs = true;
+		transfer.file = localPath;
+		await this.send("upload", remotePath, this.address(remotePath, false), transfer);
+	}
+
+	/**
+	 * Fetches `remotePath` into a file of the game folder, byte for byte. A
+	 * download that fails leaves a file already there as it was.
+	 *
+	 * ```ts
+	 * await client.download("/maps/de_dust2.bsp", "maps/de_dust2.bsp");
+	 * ```
+	 */
+	async download(remotePath: string, localPath: string, options: FtpCallOptions = {}) {
+		const transfer = this.requestOptions(options);
+		transfer.file = localPath;
+		await this.send("download", remotePath, this.address(remotePath, false), transfer);
+	}
+
+	/**
+	 * The text of `remotePath`, read as UTF-8 - a config, a list.
+	 *
+	 * ```ts
+	 * const maps = await client.readFile("/configs/maps.ini");
+	 * ```
+	 */
+	async readFile(remotePath: string, options: FtpCallOptions = {}) {
+		const result = await this.send("readFile", remotePath, this.address(remotePath, false), this.requestOptions(options));
+		return result.text();
+	}
+
+	/**
+	 * Writes `text` to `remotePath` as UTF-8, in place of what was there,
+	 * making the remote folders that are not there.
+	 *
+	 * ```ts
+	 * await client.writeFile("/status/online.txt", `${server.players.length}`);
+	 * ```
+	 */
+	async writeFile(remotePath: string, text: string, options: FtpCallOptions = {}) {
+		const transfer = this.requestOptions(options);
+		transfer.upload = true;
+		transfer.createDirs = true;
+		transfer.body = text;
+		await this.send("writeFile", remotePath, this.address(remotePath, false), transfer);
+	}
+
+	/**
+	 * The files and folders in `remotePath` - the folder of `ftp.connect`'s
+	 * address when left out.
+	 *
+	 * ```ts
+	 * const entries = await client.list("/configs");
+	 * const big = entries.filter((entry) => !entry.isDirectory && entry.size > 1_000_000);
+	 * ```
+	 */
+	async list(remotePath?: string, options: FtpCallOptions = {}) {
+		const path = remotePath ?? "";
+		const result = await this.send("list", path, this.address(path, true), this.requestOptions(options));
+		return parseListing(result.text());
+	}
+
+	/** Ends the client: a call after it rejects. */
+	async close() {
+		this.closed = true;
+	}
+
+	/** @hidden checks the login: the folder of the address entered, nothing transferred. */
+	async __check() {
+		const check = this.requestOptions({});
+		check.method = "HEAD";
+		await this.send("connect", "", this.address("", true), check);
+	}
+
+	/** The request's options: the login, then the call's timeout and signal. */
+	private requestOptions(options: FtpCallOptions) {
+		const login = this.login;
+		const transfer: RequestOptions = {
+			user: this.user,
+			password: login.password,
+			keyFile: login.keyFile,
+			keyPassphrase: login.keyPassphrase,
+			hostKey: login.hostKey,
+			ca: login.ca,
+			signal: options.signal ?? null,
+		};
+		const timeout = options.timeout ?? login.timeout;
+		if (timeout !== undefined) transfer.timeout = timeout;
+		// ftpes: TLS asked for on a plain FTP connection, and required.
+		if (this.origin.scheme == "ftpes:") transfer.ssl = "all";
+		return transfer;
+	}
+
+	/**
+	 * The address of `path` as the network client reads it. An absolute path
+	 * starts at the server's root, a relative one at the folder of
+	 * `ftp.connect`'s address. FTP counts a URL's path from the login folder
+	 * (`%2F` is its root); SFTP from the root (`/~` is the login folder).
+	 */
+	private address(path: string, folder: boolean) {
+		const origin = this.origin;
+		const scheme = schemeOf(origin.scheme);
+		const sftp = scheme == "sftp:";
+		const relative = !path.startsWith("/");
+		const start = relative ? origin.folder || (sftp ? "/~" : "") : sftp ? "" : "/%2F";
+		const rest = encodePath(relative ? path : path.slice(1));
+		const joined = rest.length > 0 ? `${start}/${rest}` : start;
+		const tail = folder && !joined.endsWith("/") ? "/" : "";
+		return `${scheme}//${origin.host}${joined}${tail}`;
+	}
+
+	/** Sends a request; its result, or a rejection that says what failed. */
+	private async send(action: string, path: string, url: string, transfer: RequestOptions) {
+		if (this.closed) throw new Error(`${action} ${path}: the FTP client is closed`);
+
+		const result = await request(url, transfer);
+		if (result.errorKind == "") return result;
+		throw this.failure(action, path, result, transfer.signal ?? null);
+	}
+
+	/** What failed, in words: the action, the path and why - never the password. */
+	private failure(action: string, path: string, result: RequestResult, signal: AbortSignal | null) {
+		const reason = signal ? signal.reason : null;
+		if (result.errorKind == "aborted" && reason) return reason;
+
+		const host = this.origin.host;
+		const what = path.length > 0 ? `${action} ${path}` : `${action} ${this.origin.scheme}//${this.user.length > 0 ? `${this.user}@` : ""}${host}`;
+		const reply = result.replyCode > 0 ? ` (reply ${result.replyCode})` : "";
+		const because = reasonOf(result.errorKind) || `failed: ${result.errorText}`;
+		return new Error(this.hidden(`${what}: ${because.replace("{host}", host)}${reply}`));
+	}
+
+	/** `text` with the password, should a server repeat it, as `***`. */
+	private hidden(text: string) {
+		const password = this.login.password ?? "";
+		return password.length > 0 ? text.replaceAll(password, "***") : text;
+	}
+}
+
+/** Why a call failed, by the network client's kind of error; `{host}` is the server. */
+function reasonOf(kind: string) {
+	switch (kind) {
+		case "login":
+			return "{host} refused the login - a wrong user, password or key";
+		case "denied":
+			return "{host} denied it - the account may not do this here";
+		case "notFound":
+			return "no such file or folder on {host}";
+		case "refused":
+			return "could not connect to {host} - it is down, unknown or refuses the connection";
+		case "timeout":
+			return "timed out";
+		case "tls":
+			return "the secure connection to {host} failed - its certificate or host key is not trusted";
+		case "aborted":
+			return "aborted";
+		default:
+			return "";
+	}
+}
+
+/** The network client's scheme for one `ftp.connect` takes - `ftpes:` is FTP with TLS asked for - or `""`. */
+function schemeOf(protocol: string) {
+	if (protocol == "ftpes:") return "ftp:";
+	return protocol == "ftp:" || protocol == "ftps:" || protocol == "sftp:" ? protocol : "";
+}
+
+/**
+ * Connects to an FTP, FTPS or SFTP server - `ftp`, imported from
+ * `@amxts/ftp`.
+ *
+ * ```ts
+ * import { ftp } from "@amxts/ftp";
+ *
+ * const client = await ftp.connect("sftp://backup@example.com", { password });
+ * ```
+ */
+export class Ftp {
+	/**
+	 * Logs in to the server of `url` and gives a client for it; rejects when
+	 * the login fails. The scheme says how: `ftp:` plain FTP, `ftpes:` FTP
+	 * with TLS asked for (explicit FTPS), `ftps:` TLS from the first byte
+	 * (implicit FTPS), `sftp:` SFTP over SSH. A folder in the address is where
+	 * relative paths start.
+	 *
+	 * ```ts
+	 * const client = await ftp.connect("ftpes://files.example.com:2121/backup", { user: "cs", password });
+	 * ```
+	 */
+	async connect(url: string, options: FtpOptions = {}) {
+		const address = URL.parse(url);
+		if (!address) throw new TypeError("ftp.connect: the address is not a URL, e.g. sftp://user@example.com");
+
+		if (schemeOf(address.protocol).length == 0) throw new TypeError(`ftp.connect: ${address.protocol} is not one of ftp:, ftpes:, ftps: or sftp:`);
+
+		const login: FtpOptions = { ...options };
+		login.password = options.password ?? decodeURIComponent(address.password);
+		const origin: Origin = {
+			scheme: address.protocol,
+			host: address.host,
+			folder: address.pathname.endsWith("/") ? address.pathname.slice(0, -1) : address.pathname,
+		};
+		const client = new FtpClient(origin, options.user ?? decodeURIComponent(address.username), login);
+		await client.__check();
+		return client;
+	}
+}
+
+/** Connects to an FTP, FTPS or SFTP server: `ftp.connect(url, options)`. */
+export const ftp = new Ftp();
+
+/** A path's segments percent-encoded, its slashes kept: `"my maps/a#1.bsp"` as `"my%20maps/a%231.bsp"`. */
+function encodePath(path: string) {
+	return path.split("/").map(encodeURIComponent).join("/");
+}
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+
+// A Unix listing's line: `drwxr-xr-x 2 owner group 4096 Oct  1 21:05 name`,
+// the group left out by some servers, a year in place of the time for an
+// older file.
+const UNIX_LINE = /^([-bcdlps])\S*\s+\d+\s+\S+(?:\s+\S+)?\s+(\d+)\s+([a-z]{3})\s+(\d{1,2})\s+(\d{1,2}:\d{2}|\d{4})\s+(\S.*)$/i;
+
+// A Windows server's: `10-01-24  09:05PM       <DIR>          name`.
+const DOS_LINE = /^(\d{2})-(\d{2})-(\d{2,4})\s+(\d{1,2}):(\d{2})([AP]M)\s+(<DIR>|\d+)\s+(\S.*)$/i;
+
+/** A listing, a line an entry, without `.` and `..`. */
+function parseListing(text: string) {
+	const entries: FtpEntry[] = [];
+	for (const line of text.split("\n")) {
+		const entry = parseLine(line.trim());
+		if (entry && entry.name != "." && entry.name != "..") entries.push(entry);
+	}
+	return entries;
+}
+
+function parseLine(line: string) {
+	const unix = UNIX_LINE.exec(line);
+	if (unix) return unixEntry(unix);
+	const dos = DOS_LINE.exec(line);
+	if (dos) return dosEntry(dos);
+	return null;
+}
+
+function unixEntry(match: RegExpExecArray) {
+	const kind = match[1];
+	const month = MONTHS.indexOf(match[3].toLowerCase());
+	const day = Number(match[4]);
+	const timeOrYear = match[5];
+	// A link's line is `name -> target`.
+	const name = kind == "l" ? match[6].split(" -> ")[0] : match[6];
+	const entry: FtpEntry = { name, size: Number(match[2]), isDirectory: kind == "d", modified: unixDate(month, day, timeOrYear) };
+	return entry;
+}
+
+/** `Oct  1 21:05` is this year's - last year's if that is still to come; `Oct  1  2023` is that day's. */
+function unixDate(month: number, day: number, timeOrYear: string) {
+	const colon = timeOrYear.indexOf(":");
+	if (colon < 0) return new Date(utc(Number(timeOrYear), month, day, 0, 0));
+
+	const hour = Number(timeOrYear.slice(0, colon));
+	const minute = Number(timeOrYear.slice(colon + 1));
+	const now = Date.now();
+	const year = new Date(now).getUTCFullYear();
+	const thisYear = utc(year, month, day, hour, minute);
+	// A day ahead allows for the server's time zone.
+	return new Date(thisYear > now + 86_400_000 ? utc(year - 1, month, day, hour, minute) : thisYear);
+}
+
+function dosEntry(match: RegExpExecArray) {
+	const shortYear = Number(match[3]);
+	const year = match[3].length == 4 ? shortYear : shortYear < 70 ? 2000 + shortYear : 1900 + shortYear;
+	const hour = Number(match[4]) % 12 + (match[6].toUpperCase() == "PM" ? 12 : 0);
+	const folder = match[7].toUpperCase() == "<DIR>";
+	const modified = new Date(utc(year, Number(match[1]) - 1, Number(match[2]), hour, Number(match[5])));
+	const entry: FtpEntry = { name: match[8], size: folder ? 0 : Number(match[7]), isDirectory: folder, modified };
+	return entry;
+}
+
+/** Milliseconds since 1970 of a UTC time, to the minute. */
+function utc(year: number, month: number, day: number, hour: number, minute: number) {
+	return Date.UTC(year, month, day, hour, minute, 0, 0);
+}