@filebox/ftp-server 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,2 @@
+# Changelog
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FileBox
+
+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,32 @@
+# @filebox/ftp-server
+
+FileBox 的 FTP 服务适配包，用来把 FileBox 运行时里的驱动暴露为 FTP 服务。
+
+## 安装
+
+```bash
+pnpm add @filebox/ftp-server
+```
+
+## 使用
+
+```ts
+import {
+  FileBoxFtpServer,
+  createFileBoxFtpSessionFactory,
+  createWorkspaceRuntime,
+} from "@filebox/ftp-server";
+
+const runtime = await createWorkspaceRuntime();
+
+const server = new FileBoxFtpServer({
+  url: "ftp://0.0.0.0:2121",
+  createSession: createFileBoxFtpSessionFactory(runtime),
+});
+
+await server.listen();
+```
+
+## License
+
+MIT

package/dist/adapters/filebox/index.d.ts

@@ -0,0 +1,2 @@
+export { createRuntime, type CreateRuntimeOptions, type TFileBoxFtpRuntime, } from "./runtime";
+export { createFileBoxFtpSessionFactory } from "./session";

package/dist/adapters/filebox/runtime.d.ts

@@ -0,0 +1,9 @@
+import type { FileBoxRuntime, WorkspaceRuntimeConfig } from "@filebox/runtime";
+export interface CreateRuntimeOptions {
+    runtime: FileBoxRuntime<WorkspaceRuntimeConfig>;
+    mountedDriveNames?: string[];
+}
+export type TFileBoxFtpRuntime = FileBoxRuntime<WorkspaceRuntimeConfig> & {
+    mountedDriveNames: string[];
+};
+export declare function createRuntime(options: CreateRuntimeOptions): TFileBoxFtpRuntime;

package/dist/adapters/filebox/session.d.ts

@@ -0,0 +1,3 @@
+import type { FileBoxFtpSessionFactory } from "../../server/types";
+import type { TFileBoxFtpRuntime } from "./runtime";
+export declare function createFileBoxFtpSessionFactory(runtime: TFileBoxFtpRuntime): FileBoxFtpSessionFactory;

package/dist/adapters/workspace/index.d.ts

@@ -0,0 +1,6 @@
+import { type TFileBoxFtpRuntime } from "../filebox/runtime";
+export interface CreateWorkspaceRuntimeOptions {
+    workspaceRoot?: string;
+    onlyDrive?: string | null;
+}
+export declare function createWorkspaceRuntime(options?: CreateWorkspaceRuntimeOptions): Promise<TFileBoxFtpRuntime>;

package/dist/filesystem/index.d.ts

