Fileport

Fileport is a clean-room Agent Artifact Gateway backed by the official Dufs filesystem engine.

It turns a local file or directory into an opaque capability URL while keeping Dufs workers on Unix sockets and enforcing the share boundary again at the Gateway.

Phase 1 status

Implemented:

• official Dufs 0.46.0 pin + compatibility contract;
• persistent capability shares;
• read-only Unix Socket workers with root reuse and crash restart;
• reverse proxy with GET/HEAD/Range;
• traversal, encoded-path and symlink-escape protection;
• CLI and browser preview shell;
• explicit RO/RW shares, expiry and strict existing-file-only atomic saves;
• in-browser archive browsing and bounded entry preview for ZIP and compressed tar files.

See current architecture, Dufs compatibility, and migration plan, and network/CLI contract.

Install

npm install --global fileport-gateway
fileport share /absolute/path/to/report.md --readonly

The npm package includes the checksum-verified official Dufs 0.46.0 Linux x86_64 binary. Source development uses npm ci && npm run vendor:dufs && npm run build.

Run

# Direct LAN advertisement (default mode):
export FILEPORT_PUBLIC_BASE_URL="http://<devbox-ip>:7892"
fileport serve

In another shell:

fileport share /absolute/path/to/report.md
fileport ls
fileport revoke <share-id>

The Fileport origin listener provides HTTP only. The listener defaults to 0.0.0.0:7892; generated URLs default to the default-route LAN IPv4, not 127.0.0.1.

Direct mode (the default) requires a configured hostname to resolve entirely to local, listener-covered addresses. For a reverse proxy or tunnel that terminates public HTTPS and forwards to the local HTTP listener, use proxy mode:

fileport config set --host 127.0.0.1 \
  --public-url https://files.example.com \
  --public-mode proxy
fileport stop                 # if a daemon is already running
fileport doctor --json        # starts are explicit; doctor validates configuration
fileport share ./report.md --readonly

Proxy mode treats public.url as the externally advertised URL. DNS is reported for diagnostics but is not required to resolve to a local interface, and the public port does not need to equal the origin listener port. Fileport does not configure or verify the reverse proxy itself; verify the resulting capability URL end to end.

Archive browsing

The preview shell recognizes these formats by filename extension:

• ZIP: .zip
• tar: .tar
• gzip-compressed tar: .tar.gz, .tgz
• bzip2-compressed tar: .tar.bz2, .tbz, .tbz2
• xz-compressed tar: .tar.xz, .txz

Opening one of these files shows a sorted archive manifest with entry paths, types, uncompressed sizes and ZIP encryption status. Entries marked previewable—supported, unencrypted regular files of at most 10 MiB—can be opened with magic-validated image, PDF or media previews, sanitized Markdown/source/text views, and bounded binary-entry download behavior; a selected binary entry can be downloaded from that view. The original archive remains available through Download. Archive entries are read-only even when the enclosing share is RW.

Fileport streams archive parsing and decompression and never extracts archive contents to disk. A selected entry is buffered in memory only after its size has passed the preview checks. Limits are a 512 MiB archive input file, 10,000 entries per archive, 4 KiB per entry path, 4 MiB of aggregate manifest path text, 256 MiB of expanded data per tar scan, and 10 MiB per entry preview. Archive work runs in memory-limited worker threads with bounded global/per-archive concurrency and a 15-second wall-clock timeout. Tar archives are rescanned when an entry is opened; the limit applies to every such scan.

Unsafe archive paths are omitted from the manifest and counted. Leading ./ prefixes and trailing directory slashes are normalized; after that, absolute paths, drive-prefixed paths, backslashes, NULs, empty components, and . or .. components are unsafe. Symlinks, hard links and other non-regular entries may be listed but are never followed or previewed. Encrypted ZIP entries and regular files over the preview limit are listed as non-previewable; download the original archive to handle them with a trusted local tool.

fileport --help
fileport share --help
``` Agent control is available only through `$FILEPORT_STATE_DIR/control.sock` (0600).

## Verify

```bash
npm run typecheck
FILEPORT_TEST_DUFS=vendor/dufs npm test
FILEPORT_DUFS_BIN=vendor/dufs node scripts/dufs-compatibility.mjs

Security boundary

Dufs always remains read-only and never receives network exposure or write flags. RO is the default. An explicit RW share can modify only an existing allowlisted text file through Fileport's versioned, atomic Save API. Fileport rejects Home/filesystem-root/common credential targets; capability requests are canonicalized and checked against the exact share scope before proxying.