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.

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

Your /me home has one special subfolder: /me/public. Anything you put there is published on the web at ~<name>/public (the unix ~/public convention) — that, and only that, is the per-member public surface. The rest of /me stays private; there is no path from one member's /me to another's. Both 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) only ever exposes ~name/public, never the rest of a member's /me.

files.<host> is a file server, not a website host. Member homepages ("sites") live on the BBS at https://<host>/~<name>; the file host's ~user directory links out to them but does not serve them.

Quotas

Each private workspace has a byte quota (default 1 GiB, set by AGENTBBS_FILES_QUOTA_MB). The gauge measures all of /me — including your /me/public folder — and writes that would exceed it 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,public} (a member's public files are users/<name>/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 all members — each linked to their BBS site and their public files	none
/~<name>/public[/path]	That member's public files (/me/public) — browse + download	none
/~<name>	Redirects to /~<name>/public/	none
/public[/path]	The shared public area — browse + download	none
/?path=…, /upload, …	The authenticated manager: your /me + the shared /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:/me/public/
        ->  https://files.profullstack.com/~chovy/public/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.

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/

Public files over HTTP (anonymous, read-only)

The web file manager at files.<host> requires a login even to download, which is wrong for shared artifacts (a .crx download link must work for anyone). So the files.<host> Caddy site (generated by setup.sh) serves the shared /public area as unauthenticated, read-only static files, mapping 1:1 to the SFTP path:

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

Everything outside /public/* still falls through to the authenticated web manager (private /me browsing).

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.