@@ -0,0 +1,65 @@
+import { Readable, Writable } from "node:stream";
+import { FileSystem } from "ftp-srv";
+import type { TFileBoxFtpRuntime } from "../adapters/filebox/runtime";
+type FtpStatLike = {
+    name: string;
+    size: number;
+    atime: Date;
+    mtime: Date;
+    ctime: Date;
+    birthtime: Date;
+    isDirectory: () => boolean;
+    isFile: () => boolean;
+};
+declare class DeferredUploadWriteStream extends Writable {
+    private readonly volume;
+    private readonly relativePath;
+    private readonly tempFilePath;
+    private readonly runtime;
+    private localStream;
+    private commitPromise;
+    private tempFileRemoved;
+    constructor(volume: any, relativePath: string, tempFilePath: string, runtime: TFileBoxFtpRuntime);
+    _write(chunk: Buffer, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
+    private commitUploadedFile;
+    private cleanupTempFile;
+}
+export declare class FileBoxFtpFileSystem extends FileSystem {
+    private readonly runtime;
+    private cryptPromise?;
+    constructor(connection: unknown, runtime: TFileBoxFtpRuntime);
+    private resolveClientPath;
+    private getApp;
+    private getCrypt;
+    private getDisplayName;
+    private decorateRemoteItem;
+    private transformStoredName;
+    private splitMountedPath;
+    private getMountedVolume;
+    private findRemoteEntryByClientName;
+    private resolveExistingMountedPath;
+    private getRootEntry;
+    private createTempFilePath;
+    get(fileName: string): Promise<FtpStatLike>;
+    list(targetPath?: string): Promise<FtpStatLike[]>;
+    chdir(targetPath?: string): Promise<string>;
+    read(fileName: string, options?: {
+        start?: number;
+    }): Promise<{
+        stream: Readable;
+        clientPath: string;
+    }>;
+    write(fileName: string, options?: {
+        append?: boolean;
+        start?: number;
+    }): Promise<{
+        stream: DeferredUploadWriteStream;
+        clientPath: string;
+    }>;
+    delete(targetPath: string): Promise<any>;
+    mkdir(targetPath: string): Promise<any>;
+    rename(from: string, to: string): Promise<any>;
+}
+export {};

package/dist/filesystem/path.d.ts

@@ -0,0 +1 @@
+export declare function normalizeFtpClientPath(targetPath: string): string;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { FileBoxFtpServer } from "./server/index";
+export type { FileBoxFtpAuthenticate, FileBoxFtpLoginContext, FileBoxFtpServerOptions, FileBoxFtpServerSummary, FileBoxFtpSession, FileBoxFtpSessionFactory, } from "./server/types";
+export { createStaticFtpAuthenticator, normalizeServerCredentials, } from "./server/auth";
+export { FileBoxFtpFileSystem } from "./filesystem";
+export { createFileBoxFtpSessionFactory, createRuntime, type CreateRuntimeOptions, type TFileBoxFtpRuntime, } from "./adapters/filebox";
+export { createWorkspaceRuntime, type CreateWorkspaceRuntimeOptions, } from "./adapters/workspace";

package/dist/index.js

@@ -0,0 +1,930 @@
+// src/server/index.ts
+import { FtpSrv } from "ftp-srv";
+
+// src/server/auth.ts
+function normalizeServerCredentials(options) {
+  return {
+    username: options.username || "filebox",
+    password: options.password || "filebox",
+    anonymous: options.anonymous ?? false
+  };
+}
+function createStaticFtpAuthenticator(credentials) {
+  return ({ username, password }) => {
+    if (credentials.anonymous) {
+      return true;
+    }
+    return username === credentials.username && password === credentials.password;
+  };
+}
+
+// src/server/index.ts
+function normalizeServerOptions(options = {}) {
+  const credentials = normalizeServerCredentials(options);
+  return {
+    url: options.url || "ftp://0.0.0.0:2121",
+    username: credentials.username,
+    password: credentials.password,
+    anonymous: credentials.anonymous,
+    passiveUrl: options.passiveUrl ?? null,
+    passivePortMin: options.passivePortMin ?? 3e4,
+    passivePortMax: options.passivePortMax ?? 30999,
+    timeout: options.timeout ?? 0,
+    greeting: options.greeting ?? null,
+    mountedDriveNames: options.mountedDriveNames ?? [],
+    loginLabel: options.loginLabel ?? null,
+    authenticate: options.authenticate,
+    createSession: options.createSession
+  };
+}
+var FileBoxFtpServer = class {
+  options;
+  authenticate;
+  ftpServer = null;
+  constructor(options = {}) {
+    this.options = normalizeServerOptions(options);
+    if (typeof this.options.createSession !== "function") {
+      throw new Error("FileBoxFtpServer requires a createSession handler.");
+    }
+    this.authenticate = this.options.authenticate || createStaticFtpAuthenticator({
+      anonymous: this.options.anonymous,
+      username: this.options.username,
+      password: this.options.password
+    });
+  }
+  async init() {
+    if (this.ftpServer) {
+      return this;
+    }
+    this.ftpServer = new FtpSrv({
+      url: this.options.url,
+      anonymous: this.options.anonymous,
+      pasv_url: this.options.passiveUrl || void 0,
+      pasv_min: this.options.passivePortMin,
+      pasv_max: this.options.passivePortMax,
+      timeout: this.options.timeout,
+      greeting: this.options.greeting || void 0
+    });
+    this.ftpServer.on("login", ({ username, password }, resolve, reject) => {
+      void this.handleLogin({ username, password }, resolve, reject);
+    });
+    return this;
+  }
+  async handleLogin(credentials, resolve, reject) {
+    try {
+      const loginContext = {
+        username: credentials.username,
+        password: credentials.password,
+        anonymous: this.options.anonymous
+      };
+      const authenticated = await this.authenticate(loginContext);
+      if (!authenticated) {
+        reject(new Error("Invalid username or password"));
+        return;
+      }
+      const createSession = this.options.createSession;
+      if (!createSession) {
+        reject(new Error("FTP session factory is not configured."));
+        return;
+      }
+      const session = await createSession(loginContext);
+      if (!session?.fs) {
+        reject(new Error("FTP session must provide a file system instance."));
+        return;
+      }
+      resolve({
+        root: session.root || "/",
+        fs: session.fs
+      });
+    } catch (error) {
+      reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  async listen() {
+    await this.init();
+    await this.ftpServer.listen();
+    return this;
+  }
+  async close() {
+    if (this.ftpServer) {
+      const server = this.ftpServer;
+      this.ftpServer = null;
+      await server.close();
+    }
+  }
+  getFtpServer() {
+    if (!this.ftpServer) {
+      throw new Error("FTP server is not initialized. Call init() first.");
+    }
+    return this.ftpServer;
+  }
+  getSummary() {
+    const loginLabel = this.options.loginLabel || (this.options.anonymous ? "anonymous" : this.options.username);
+    return {
+      url: this.options.url,
+      mountedDriveNames: this.options.mountedDriveNames,
+      passiveUrl: this.options.passiveUrl,
+      passivePortMin: this.options.passivePortMin,
+      passivePortMax: this.options.passivePortMax,
+      anonymous: this.options.anonymous,
+      username: this.options.username,
+      loginLabel,
+      timeout: this.options.timeout
+    };
+  }
+};
+
+// src/filesystem/index.ts
+import fs from "node:fs";
+import path2 from "node:path";
+import crypto from "node:crypto";
+import { Readable, Transform, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { FileSystem } from "ftp-srv";
+import {
+  addContentEncryptionSuffix,
+  calculateEncryptedBytes,
+  isContentEncryptedName,
+  parseEncryptionQueryParams,
+  resolveEncryptionProfile,
+  createFileEncryptor
+} from "@filebox/runtime";
+
+// src/filesystem/path.ts
+import path from "node:path";
+function normalizeFtpClientPath(targetPath) {
+  const normalizedInput = (targetPath || "/").trim();
+  if (normalizedInput === "" || normalizedInput === "." || normalizedInput === "./") {
+    return "/";
+  }
+  const normalized = path.posix.normalize(normalizedInput);
+  if (normalized === "." || normalized === "/.") {
+    return "/";
+  }
+  return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}
+
+// src/filesystem/index.ts
+function asDate(input) {
+  const date = input ? new Date(String(input)) : /* @__PURE__ */ new Date(0);
+  return Number.isNaN(date.getTime()) ? /* @__PURE__ */ new Date(0) : date;
+}
+function toFileSystemError(error) {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "File system error";
+  return new Error(message);
+}
+function toFileEntry(stat) {
+  const isDirectory = stat?.type === "folder" || stat?.directory === true;
+  const byteSize = typeof stat?.byte === "number" ? stat.byte : typeof stat?.size === "number" ? stat.size : 0;
+  return {
+    name: stat?.name || "",
+    size: Number.isFinite(byteSize) ? byteSize : 0,
+    atime: asDate(stat?.atime),
+    mtime: asDate(stat?.mtime),
+    ctime: asDate(stat?.ctime),
+    birthtime: asDate(stat?.ctime),
+    isDirectory: () => isDirectory,
+    isFile: () => !isDirectory
+  };
+}
+function createUploadFileMetadata(tempFilePath, fileName, workspaceRoot) {
+  const stats = fs.statSync(tempFilePath);
+  const parsedPath = path2.parse(tempFilePath);
+  const relativeBase = workspaceRoot || path2.dirname(tempFilePath);
+  return {
+    path: parsedPath.dir,
+    name: fileName,
+    baseName: path2.parse(fileName).name,
+    ext: path2.parse(fileName).ext,
+    size: stats.size,
+    absolutePath: tempFilePath,
+    relativePath: path2.relative(relativeBase, tempFilePath),
+    mimeType: "",
+    lastModified: stats.mtime,
+    parentPath: parsedPath.dir,
+    isFile: true,
+    isDirectory: false,
+    md5: async () => calculateMd5(tempFilePath)
+  };
+}
+function calculateMd5(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash("md5");
+    const input = fs.createReadStream(filePath);
+    input.on("readable", () => {
+      const data = input.read();
+      if (data) {
+        hash.update(data);
+        return;
+      }
+      resolve(hash.digest("hex"));
+    });
+    input.on("error", reject);
+  });
+}
+function resolveReadableDownloadPath(rawUrl) {
+  if (rawUrl.startsWith("file://")) {
+    return fileURLToPath(rawUrl);
+  }
+  if (fs.existsSync(rawUrl)) {
+    return rawUrl;
+  }
+  return null;
+}
+function parseRemoteResponseTotalSize(response, fallback) {
+  const contentRange = response.headers.get("content-range");
+  if (contentRange) {
+    const match = contentRange.match(/\/(\d+)$/);
+    if (match) {
+      return Number.parseInt(match[1], 10);
+    }
+  }
+  const contentLength = response.headers.get("content-length");
+  if (contentLength) {
+    const size = Number.parseInt(contentLength, 10);
+    if (Number.isFinite(size)) {
+      return size;
+    }
+  }
+  return typeof fallback === "number" && Number.isFinite(fallback) ? fallback : 0;
+}
+function parseDownloadEncryptionProfile(rawUrl) {
+  try {
+    return parseEncryptionQueryParams(new URL(rawUrl));
+  } catch {
+    return null;
+  }
+}
+function resolveFtpClientReference(currentDirectory, targetPath = ".") {
+  const resolvedPath = targetPath.replace(/\\/g, "/");
+  const clientPath = path2.posix.isAbsolute(resolvedPath) ? path2.posix.normalize(resolvedPath) : path2.posix.join("/", currentDirectory, resolvedPath);
+  return normalizeFtpClientPath(clientPath);
+}
+function resolveFtpDownloadDecryption(input) {
+  const queryProfile = parseDownloadEncryptionProfile(
+    input.downloadInfo.url || ""
+  );
+  const encryptedByName = isContentEncryptedName(
+    path2.posix.basename(input.clientPath)
+  );
+  if (!encryptedByName && !queryProfile) {
+    return null;
+  }
+  const profile = resolveEncryptionProfile({
+    password: input.config.encryption?.password,
+    salt: input.config.encryption?.salt,
+    algorithm: queryProfile?.algorithm || input.config.encryption?.advanced?.algorithm,
+    partialEncryption: queryProfile?.partialEncryption || input.config.encryption?.advanced?.partialEncryption
+  });
+  if (!profile.password) {
+    throw new Error(`Missing encryption password for ${input.clientPath}`);
+  }
+  return profile;
+}
+var DownloadDecryptTransform = class extends Transform {
+  constructor(encryptor, startOffset, encryptedBytes) {
+    super();
+    this.encryptor = encryptor;
+    this.encryptedBytes = encryptedBytes;
+    this.offset = startOffset;
+  }
+  offset;
+  async _transform(chunk, _encoding, callback) {
+    try {
+      const chunkStart = this.offset;
+      const chunkEnd = chunkStart + chunk.length;
+      if (chunkStart >= this.encryptedBytes) {
+        this.offset += chunk.length;
+        callback(null, chunk);
+        return;
+      }
+      if (chunkEnd <= this.encryptedBytes) {
+        const decrypted2 = await this.encryptor.decryptChunk(
+          new Uint8Array(chunk),
+          this.offset
+        );
+        this.offset += chunk.length;
+        callback(null, Buffer.from(decrypted2));
+        return;
+      }
+      const encryptedPartLength = this.encryptedBytes - chunkStart;
+      const encryptedPart = chunk.slice(0, encryptedPartLength);
+      const plainPart = chunk.slice(encryptedPartLength);
+      const decrypted = await this.encryptor.decryptChunk(
+        new Uint8Array(encryptedPart),
+        this.offset
+      );
+      this.offset += chunk.length;
+      callback(null, Buffer.concat([Buffer.from(decrypted), plainPart]));
+    } catch (error) {
+      callback(toFileSystemError(error));
+    }
+  }
+};
+function isUploadHandle(value) {
+  return Boolean(
+    value && typeof value === "object" && "upload" in value && typeof value.upload === "function"
+  );
+}
+async function syncUploadedFileCache(volume, parentPath, fileName, uploadResult) {
+  const cache = volume?._fs?.cache;
+  const fsAdapter = volume?._fs;
+  if (!cache || !fsAdapter) {
+    return;
+  }
+  const targetPath = normalizeFtpClientPath(
+    path2.posix.join(parentPath, fileName)
+  );
+  try {
+    if (uploadResult) {
+      await cache.handleOperation({
+        type: "create",
+        path: targetPath,
+        parentPath,
+        newItem: uploadResult,
+        fs: fsAdapter
+      });
+      return;
+    }
+  } catch {
+  }
+  if (typeof cache.markForRefresh === "function") {
+    await cache.markForRefresh(parentPath);
+    await cache.markForRefresh(targetPath);
+    return;
+  }
+  if (typeof volume.refresh === "function") {
+    await volume.refresh(parentPath);
+    await volume.refresh(targetPath);
+  }
+}
+var DeferredUploadWriteStream = class extends Writable {
+  constructor(volume, relativePath, tempFilePath, runtime) {
+    super();
+    this.volume = volume;
+    this.relativePath = relativePath;
+    this.tempFilePath = tempFilePath;
+    this.runtime = runtime;
+    this.localStream = fs.createWriteStream(this.tempFilePath, { flags: "w" });
+  }
+  localStream;
+  commitPromise = null;
+  tempFileRemoved = false;
+  _write(chunk, encoding, callback) {
+    this.localStream.write(chunk, encoding, callback);
+  }
+  _final(callback) {
+    this.localStream.end(() => {
+      this.commitPromise = this.commitUploadedFile();
+      this.commitPromise.then(() => callback()).catch((error) => callback(toFileSystemError(error))).finally(() => {
+        this.cleanupTempFile();
+      });
+    });
+  }
+  _destroy(error, callback) {
+    if (this.commitPromise) {
+      callback(error);
+      return;
+    }
+    if (!this.localStream.destroyed) {
+      this.localStream.destroy();
+    }
+    this.cleanupTempFile();
+    callback(error);
+  }
+  async commitUploadedFile() {
+    const parentPath = path2.posix.dirname(this.relativePath);
+    let fileName = path2.posix.basename(this.relativePath);
+    let uploadFilePath = this.tempFilePath;
+    if (this.runtime.crypto.isContentEncryptionEnabled()) {
+      const contentProfile = this.runtime.crypto.resolveProfile();
+      if (!contentProfile.password) {
+        throw new Error(`Missing encryption password for ${this.relativePath}`);
+      }
+      const encryptedTempFilePath = `${this.tempFilePath}.enc`;
+      const encryptor = await this.runtime.crypto.createFileEncryptor();
+      await encryptLocalFileWithEncryptor(
+        this.tempFilePath,
+        encryptedTempFilePath,
+        encryptor
+      );
+      uploadFilePath = encryptedTempFilePath;
+      fileName = addContentEncryptionSuffix(fileName);
+    }
+    const fileMetadata = createUploadFileMetadata(
+      uploadFilePath,
+      fileName,
+      this.runtime.workspaceRoot
+    );
+    const uploadController = typeof this.volume?.createUpload === "function" ? await this.volume.createUpload(parentPath, fileMetadata) : await this.volume.upload(parentPath, fileMetadata);
+    const uploadResult = isUploadHandle(uploadController) ? await uploadController.upload() : uploadController;
+    await syncUploadedFileCache(
+      this.volume,
+      parentPath,
+      fileName,
+      uploadResult
+    );
+    if (uploadFilePath !== this.tempFilePath && fs.existsSync(uploadFilePath)) {
+      fs.unlinkSync(uploadFilePath);
+    }
+  }
+  cleanupTempFile() {
+    if (this.tempFileRemoved) {
+      return;
+    }
+    this.tempFileRemoved = true;
+    try {
+      if (fs.existsSync(this.tempFilePath)) {
+        fs.unlinkSync(this.tempFilePath);
+      }
+    } catch {
+    }
+  }
+};
+async function encryptLocalFileWithEncryptor(inputPath, outputPath, encryptor) {
+  const chunkSize = 1024 * 1024;
+  const fileSize = fs.statSync(inputPath).size;
+  const inputFd = fs.openSync(inputPath, "r");
+  const outputFd = fs.openSync(outputPath, "w");
+  try {
+    let offset = 0;
+    const buffer = Buffer.allocUnsafe(chunkSize);
+    while (offset < fileSize) {
+      const bytesToRead = Math.min(chunkSize, fileSize - offset);
+      const bytesRead = fs.readSync(inputFd, buffer, 0, bytesToRead, offset);
+      if (bytesRead === 0) {
+        break;
+      }
+      const chunk = new Uint8Array(buffer.buffer, buffer.byteOffset, bytesRead);
+      const encryptedChunk = await encryptor.encryptChunk(chunk, offset);
+      fs.writeSync(outputFd, Buffer.from(encryptedChunk));
+      offset += bytesRead;
+    }
+  } finally {
+    fs.closeSync(inputFd);
+    fs.closeSync(outputFd);
+  }
+}
+var FileBoxFtpFileSystem = class extends FileSystem {
+  constructor(connection, runtime) {
+    super(connection, { root: "/", cwd: "/" });
+    this.runtime = runtime;
+  }
+  cryptPromise;
+  resolveClientPath(targetPath = ".") {
+    return resolveFtpClientReference(this.currentDirectory(), targetPath);
+  }
+  getApp() {
+    return this.runtime.app;
+  }
+  getCrypt() {
+    if (this.cryptPromise) {
+      return this.cryptPromise;
+    }
+    this.cryptPromise = (async () => {
+      if (!this.runtime.config.encryption?.password) {
+        return null;
+      }
+      return this.runtime.crypto.createFsCrypt();
+    })();
+    return this.cryptPromise;
+  }
+  async getDisplayName(rawName) {
+    const crypt = await this.getCrypt();
+    if (!crypt || !rawName) {
+      return rawName;
+    }
+    if (!await crypt.isEncrypted(rawName)) {
+      return rawName;
+    }
+    const decryptedName = await crypt.decryptFilename(rawName);
+    return decryptedName || rawName;
+  }
+  async decorateRemoteItem(item) {
+    const displayName = await this.getDisplayName(item?.name || "");
+    if (!displayName || displayName === item?.name) {
+      return item;
+    }
+    return {
+      ...item,
+      name: displayName,
+      original_name: displayName
+    };
+  }
+  async transformStoredName(name) {
+    if (!this.runtime.crypto.isFilenameEncryptionEnabled()) {
+      return name;
+    }
+    const crypt = await this.getCrypt();
+    if (!crypt) {
+      return name;
+    }
+    return crypt.encryptFilename(name);
+  }
+  splitMountedPath(clientPath) {
+    const normalizedPath = normalizeFtpClientPath(clientPath);
+    const segments = normalizedPath.split("/").filter(Boolean);
+    const mountName = segments[0] || "";
+    const relativePath = segments.length > 1 ? `/${segments.slice(1).join("/")}` : "/";
+    return {
+      normalizedPath,
+      mountName,
+      relativePath: normalizeFtpClientPath(relativePath)
+    };
+  }
+  getMountedVolume(clientPath) {
+    const { normalizedPath, mountName, relativePath } = this.splitMountedPath(clientPath);
+    if (normalizedPath === "/") {
+      return {
+        mountName: "",
+        relativePath: "/",
+        volume: null
+      };
+    }
+    const app = this.getApp();
+    const volume = app.getVolume?.(mountName) || app.getVolume?.(`/${mountName}`) || app.volumeMap?.get?.(mountName) || app.volumeMap?.get?.(`/${mountName}`);
+    if (!volume) {
+      throw new Error(`Drive "${mountName}" is not mounted`);
+    }
+    return {
+      mountName,
+      relativePath,
+      volume
+    };
+  }
+  async findRemoteEntryByClientName(items, clientName) {
+    for (const item of items) {
+      if (item?.name === clientName) {
+        return item;
+      }
+      if (await this.getDisplayName(item?.name || "") === clientName) {
+        return item;
+      }
+    }
+    return null;
+  }
+  async resolveExistingMountedPath(clientPath) {
+    const mounted = this.getMountedVolume(clientPath);
+    if (!mounted.volume || mounted.relativePath === "/") {
+      return mounted;
+    }
+    const segments = mounted.relativePath.split("/").filter(Boolean);
+    let resolvedPath = "/";
+    for (const segment of segments) {
+      const listing = await mounted.volume.list(resolvedPath);
+      const items = Array.isArray(listing?.data) ? listing.data : [];
+      const matchedEntry = await this.findRemoteEntryByClientName(
+        items,
+        segment
+      );
+      if (!matchedEntry?.name) {
+        resolvedPath = normalizeFtpClientPath(
+          path2.posix.join(resolvedPath, segment)
+        );
+        continue;
+      }
+      resolvedPath = normalizeFtpClientPath(
+        path2.posix.join(resolvedPath, matchedEntry.name)
+      );
+    }
+    return {
+      ...mounted,
+      relativePath: resolvedPath
+    };
+  }
+  async getRootEntry(mountName) {
+    const result = await this.getApp().list("/");
+    const items = Array.isArray(result) ? result : result?.data || [];
+    const entry = items.find((item) => item?.name === mountName);
+    if (!entry) {
+      throw new Error(`Drive "${mountName}" is not mounted`);
+    }
+    return entry;
+  }
+  createTempFilePath() {
+    const tempRoot = this.runtime.config.tempPath;
+    return path2.join(
+      tempRoot,
+      `ftp-upload-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`
+    );
+  }
+  async get(fileName) {
+    try {
+      const clientPath = this.resolveClientPath(fileName);
+      if (clientPath === "/") {
+        return toFileEntry(await this.getApp().stat("/"));
+      }
+      const { mountName, relativePath, volume } = await this.resolveExistingMountedPath(clientPath);
+      const stat = relativePath === "/" ? await this.getRootEntry(mountName) : await volume.stat(relativePath);
+      return toFileEntry(await this.decorateRemoteItem(stat));
+    } catch (error) {
+      throw toFileSystemError(error);
+    }
+  }
+  async list(targetPath = ".") {
+    try {
+      const clientPath = this.resolveClientPath(targetPath);
+      const mounted = clientPath === "/" ? null : await this.resolveExistingMountedPath(clientPath);
+      const result = mounted ? await mounted.volume.list(mounted.relativePath) : await this.getApp().list("/");
+      const items = Array.isArray(result) ? result : result?.data || [];
+      const decoratedItems = await Promise.all(
+        items.map((item) => this.decorateRemoteItem(item))
+      );
+      return decoratedItems.map((item) => toFileEntry(item));
+    } catch (error) {
+      throw toFileSystemError(error);
+    }
+  }
+  async chdir(targetPath = ".") {
+    try {
+      const clientPath = this.resolveClientPath(targetPath);
+      const mounted = clientPath === "/" ? null : await this.resolveExistingMountedPath(clientPath);
+      const stat = clientPath === "/" ? await this.getApp().stat("/") : mounted.relativePath === "/" ? await this.getRootEntry(mounted.mountName) : await mounted.volume.stat(mounted.relativePath);
+      if (stat?.type !== "folder" && stat?.directory !== true) {
+        throw new Error("Not a valid directory");
+      }
+      this.cwd = clientPath;
+      return this.currentDirectory();
+    } catch (error) {
+      throw toFileSystemError(error);
+    }
+  }
+  async read(fileName, options = {}) {
+    try {
+      const clientPath = this.resolveClientPath(fileName);
+      const { relativePath, volume } = await this.resolveExistingMountedPath(clientPath);
+      const stat = await volume.stat(relativePath);
+      if (stat?.type === "folder" || stat?.directory === true) {
+        throw new Error("Cannot read a directory");
+      }
+      const [downloadInfo] = await volume.download(relativePath);
+      if (!downloadInfo?.url) {
+        throw new Error("Download URL is not available");
+      }
+      const decryptProfile = resolveFtpDownloadDecryption({
+        clientPath,
+        downloadInfo,
+        config: this.runtime.config
+      });
+      const startOffset = typeof options.start === "number" ? options.start : 0;
+      const localDownloadPath = resolveReadableDownloadPath(downloadInfo.url);
+      if (localDownloadPath) {
+        const sourceStream2 = fs.createReadStream(localDownloadPath, {
+          start: typeof options.start === "number" ? options.start : void 0
+        });
+        if (!decryptProfile) {
+          return {
+            stream: sourceStream2,
+            clientPath
+          };
+        }
+        const totalSize2 = fs.statSync(localDownloadPath).size;
+        const encryptedBytes2 = calculateEncryptedBytes(
+          totalSize2,
+          decryptProfile.partialEncryption
+        );
+        const encryptor2 = await createFileEncryptor(decryptProfile);
+        return {
+          stream: sourceStream2.pipe(
+            new DownloadDecryptTransform(
+              encryptor2,
+              startOffset,
+              encryptedBytes2
+            )
+          ),
+          clientPath
+        };
+      }
+      const headers = { ...downloadInfo.headers || {} };
+      if (typeof options.start === "number" && options.start > 0 && !("Range" in headers) && !("range" in headers)) {
+        headers.Range = `bytes=${options.start}-`;
+      }
+      const response = await fetch(downloadInfo.url, { headers });
+      if (!response.ok && response.status !== 206) {
+        throw new Error(
+          `Failed to fetch remote file: ${response.status} ${response.statusText}`
+        );
+      }
+      if (!response.body) {
+        throw new Error("Remote response does not contain a readable body");
+      }
+      const totalSize = parseRemoteResponseTotalSize(response, stat?.byte);
+      const sourceStream = Readable.fromWeb(response.body);
+      if (!decryptProfile) {
+        return {
+          stream: sourceStream,
+          clientPath
+        };
+      }
+      const encryptedBytes = calculateEncryptedBytes(
+        totalSize,
+        decryptProfile.partialEncryption
+      );
+      const encryptor = await createFileEncryptor(decryptProfile);
+      return {
+        stream: sourceStream.pipe(
+          new DownloadDecryptTransform(encryptor, startOffset, encryptedBytes)
+        ),
+        clientPath
+      };
+    } catch (error) {
+      throw toFileSystemError(error);
+    }
+  }
+  async write(fileName, options = {}) {
+    const { append = false, start } = options;
+    if (append || typeof start === "number") {
+      throw new Error("Append and ranged uploads are not supported");
+    }
+    const clientPath = this.resolveClientPath(fileName);
+    const mounted = this.getMountedVolume(clientPath);
+    const parentClientPath = normalizeFtpClientPath(
+      path2.posix.dirname(clientPath)
+    );
+    const parentMounted = parentClientPath === "/" ? mounted : await this.resolveExistingMountedPath(parentClientPath);
+    const relativePath = normalizeFtpClientPath(
+      path2.posix.join(
+        parentMounted.relativePath,
+        await this.transformStoredName(
+          path2.posix.basename(mounted.relativePath)
+        )
+      )
+    );
+    const { volume } = mounted;
+    const stream = new DeferredUploadWriteStream(
+      volume,
+      relativePath,
+      this.createTempFilePath(),
+      this.runtime
+    );
+    return {
+      stream,
+      clientPath
+    };
+  }
+  async delete(targetPath) {
+    try {
+      const clientPath = this.resolveClientPath(targetPath);
+      if (clientPath === "/") {
+        throw new Error("Cannot delete root directory");
+      }
+      const { relativePath, volume } = await this.resolveExistingMountedPath(clientPath);
+      return await volume.remove(relativePath);
+    } catch (error) {
+      throw toFileSystemError(error);
+    }
+  }
+  async mkdir(targetPath) {
+    try {
+      const clientPath = this.resolveClientPath(targetPath);
+      const mounted = this.getMountedVolume(clientPath);
+      const parentClientPath = normalizeFtpClientPath(
+        path2.posix.dirname(clientPath)
+      );
+      const parentMounted = parentClientPath === "/" ? mounted : await this.resolveExistingMountedPath(parentClientPath);
+      const relativePath = normalizeFtpClientPath(
+        path2.posix.join(
+          parentMounted.relativePath,
+          await this.transformStoredName(
+            path2.posix.basename(mounted.relativePath)
+          )
+        )
+      );
+      const { volume } = mounted;
+      return await volume.mkdir(relativePath, {});
+    } catch (error) {
+      throw toFileSystemError(error);
+    }
+  }
+  async rename(from, to) {
+    try {
+      const fromPath = this.resolveClientPath(from);
+      const toPath = this.resolveClientPath(to);
+      const fromMounted = await this.resolveExistingMountedPath(fromPath);
+      const toMounted = this.getMountedVolume(toPath);
+      if (fromMounted.mountName !== toMounted.mountName) {
+        throw new Error("Cross-drive rename is not supported");
+      }
+      const fromDir = path2.posix.dirname(fromMounted.relativePath);
+      const toDirClientPath = normalizeFtpClientPath(
+        path2.posix.dirname(toPath)
+      );
+      const resolvedToParent = toDirClientPath === "/" ? toMounted : await this.resolveExistingMountedPath(toDirClientPath);
+      const toDir = resolvedToParent.relativePath;
+      const targetRelativePath = normalizeFtpClientPath(
+        path2.posix.join(
+          resolvedToParent.relativePath,
+          await this.transformStoredName(
+            path2.posix.basename(toMounted.relativePath)
+          )
+        )
+      );
+      if (fromDir === toDir) {
+        return await fromMounted.volume.rename(
+          fromMounted.relativePath,
+          path2.posix.basename(targetRelativePath)
+        );
+      }
+      if (typeof fromMounted.volume.move !== "function") {
+        throw new Error("Move is not supported by this drive");
+      }
+      return await fromMounted.volume.move(
+        fromMounted.relativePath,
+        targetRelativePath
+      );
+    } catch (error) {
+      throw toFileSystemError(error);
+    }
+  }
+};
+
+// src/adapters/filebox/runtime.ts
+function resolveMountedDriveNames(app, mountedDriveNames) {
+  if (mountedDriveNames && mountedDriveNames.length > 0) {
+    return mountedDriveNames;
+  }
+  const volumeMap = app?.volumeMap;
+  if (!(volumeMap instanceof Map)) {
+    return [];
+  }
+  return Array.from(volumeMap.values()).map((volume) => volume?._options?.name || volume?.name || "").map((name) => String(name || "").replace(/^\/+/, "")).filter(Boolean);
+}
+function createRuntime(options) {
+  if (!options.runtime) {
+    throw new Error("createRuntime requires a runtime instance.");
+  }
+  return Object.assign(options.runtime, {
+    mountedDriveNames: resolveMountedDriveNames(
+      options.runtime.app,
+      options.mountedDriveNames
+    )
+  });
+}
+
+// src/adapters/filebox/session.ts
+function createFileBoxFtpSessionFactory(runtime) {
+  return async () => ({
+    root: "/",
+    fs: new FileBoxFtpFileSystem(void 0, runtime)
+  });
+}
+
+// src/adapters/workspace/index.ts
+import { FileBoxRuntime, loadWorkspaceConfigInput } from "@filebox/runtime";
+async function mountEnabledDrives(runtime, options = {}) {
+  const onlyDrive = options.onlyDrive?.trim();
+  const drives = await runtime.drives.list();
+  const mountedNames = [];
+  for (const drive of drives) {
+    if (!drive.enabled) {
+      continue;
+    }
+    if (onlyDrive && drive.name !== onlyDrive) {
+      continue;
+    }
+    if (!drive.supported) {
+      console.warn(
+        `[ftp-server] Skip drive "${drive.name}": provider "${drive.provider}" is not loaded.`
+      );
+      continue;
+    }
+    if (!drive.ready) {
+      console.warn(
+        `[ftp-server] Skip drive "${drive.name}": ${drive.issue || "configuration is incomplete."}`
+      );
+      continue;
+    }
+    try {
+      await runtime.app.mount(drive);
+      mountedNames.push(drive.name);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(
+        `[ftp-server] Failed to mount drive "${drive.name}": ${message}`
+      );
+    }
+  }
+  return mountedNames;
+}
+async function createWorkspaceRuntime(options = {}) {
+  const { configPath, config } = loadWorkspaceConfigInput({
+    workspaceRoot: options.workspaceRoot || null
+  });
+  const runtime = await FileBoxRuntime.create({
+    configPath,
+    config
+  });
+  const mountedDriveNames = await mountEnabledDrives(runtime, options);
+  return Object.assign(runtime, {
+    mountedDriveNames
+  });
+}
+export {
+  FileBoxFtpFileSystem,
+  FileBoxFtpServer,
+  createFileBoxFtpSessionFactory,
+  createRuntime,
+  createStaticFtpAuthenticator,
+  createWorkspaceRuntime,
+  normalizeServerCredentials
+};

package/dist/server/auth.d.ts

@@ -0,0 +1,8 @@
+import type { FileBoxFtpAuthenticate, FileBoxFtpServerOptions } from "./types";
+export interface FileBoxFtpStaticCredentials {
+    username: string;
+    password: string;
+    anonymous: boolean;
+}
+export declare function normalizeServerCredentials(options: Pick<FileBoxFtpServerOptions, "username" | "password" | "anonymous">): FileBoxFtpStaticCredentials;
+export declare function createStaticFtpAuthenticator(credentials: FileBoxFtpStaticCredentials): FileBoxFtpAuthenticate;

package/dist/server/index.d.ts

@@ -0,0 +1,14 @@
+import { FtpSrv } from "ftp-srv";
+import type { FileBoxFtpServerOptions, FileBoxFtpServerSummary } from "./types";
+export declare class FileBoxFtpServer {
+    private readonly options;
+    private readonly authenticate;
+    private ftpServer;
+    constructor(options?: FileBoxFtpServerOptions);
+    init(): Promise<this>;
+    private handleLogin;
+    listen(): Promise<this>;
+    close(): Promise<void>;
+    getFtpServer(): FtpSrv;
+    getSummary(): FileBoxFtpServerSummary;
+}

package/dist/server/types.d.ts

@@ -0,0 +1,38 @@
+import type { FileSystem } from "ftp-srv";
+export interface FileBoxFtpLoginContext {
+    username?: string;
+    password?: string;
+    anonymous: boolean;
+}
+export interface FileBoxFtpSession {
+    root: string;
+    fs: FileSystem;
+}
+export type FileBoxFtpAuthenticate = (context: FileBoxFtpLoginContext) => boolean | Promise<boolean>;
+export type FileBoxFtpSessionFactory = (context: FileBoxFtpLoginContext) => FileBoxFtpSession | Promise<FileBoxFtpSession>;
+export interface FileBoxFtpServerOptions {
+    url?: string;
+    username?: string;
+    password?: string;
+    anonymous?: boolean;
+    passiveUrl?: string | null;
+    passivePortMin?: number;
+    passivePortMax?: number;
+    timeout?: number;
+    greeting?: string[] | null;
+    mountedDriveNames?: string[];
+    loginLabel?: string | null;
+    authenticate?: FileBoxFtpAuthenticate;
+    createSession?: FileBoxFtpSessionFactory;
+}
+export interface FileBoxFtpServerSummary {
+    url: string;
+    mountedDriveNames: string[];
+    passiveUrl: string | null;
+    passivePortMin: number;
+    passivePortMax: number;
+    anonymous: boolean;
+    username: string;
+    loginLabel: string;
+    timeout: number;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@filebox/ftp-server",
+  "version": "1.0.0",
+  "description": "FTP server library for FileBox.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "filebox",
+    "ftp",
+    "ftp-server"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --packages=external --outfile=dist/index.js && tsc -p tsconfig.json --emitDeclarationOnly",
+    "prepack": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --packages=external --outfile=dist/index.js && tsc -p tsconfig.json --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@filebox/runtime": "^1.0.0",
+    "ftp-srv": "^4.6.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.13",
+    "esbuild": "^0.24.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.5.4"
+  }
+}