agentbbs/docs/files.md

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.

Who can use it

Members only — but free for every member. Like IRC and News, file storage is gated on membership, not on the paid Founding Lifetime plan:

• Non-members can't connect. A key that isn't a registered account is refused at the SFTP handshake (this key isn't a member — register first), and guests don't see the in-hub Files browser.
• Every verified member can connect, run, and join — free and paid alike. There is no Premium gate anywhere in the Files path; the plan only affects unrelated perks (custom email, domains, Tor).
• Operators can revoke an individual account's SFTP access (abuse response) without touching its BBS login — see the management TUI below.

Three areas

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

Path	What it is	Access
/me	Your private per-user workspace	read/write, quota-limited
/site	Your own public area, served on the web at ~<name>	read/write (yours), world-read anonymously
/public	The single shared public file area (old-school BBS file area)	world-read; members-only write by default

/me is private — there is no path from one member's /me to another's. The two public surfaces are /site (per-member, the only thing exposed at ~<name>) and the single shared /public. All three areas are confined: a path that tries to escape its root (../, an absolute path, or a planted symlink) is rejected, and the unauthenticated web surface (below) has no route into anyone's /me.

Quotas

Each member's owned storage has a byte quota (default 1 GiB, set by AGENTBBS_FILES_QUOTA_MB). The gauge sums your private /me and your public /site; writes to either that would exceed the quota fail. Operators can set a per-user override in the management TUI. The shared /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,sites,public}

Provisioning members from a public key (for external services)

Normally members onboard interactively (ssh join@). External services that want to grant a user file storage without that flow — e.g. the TronBrowser extension store letting a publisher upload bundles — can register an account directly from an SSH public key (an account is just handle + key fingerprint):

agentbbs provision-user --name acme --pubkey "ssh-ed25519 AAAA… acme@dev"
# or:  --pubkey-file ./id_ed25519.pub

It normalizes the handle with the same rules as join@ (SanitizeUsername), fingerprints the key, and EnsureUsers the member; Files/SFTP access is then available immediately (free for all members). Output is JSON ({ok, name, fingerprint, store_id}); it refuses if the key already belongs to another member or the handle is taken by a different key. The publisher can then:

scp dist.crx files@files.profullstack.com:/public/extensions/acme/

The web file host (files.<host>)

The whole site is served by the Go file manager (internal/files/web.go), which Caddy reverse-proxies. Login is optional — it gates only your private /me and writes. The public surface is anonymous, read-only, and area-confined; it has no route into anyone's /me.

URL	Serves	Auth
/	A directory of members' ~user sites, plus a sign-in link	none
/~<name>[/path]	That member's public /site — browse + download	none
/public[/path]	The shared public area — browse + download	none
/?path=…, /upload, …	The authenticated manager: your /me, /site, /public	webmail login

Clean URLs map 1:1 to the SFTP paths, so share links just work:

scp dist.crx files@files.profullstack.com:/public/extensions/acme/
        ->  https://files.profullstack.com/public/extensions/acme/dist.crx

scp index.html files@files.profullstack.com:/site/
        ->  https://files.profullstack.com/~chovy/index.html

Directories render a read-only browse listing; files stream with a content type and a short (max-age=300) cache. Sign in (top-right link, webmail password) to manage your own files.

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.