@shieldfive/cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,117 @@ All notable changes to `@shieldfive/cli` will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## Unreleased
9
+
10
+ ## 0.3.0 - 2026-09-16
11
+
12
+ ### Added
13
+
14
+ - **`sf login`, `sf status`, `sf logout`.** `sf login` prompts for your password
15
+ and, if two-factor is enabled, a code, then starts an agent that holds the
16
+ signed-in session and the unlocked vault key in memory only. `sf push` and
17
+ `sf sync` use it when it is running and need nothing in the environment. The
18
+ agent locks itself after 8 hours without use (`--idle=<hours>` to change it),
19
+ and `sf logout` revokes the session on the server.
20
+ - **`sf verify <file>...`** reports whether each file is safely stored in your
21
+ vault. The bytes on disk now must match an upload the agent performed, and the
22
+ server must confirm that upload at the moment of asking. Names and sizes play
23
+ no part. Exits 0 only when every file is confirmed, so a script can gate on it.
24
+ - **Unattended sync on two-factor accounts.** One interactive `sf login` is
25
+ enough: the agent refreshes the session without prompting again until it locks
26
+ or you log out.
27
+
28
+ - **`sf logout --everywhere`** signs out every session on the account, including
29
+ the browser and phone.
30
+
31
+ ### Security
32
+
33
+ - The agent's socket accepts six operations: `status`, `upload`, `sync`,
34
+ `verify`, `lock`, `logout`. None lists, downloads or decrypts vault contents,
35
+ or returns key material, and a test pins the list.
36
+ - `sf login` never reads `SF_PASSWORD`. The agent is started with an explicit
37
+ environment allowlist, so a password exported for the older flow does not
38
+ reach it.
39
+ - Uploads are recorded in `~/.shieldfive/ledger/<account>.jsonl` with an HMAC of
40
+ each file's contents under a key derived from the vault key rather than a
41
+ plain hash, so the ledger cannot confirm which documents you hold to anyone
42
+ without that key.
43
+ - Hardened before release after a security review:
44
+ - The ledger records the MAC of the bytes actually encrypted, read in the
45
+ same pass as the upload. Hashing the file before and after could not see a
46
+ change made and undone mid-upload, and `sf verify` would then have called a
47
+ file backed up that the vault did not hold.
48
+ - Ledger records carry a tag under the vault-derived key and a device id;
49
+ forged lines, and lines copied from another machine, are ignored.
50
+ - `SF_EMAIL` and `SF_PASSWORD` take precedence over a running agent, so a
51
+ script cannot be redirected to a different account.
52
+ - A lock file stops two agents from starting at once, and an agent that is
53
+ still revoking its session cannot delete the socket of the one that replaced
54
+ it.
55
+ - `sf status` no longer postpones the idle lock.
56
+ - Stopping wipes keys before touching the network, and its token refresh and
57
+ revoke share a 5 second budget, so an unreachable server cannot keep the
58
+ agent alive. An upload already running keeps its own copy of the key.
59
+ - The socket lives in `~/.shieldfive/run` everywhere, so cron jobs and other
60
+ minimal environments find the agent.
61
+
62
+ ### Notes
63
+
64
+ - `sf login` has not been run against production. The pieces are covered by
65
+ offline tests, including one that runs the agent as its own process against a
66
+ local stub of the auth and verify endpoints. Sign-in, unlock and session
67
+ refresh against the live backend are not.
68
+ - The agent does not run on Windows. `SF_EMAIL` and `SF_PASSWORD` keep working
69
+ there, and everywhere, exactly as before.
70
+ - The ledger starts empty. Existing `.shieldfive-sync.json` manifests are not
71
+ imported: they hold no content hash to check a claim against.
72
+
73
+ ## 0.2.1 - 2026-09-14
74
+
75
+ ### Fixed
76
+
77
+ - **Files of 5 MiB or less could not be uploaded at all, since 2026-09-03.** The
78
+ server moved the direct-upload path to a presigned S3 PUT and stopped
79
+ returning `authToken` (web `b52b4c8`, PR #726); the client hard-required that
80
+ token and threw `Direct upload session is missing credentials.` before sending
81
+ a byte. The direct path now `PUT`s the ciphertext straight at the presigned
82
+ URL with no `Authorization` and no `X-Bz-*` headers, and sends no `b2FileId`
83
+ at finalize — a presigned PUT returns an ETag, not a Backblaze file id, and
84
+ forwarding it would have been persisted verbatim as the storage id. Files
85
+ larger than 5 MiB were never affected; the multipart path is unchanged and
86
+ keeps its token, its `X-Bz-*` headers and its session-derived `b2FileId`.
87
+
88
+ ### Changed
89
+
90
+ - **The direct path no longer sends a wire checksum.** It previously sent
91
+ `X-Bz-Content-Sha1`, which Backblaze's native upload verified server-side and
92
+ rejected on mismatch. A presigned PUT signed for `host` only carries no
93
+ equivalent, and the server's finalize check compares the client's
94
+ `ciphertextHash` against the client's own `partSha1Array[0]` — both
95
+ client-supplied, so always equal. That protection is removed and not replaced:
96
+ integrity on this path now rests on the upload proof and on AES-GCM's tag at
97
+ download. Stated rather than left to be discovered.
98
+ - The direct path also no longer checks the upload response shape. It used to
99
+ require a `fileId` in the body; a presigned PUT returns none, so any 2xx is
100
+ now accepted and a PUT that answered 200 without durably storing the object
101
+ surfaces later as finalize's 409 rather than immediately.
102
+
103
+ ### Notes
104
+
105
+ - **The rewritten direct path has not been run against production.** It is
106
+ covered by the offline mock test only, which is the same class of evidence
107
+ that let 0.2.0 ship broken — the old fixture supplied an `authToken` the
108
+ server had stopped sending. The mock now matches the live response shape, and
109
+ four mutations of the client (re-adding `Authorization`, re-sending
110
+ `b2FileId`, reverting to `POST`, restoring the token requirement) each fail
111
+ the suite. That is a contract test, not a live one. One `sf push` of a file
112
+ under 5 MiB and one over it, confirmed visible and decryptable in the web app,
113
+ is still required.
114
+ - The direct path remains single-attempt: one `fetch`, no retry and no
115
+ signature refresh, where the multipart path retries. A transient 5xx or a
116
+ signature that expires mid-upload fails the file. Pre-existing, out of scope
117
+ here, and worth fixing before `sf sync --watch` is relied on.
118
+
8
119
  ## 0.2.0 - 2026-07-01
9
120
 
10
121
  ### Added
@@ -48,8 +159,10 @@ Initial public release.
48
159
 
49
160
  - The cryptographic core (`@shieldfive/crypto`) has not had an external audit.
50
161
  Early software.
51
- - The direct (single-chunk) upload path is validated against production. The
52
- multipart path is verified byte-for-byte against the server contract and
53
- tested end to end with mocks, but has not yet been run live with a real large
54
- file.
162
+ - The direct (single-chunk) upload path was validated against production as the
163
+ backend stood on 2026-07-01. **That no longer holds:** the server moved the
164
+ direct path to a presigned PUT on 2026-09-03, and this claim was false from
165
+ that date until the fix in 0.2.1. The multipart path is verified
166
+ byte-for-byte against the server contract and tested end to end with mocks,
167
+ but has not yet been run live with a real large file.
55
168
  - `sf sync` is append-only: it does not yet mirror local deletions or renames.
package/README.md CHANGED
@@ -27,15 +27,25 @@ size, uploading nothing.
27
27
 
28
28
  - The underlying cryptography ([`@shieldfive/crypto`](https://github.com/shieldfive/crypto))
29
29
  has **not** undergone an external audit yet. Treat this as early software.
30
- - The direct upload path (files up to one 5 MiB chunk) has been run end to end
31
- against the production backend: files uploaded by this CLI appear in the web
32
- app with their real names and decrypt correctly.
30
+ - **Neither upload path has been exercised against production since 2026-09-03.**
31
+ The direct (≤ 5 MiB) path was validated end to end against the backend as it
32
+ stood at 0.1.0, but the server then moved that path to a presigned S3 PUT and
33
+ stopped issuing an upload token. 0.2.0 hard-required that token, so it could
34
+ not upload any file of 5 MiB or less at all. This release rewrites the direct
35
+ path to the presigned PUT. It is covered by the offline mock test in
36
+ [`test/upload.flow.test.mjs`](test/upload.flow.test.mjs) and sends byte-for-byte
37
+ the request the web app sends, but it has not been run live.
33
38
  - The **multipart** path (files larger than 5 MiB) is covered by a byte-for-byte
34
39
  review against the server contract and a mock end-to-end test that decrypts
35
40
  every part, but has not yet been exercised against production with a real
36
41
  large file.
37
42
  - `sf sync` is **append-only**: it uploads new and changed files; it does not
38
43
  yet mirror local deletions or renames into the vault.
44
+ - **`sf login` and the agent have not been run against production.** They are
45
+ covered by offline tests, including one that runs the agent as its own process
46
+ and reaches it from separate `sf` processes against a local stub of the auth
47
+ and verify endpoints. Sign-in, unlock and session refresh against the live
48
+ backend are not covered.
39
49
 
40
50
  ## Requirements
41
51
 
@@ -61,27 +71,58 @@ trust it):
61
71
  git clone https://github.com/shieldfive/cli.git
62
72
  cd cli
63
73
  npm install # @shieldfive/crypto (+ libsodium), @supabase/supabase-js, @noble/*
64
- npm test # 27/27
74
+ npm test # 107 tests
65
75
  ```
66
76
 
67
77
  ## Commands
68
78
 
69
79
  ```
70
- sf encrypt <folder> encrypt each file locally, upload nothing (no account needed)
71
- sf push <folder> sign in, unlock, encrypt, upload every file once
80
+ sf login [--idle=<hours>] sign in once; an agent holds the session in memory (locks after 8 h idle)
81
+ sf status is an agent running, and for which account
82
+ sf logout [--everywhere] revoke the session and stop the agent; --everywhere signs out every device
83
+ sf push <folder> encrypt and upload every file once
72
84
  sf sync <folder> [--watch] [--interval=N] upload new/changed files; --watch keeps a poll loop (N seconds, default 5)
85
+ sf verify <file>... report whether each file is safely stored in your vault
86
+ sf encrypt <folder> encrypt each file locally, upload nothing (no account needed)
73
87
  ```
74
88
 
75
89
  `sf push` and `sf sync` pick the direct or multipart upload path automatically
76
- from the file size. `sf sync` writes a `.shieldfive-sync.json` manifest in the
77
- target folder that records what has already been uploaded (by size and mtime),
78
- so unchanged files are skipped and an interrupted run does not re-upload
79
- everything.
90
+ from the file size.
91
+
92
+ With an agent running, `sf sync` records uploads in the agent's ledger (see
93
+ [What the agent can and cannot do](#what-the-agent-can-and-cannot-do)) and
94
+ `sf verify` works. Without one, `sf sync` writes a `.shieldfive-sync.json`
95
+ manifest in the target folder that records what has already been uploaded (by
96
+ size and mtime), so unchanged files are skipped and an interrupted run does not
97
+ re-upload everything; `sf verify` needs the agent.
80
98
 
81
99
  ## Running the live commands
82
100
 
83
- `sf push` and `sf sync` need only your ShieldFive account. Your password is
84
- typed, never passed on the command line:
101
+ ### With `sf login`
102
+
103
+ ```sh
104
+ sf login
105
+ sf push ./my-folder
106
+ sf sync ./my-folder --watch
107
+ sf verify ./my-folder/tax-return-2025.pdf
108
+ sf logout
109
+ ```
110
+
111
+ `sf login` prompts for your email, your password and, if it differs, your vault
112
+ password. It never reads them from the environment and there is no flag for
113
+ them. It then starts an agent in the background and exits; every later command
114
+ talks to that agent and needs nothing exported.
115
+
116
+ If `SF_EMAIL` and `SF_PASSWORD` are also set, `sf push` and `sf sync` sign in
117
+ with those instead and tell you an agent is running, so a script written for one
118
+ account is never sent to another. `sf push` exits 2 if a file changed while it
119
+ was being uploaded: the vault then holds the version that was read, not the file
120
+ as it is now.
121
+
122
+ ### Without an agent
123
+
124
+ `sf push` and `sf sync` still work from environment variables, exactly as
125
+ before. Your password is typed, never passed on the command line:
85
126
 
86
127
  ```sh
87
128
  export SF_EMAIL=you@example.com
@@ -111,6 +152,68 @@ Enter the current code from your authenticator. In a non-interactive context
111
152
  (scripts, CI) set `SF_TOTP_CODE` to the current code instead of being prompted.
112
153
  Only TOTP is supported; SMS and other factors are not.
113
154
 
155
+ With `sf login` you are asked once. The agent refreshes the stepped-up session
156
+ on its own, so `sf sync --watch` keeps working on a two-factor account until the
157
+ agent locks or you log out.
158
+
159
+ ## What the agent can and cannot do
160
+
161
+ The agent keeps two things in memory: your signed-in session and your unlocked
162
+ vault key. Neither is written to disk. It listens on a Unix socket in
163
+ `~/.shieldfive/run`, a directory only your user can enter, and refuses to start
164
+ if that directory is a symlink, owned by someone else or open to other users.
165
+ Only one agent runs at a time.
166
+
167
+ It accepts six requests: `status`, `upload`, `sync`, `verify`, `lock` and
168
+ `logout`. It cannot list what is in your vault, download a file, decrypt
169
+ anything, or hand out the key, because there is no request for any of those. A
170
+ process that reaches the socket can put files into your vault and ask whether
171
+ files are backed up. It cannot read your vault through the agent.
172
+
173
+ Uploads are recorded in `~/.shieldfive/ledger/<account>.jsonl`: the path, size,
174
+ time, vault file id, and an HMAC of the bytes that were actually encrypted, under
175
+ a key derived from your vault key. A plain hash would let anyone holding the
176
+ ledger confirm whether you have a particular known document; the HMAC does not,
177
+ without your vault key. Each record also carries a tag under that key, so a line
178
+ added to the ledger by anything other than the agent is ignored, and records
179
+ made on another machine do not count on this one.
180
+
181
+ `sf verify` reports a file as **backed up** only when the bytes on disk now
182
+ match an upload in the ledger and the server confirms, at that moment, that the
183
+ upload is stored, complete, intact and not in your Bin. It never decides by name
184
+ or size. The other answers:
185
+
186
+ | Answer | Meaning |
187
+ |---|---|
188
+ | `NOT confirmed` | these bytes were uploaded, but the server cannot confirm they are still safely stored |
189
+ | `changed since upload` | this path was uploaded, but the file has changed since |
190
+ | `no upload record` | this agent never uploaded these bytes; they may still be in your vault from another device |
191
+ | `unreadable` | the local file could not be read |
192
+
193
+ `no upload record` does not mean the file is missing from your vault. Do not
194
+ delete anything on the strength of that answer.
195
+
196
+ The agent locks itself after 8 hours without an upload, sync or verify
197
+ (`sf login --idle=<hours>` to change it; `sf status` does not count). Locking and
198
+ `sf logout` both overwrite the key in memory first and then sign the session out
199
+ on the server. Sessions on ShieldFive do not expire on their own, so a session
200
+ that is forgotten rather than signed out would stay valid. If the server cannot
201
+ be reached when you log out, `sf logout` says the session is still valid and
202
+ exits 1; run `sf login` and then `sf logout --everywhere` once you are online.
203
+
204
+ Limits:
205
+
206
+ - Windows is not supported. Use `SF_EMAIL` and `SF_PASSWORD` there.
207
+ - Node cannot see which process connected to the socket, so directory
208
+ permissions are the only gate. This is also how `ssh-agent` works on macOS.
209
+ - Overwriting the key in memory is best-effort. A garbage-collected runtime can
210
+ copy key material during crypto operations.
211
+ - The ledger is per device. A file uploaded from another machine shows as
212
+ `no upload record` here.
213
+
214
+ The full design, including the threat model, is in
215
+ [`docs/agent-design.md`](docs/agent-design.md).
216
+
114
217
  ## How the upload works (for auditors)
115
218
 
116
219
  The upload uses **chunked AES-GCM** for file content and issues a
@@ -131,6 +234,15 @@ protocol and server-side proof expect.)
131
234
  The server issues `proofKey` when it creates the session and verifies the proof
132
235
  when finalizing. It ties the stored ciphertext to the session without the
133
236
  server ever seeing plaintext.
237
+ - **Direct** (≤ 5 MiB) — the single encrypted chunk is `PUT` at a presigned S3
238
+ URL the server issues with the session. The URL's SigV4 signature is the only
239
+ credential and it authorises exactly one object key, so the request carries no
240
+ `Authorization` header and no `X-Bz-*` headers; the client sends no storage id
241
+ at finalize, because the server reads the real one off the stored object.
242
+ Because the signature covers `host` only, nothing on this path binds the body:
243
+ the server compares the client's `ciphertextHash` against the client's own
244
+ `partSha1Array[0]`, so they always agree. Integrity here rests on the upload
245
+ proof and on AES-GCM's tag at download, not on a wire checksum.
134
246
  - **Multipart** (> 5 MiB) — the file is streamed one 5 MiB chunk at a time (never
135
247
  loaded whole into memory), each chunk uploaded as a Backblaze part. The
136
248
  ciphertext hash the server checks is SHA-1 over the concatenated raw part
@@ -153,6 +265,12 @@ file — a machine-checked demonstration that only ciphertext is uploaded.
153
265
  finalize; the streaming chunk reader
154
266
  - `src/sync.mjs` — `sf sync`: manifest, change detection, reconcile pass, watch
155
267
  loop (reuses `upload.mjs`)
268
+ - `src/prompt.mjs` — terminal prompts; the password prompt echoes nothing
269
+ - `src/agent/` — `sf login`'s agent: `server.mjs` (the process and its six
270
+ requests), `client.mjs`, `protocol.mjs` (the request allowlist), `ledger.mjs`
271
+ (HMAC upload ledger and `verify` classification), `paths.mjs` (socket
272
+ directory checks), `main.mjs` (entry point and session handoff)
273
+ - `docs/agent-design.md` — design record and threat model for the agent
156
274
  - `src/sfCrypto.mjs` — the post-quantum hybrid encrypt/decrypt used by the
