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:

```bash
# 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:

```bash
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*):

```bash
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 `EnsureUser`s 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:

```bash
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*):

```bash
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 `EnsureUser`s 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:

```bash
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.