cacbdd571f
In Theseus, Pithos now opens only with the vault unlocked: it asks Theseus for the unlock (api.vault.requestUnlock), and Theseus shows its own PIN prompt, falling back to the master password after three wrong tries. Pithos never sees either. When the vault locks (Settings > Lock now) Pithos locks within a few seconds; the add-on watches from the main process because a hidden panel's timers run about once a minute. The guide's phrase step gains "Use my Theseus vault" (the default when a vault exists): the add-on derives the 12-word phrase from the vault (purpose path pithos/sia-recovery/v1, first 16 bytes as BIP-39 entropy) and hands it straight to s3d, so there is nothing to write down and the vault backup restores storage access. The path is now fixed; changing it would cut users off from their data. Needs the vault-derive capability. On a Theseus without requestUnlock it runs ungated, as before. |
||
|---|---|---|
| bin | ||
| core | ||
| desktop | ||
| scripts | ||
| test | ||
| theseus | ||
| ui | ||
| .gitignore | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
Pithos
A control panel for s3d, the Sia Foundation's S3 gateway. s3d itself is managed through a CLI and a two-route admin API; Pithos puts a UI over all of it:
- Gateway: install the pinned s3d release (SHA-256 checked), start, stop,
restart, live logs, edit
s3d.yml. - Sia connection: register s3d with an indexer (sia.storage or your own indexd) with an existing recovery phrase or a freshly generated one, and approve the connection in the browser.
- Users & keys: create and delete users, issue and revoke access keys,
copy ready-made
aws,rcloneand env-var config. - Buckets: browse as any user, create and delete buckets, upload by drag-and-drop, download, delete files and folders, presigned share links, public-read policies.
- Upload pipeline: pending, uploaded, unpinned and failed objects from
/stats/uploads, plus "flush now".
One core, three hosts
core/ control server: s3d process, CLI wrapper, SigV4 S3 client, admin API, HTTP API
ui/ the single-page UI the server serves (plain JS, no build step)
bin/pithos-web.js web console -> your browser
desktop/main.cjs desktop app -> an Electron window
theseus/ Theseus add-on -> a Theseus tab
Every host runs the same createPithos() server on a loopback port and
points a view at it. A feature added to core/ + ui/ lands in all three.
Web console
npm install
node bin/pithos-web.js
It prints a one-time sign-in link for 127.0.0.1:8700. To reach it from
another machine, set a password and put a TLS reverse proxy in front:
PITHOS_PASSWORD='long random secret' node bin/pithos-web.js --listen 0.0.0.0:8700 --allow-host pithos.example.org
Other flags: --config <s3d.yml>, --s3d <binary>, --bin-dir <dir>,
--password-file <file>.
Desktop
npm run desktop
The window signs in with the server's one-time secret; nothing else on the machine can drive the API. Quitting stops s3d cleanly. Installed s3d builds go to the app's user-data folder.
Theseus
node scripts/build-theseus-addon.mjs
builds dist/theseus-addon/pithos/ (about 0.9 MB). Copy it into
TheseusNavigator/bundled-addons/ to bundle it, or publish it as a
community extension. The dock menu has Open Pithos and Stop s3d.
Shipping an update. The add-on updates on its own extension channel, not with Theseus releases:
- Bump
versionintheseus/addon.json(andpackage.json). - Rebuild the bundled copy:
node scripts/build-theseus-addon.mjs ../TheseusNavigator/bundled-addons/pithos, then commit, so new installs carry the same version. - Sign it and publish it on the channel at
https://navigate.st/bns/theseus.x/extensions/pithos/(Sia bucketbns/theseus/extensions/pithos/), as described inTheseusNavigator/docs/ADDON-UPDATES.md.
Installed copies pick the update up within about 30 seconds of the next launch and switch to it on the launch after that. The Theseus version stays the same.
The add-on leaves out the pty module (12 MB of native code), so on Windows the indexer login runs in its own console window and Pithos picks up the result when it closes.
Which s3d instance it manages
The same one a hand-run s3d would use: S3D_CONFIG_FILE if set, otherwise
%APPDATA%\s3d\s3d.yml (Windows), ~/Library/Application Support/s3d/s3d.yml
(macOS), /etc/s3d/s3d.yml (Linux). Every s3d call Pithos makes gets
S3D_CONFIG_FILE pinned, so the daemon and the CLI calls always agree.
If another s3d process is already serving that config (a service, or one started by hand), the overview shows it as external and reads its stats, but Pithos won't start a second copy.
Pithos needs s3d v0.2.0 or newer: users list and keys list arrived
in 0.2.0. Older builds get an upgrade banner.
Security model
- The server binds loopback by default and refuses Host headers other than its own address (DNS-rebinding guard). Binding beyond loopback requires a password of at least 12 characters.
- Sessions are HttpOnly, SameSite=Strict cookies. Every non-GET request also
needs an
x-pithos: 1header, so a cross-site form cannot drive the API. - The recovery phrase is only written to the s3d login process's terminal. It is never stored, logged or sent anywhere else. A generated phrase is shown once and must be acknowledged.
- Downloads are served with a sandboxing CSP and
nosniff, so a stored HTML object cannot run script on the console's origin. - s3d keeps access-key secrets in plain text in its own SQLite database. Pithos shows them to whoever is signed in to the console, so treat console access as root on the gateway.
How it talks to s3d
| Need | Mechanism |
|---|---|
| users, keys, version, registration check | s3d users …, s3d keys …, s3d version, s3d login with stdin closed |
| indexer login | s3d login in a pseudo-terminal (it reads the phrase with term.ReadPassword) |
| buckets and objects | the S3 API, signed with SigV4 as the chosen user's first access key |
| stats, flush | the admin API (/stats/uploads, /objects/flush) with the configured admin password |
test/sigv4.test.js cross-checks the signer against the AWS CLI on awkward
keys and prefixes and on presigned URLs (npm test).
Limits and next steps
- Uploads are single PUTs, capped at 5 GiB (s3d's part limit). Multipart uploads from the browser would lift that.
- Object versioning, lifecycle rules and multipart-upload cleanup are not in the UI yet.
- Desktop installers (electron-builder) are not set up yet.
- Multi-tenant mode, where end users sign in with a wallet and each get
their own s3d user and quota, is the planned follow-up. It is the
Hestia direction in
Hephaestus/DESIGN-hestia.md.
License
MPL-2.0. s3d is MIT, © The Sia Foundation.