Skip to content

files.md

Latest commit

 

History

History
202 lines (155 loc) · 8.48 KB

files.md

File metadata and controls

202 lines (155 loc) · 8.48 KB
Raw

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 Your own public files area, published at ~<name>/public read/write (yours); world-read anonymously

These are two separate areas — /public is a sibling of /me, not a folder inside it. /me stays fully private; anything you put in /public is published on the web at ~<name>/public. Both count toward your quota. 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 your private /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 member has a byte quota (default 1 GiB, set by AGENTBBS_FILES_QUOTA_MB). The gauge sums both of your areas — private /me and your public /public — and writes that would exceed it fail. Operators can set a per-user override in the management TUI.

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} — private /me is users/<name>, public /public is public/<name>

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 own public files (/public) — browse + download none
/~<name> Redirects to /~<name>/public/ none
/?path=…, /upload, … The authenticated manager: your /me and your /public webmail login

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

scp index.html files@files.profullstack.com:/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.