157
275
  `sf encrypt` demo
158
276
  - `test/*.test.mjs` — round-trip guarantees plus the mock end-to-end upload and
package/SECURITY.md CHANGED
@@ -63,9 +63,13 @@ not pursue civil claims or refer law enforcement against researchers who:
63
63
 
64
64
  ## Bug bounty
65
65
 
66
- ShieldFive operates a paid bug bounty program. For current scope, reward tiers,
67
- rules of engagement, and submission instructions, see
68
- https://shieldfive.com/security/bug-bounty.
66
+ **There is no bug bounty.** ShieldFive ran one until 2026-07; it closed, and
67
+ `/security/bug-bounty` now redirects to the security page. Reports are answered
68
+ on the timelines above, and credited if you want credit. They are not paid.
69
+
70
+ This section previously said the opposite and pointed at that redirected URL.
71
+ It is corrected here rather than removed, so anyone who read the old text finds
72
+ out what changed.
69
73
 
70
74
  ## Scope
71
75
 
@@ -79,6 +83,6 @@ Out of scope for *this* repository (report elsewhere or not at all):
79
83
  [`@shieldfive/crypto`](https://github.com/shieldfive/crypto).
80
84
  - Vulnerabilities in dependencies (`@noble/*`, `@supabase/supabase-js`) — report
81
85
  those upstream.
82
- - Server-side issues in the ShieldFive backend — report via the bug bounty
83
- program above.
86
+ - Server-side issues in the ShieldFive backend — same address,
87
+ `security@shieldfive.com`, different codebase.
84
88
  - Attacks that require an attacker to already control the user's device.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shieldfive/cli",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "type": "module",
5
5
  "description": "Open-source command-line client for ShieldFive: encrypt a folder on your machine and sync it to your EU-hosted, post-quantum vault. Read the code; it encrypts before upload.",
6
6
  "license": "Apache-2.0",
@@ -0,0 +1,102 @@
1
+ // ShieldFive CLI — talk to a running agent.
2
+
3
+ import { connect } from 'node:net'
4
+
5
+ import { socketPath } from './paths.mjs'
6
+ import { encode, lineSplitter } from './protocol.mjs'
7
+
8
+ export class AgentUnavailableError extends Error {
9
+ constructor(message) {
10
+ super(message)
11
+ this.name = 'AgentUnavailableError'
12
+ this.code = 'agent_unavailable'
13
+ }
14
+ }
15
+
16
+ export class AgentRequestError extends Error {
17
+ constructor(code, message) {
18
+ super(message)
19
+ this.name = 'AgentRequestError'
20
+ this.code = code
21
+ }
22
+ }
23
+
24
+ /**
25
+ * Send one request and resolve with the result.
26
+ *
27
+ * `timeoutMs: 0` disables the timeout, which uploads and syncs need: a large
28
+ * file can take longer than any fixed number.
29
+ */
30
+ export function request(op, args = {}, { path, timeoutMs = 10_000 } = {}) {
31
+ return new Promise((resolve, reject) => {
32
+ // Resolved here rather than as a default parameter, so a platform the agent
33
+ // does not support rejects this promise instead of throwing out of it.
34
+ let socketFile
35
+ try {
36
+ socketFile = path ?? socketPath()
37
+ } catch (err) {
38
+ reject(err)
39
+ return
40
+ }
41
+
42
+ let settled = false
43
+ const socket = connect({ path: socketFile })
44
+
45
+ const settle = (fn, value) => {
46
+ if (settled) return
47
+ settled = true
48
+ clearTimeout(timer)
49
+ socket.destroy()
50
+ fn(value)
51
+ }
52
+
53
+ const timer = timeoutMs
54
+ ? setTimeout(
55
+ () => settle(reject, new AgentRequestError('timeout', `Agent did not answer within ${timeoutMs} ms.`)),
56
+ timeoutMs,
57
+ )
58
+ : null
59
+
60
+ socket.on('error', (err) => {
61
+ if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
62
+ settle(reject, new AgentUnavailableError('The ShieldFive agent is not running. Run sf login.'))
63
+ } else {
64
+ settle(reject, err)
65
+ }
66
+ })
67
+
68
+ socket.setEncoding('utf8')
69
+ socket.on(
70
+ 'data',
71
+ lineSplitter((line) => {
72
+ let message
73
+ try {
74
+ message = JSON.parse(line)
75
+ } catch {
76
+ return settle(reject, new AgentRequestError('bad_response', 'Agent sent something that is not JSON.'))
77
+ }
78
+ if (message.ok) settle(resolve, message.result)
79
+ else settle(reject, new AgentRequestError(message.error?.code ?? 'error', message.error?.message ?? 'Agent refused.'))
80
+ }),
81
+ )
82
+ socket.on('close', () =>
83
+ settle(reject, new AgentRequestError('closed', 'Agent closed the connection without answering.')),
84
+ )
85
+
86
+ socket.on('connect', () => socket.write(encode({ id: 1, op, args })))
87
+ })
88
+ }
89
+
90
+ /**
91
+ * The agent's status, or null when no agent is listening or the agent cannot
92
+ * run on this platform. Callers fall back to environment credentials on null,
93
+ * so an unsupported platform must answer null, not throw.
94
+ */
95
+ export async function agentStatus(options = {}) {
96
+ try {
97
+ return await request('status', {}, { timeoutMs: 2_000, ...options })
98
+ } catch (err) {
99
+ if (err instanceof AgentUnavailableError || err.code === 'unsupported_platform') return null
100
+ throw err
101
+ }
102
+ }