bbs.profullstack/agentbbs
1
0
Fork 0
mirror of https://github.com/profullstack/agentbbs.git synced 2026-08-13 14:27:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3
agentbbs/docs/files.md
Anthony Ettinger 6dc94bd784 feat(files): SFTP member storage — private workspaces + shared public area + mgmt TUI 
Implements M4 (Files). A fully virtual Go SFTP server (pkg/sftp + crypto/ssh,
no OS users) wired as an "sftp" subsystem on the existing :22 wish listener, so
members reach their files with their login key:

    sftp files@bbs.profullstack.com     # scp/rsync ride the same endpoint

Identity is the SSH key (the username is conventional/ignored). Two areas per
session: a private, quota-limited /me workspace and a single shared public file
area /public (old-school BBS file area; world-read, members-only write by
default, operator-moderated). This reverses the old NG1 "no sharing" boundary in
favour of one sanctioned, inspectable sharing surface (PRD §9.3 amended).

internal/files:
- backend.go  service, layout, quota/usage, live-session registry, operator API
- fs.go       per-session virtual FS; resolve() is the single security
              chokepoint (area confinement + symlink-escape guard) + pkg/sftp
              request handlers
- server.go   subsystem handler: key auth -> member session -> request server,
              with byte metering and force-disconnect
- tui.go      in-BBS member browser (hub plugin "Files")
- admin.go    operator management TUI: sessions, workspaces/quotas, public area

Operator console: ssh sftp@<host> (allowlist-gated; sftpadmin@/filesadmin@
aliases) — list/disconnect sessions, set per-user quotas, revoke SFTP access,
toggle public write, moderate the public area.

store: files_access (per-user quota override + revoked) and files_settings
(public-write mode) tables + methods. main.go wiring guarded by AGENTBBS_FILES
(+ AGENTBBS_FILES_QUOTA_MB, default 1 GiB). Route names reserved.

Tests (incl -race): path traversal/confinement, symlink-escape rejection,
public-write ACL, quota enforcement, usage accounting, and an end-to-end run
against a real SFTP client. Docs: docs/files.md; PRD §5.3/§5.3.1/§9.3 + README
updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-23 09:35:04 +00:00

3.7 KiB
Raw Blame History

Files (SFTP) — member storage

AgentBBS gives every verified member file storage over SFTP, reachable with the same SSH key they log in with. It rides the existing :22 listener as an SSH subsystem, so there is no new port and no separate account:

# interactive
sftp files@bbs.profullstack.com

# one-shot copies (same endpoint, same key)
scp report.pdf files@bbs.profullstack.com:/me/
rsync -avz ./site/ -e ssh files@bbs.profullstack.com:/me/site/

The username (files) is conventional and ignored — identity is your SSH key (one key = one account, like the rest of the BBS). scp/rsync work because they tunnel over the same SSH transport.

Two areas

When you connect you see a virtual root with two directories:

Path What it is Access
/me Your private per-user workspace read/write, quota-limited
/public The single shared public file area (old-school BBS file area) world-read; members-only write by default

There is no path from one member's /me to another's — the only sharing surface is the one public area (PRD §9.3, amended). Both areas are confined: a path that tries to escape its root (../, an absolute path, or a planted symlink) is rejected.

Quotas

Each private workspace has a byte quota (default 1 GiB, set by AGENTBBS_FILES_QUOTA_MB). Writes that would exceed it fail. Operators can set a per-user override in the management TUI. The public area is operator-managed and not metered per user.

In-BBS browser

Inside the hub, the Files entry opens a TUI browser for your workspace and the public area: navigate, view text files, make directories, rename, and delete, with a live usage gauge. Actual transfers happen over SFTP/scp/rsync (a PTY can't move file bytes).

Operator management TUI

Operators (the $AGENTBBS_ADMINS allowlist) reach the SFTP management console with:

ssh sftp@bbs.profullstack.com      # aliases: sftpadmin@, filesadmin@

Panes (Tab to switch):

  • Sessions — live SFTP connections (user, remote, rx/tx, idle); x force-disconnects.
  • Workspaces — every member's usage vs. quota; Q sets a per-user quota, x revokes/restores SFTP access (the BBS login is unaffected).
  • Public area — t toggles members' write access; x removes an entry (moderation).

Per PRD §9.2 the operator can inspect and act on hosted files; storage is not content-blind.

Configuration

Var Default Meaning
AGENTBBS_FILES 1 enable the SFTP subsystem + Files plugin (0 disables)
AGENTBBS_FILES_QUOTA_MB 1024 default per-user workspace quota (MB)
AGENTBBS_DATA ./data storage lives under <data>/files/{users,public}

Implementation

  • internal/files — a fully virtual Go SFTP server (github.com/pkg/sftp + crypto/ssh); no OS users.
    • backend.go — service, layout, quota/usage, live-session registry, operator surface.
    • fs.go — per-session virtual filesystem: resolve() is the single security chokepoint (area confinement + symlink-escape guard) and the pkg/sftp request handlers.
    • server.go — the wish.WithSubsystem("sftp", …) handler: key auth → member session → request server, with byte metering and force-disconnect.
    • tui.go — the in-BBS member browser plugin.
    • admin.go — the operator management TUI.
  • Storage: files_access (per-user quota override + revoked flag) and files_settings (e.g. public-write mode) in the shared SQLite store.

Security is covered by internal/files/*_test.go: path-traversal/confinement, symlink-escape rejection, the public-write ACL, quota enforcement, and an end-to-end run against a real SFTP client.