@shieldfive/cli 0.1.0 → 0.2.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 +55 -0
- package/README.md +30 -6
- package/package.json +2 -1
- package/src/auth.mjs +85 -14
- package/src/cli.mjs +35 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@shieldfive/cli` will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## 0.2.0 - 2026-07-01
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Two-factor authentication (TOTP).** Accounts with an authenticator app
|
|
13
|
+
enrolled now complete the Supabase AAL2 step-up during sign-in, which the
|
|
14
|
+
server's upload gate requires. After the password, the CLI prompts
|
|
15
|
+
`Two-factor code (6 digits):` (or reads `SF_TOTP_CODE` in non-interactive
|
|
16
|
+
contexts), runs the standard challenge/verify against the verified TOTP
|
|
17
|
+
factor, and uses the elevated token for uploads. Only TOTP is supported; SMS
|
|
18
|
+
and other factors are not. Accounts without 2FA are unaffected and are never
|
|
19
|
+
prompted.
|
|
20
|
+
|
|
21
|
+
### Notes
|
|
22
|
+
|
|
23
|
+
- The step-up flow is covered by unit tests over a mocked Supabase client
|
|
24
|
+
(no-MFA, success, missing factor, malformed/wrong code, lookup failure). The
|
|
25
|
+
live challenge/verify round-trip against a real 2FA account has not yet been
|
|
26
|
+
exercised.
|
|
27
|
+
|
|
28
|
+
## 0.1.0 - 2026-07-01
|
|
29
|
+
|
|
30
|
+
Initial public release.
|
|
31
|
+
|
|
32
|
+
### Added
|
|
33
|
+
|
|
34
|
+
- `sf encrypt <folder>` - encrypt each file locally (post-quantum hybrid demo);
|
|
35
|
+
no account and no upload.
|
|
36
|
+
- `sf push <folder>` - sign in, unlock the vault, encrypt, and upload a folder.
|
|
37
|
+
Picks the direct or multipart path automatically from file size.
|
|
38
|
+
- `sf sync <folder> [--watch] [--interval=<seconds>]` - upload new and changed
|
|
39
|
+
files, once or on a poll loop, tracked by a local `.shieldfive-sync.json`
|
|
40
|
+
manifest (size + mtime) so unchanged files are skipped.
|
|
41
|
+
- Chunked AES-GCM file encryption with a server-verified HMAC upload proof.
|
|
42
|
+
- Streaming chunk reader so large files never load fully into memory; multipart
|
|
43
|
+
upload for files larger than 5 MiB.
|
|
44
|
+
- Baked-in ShieldFive public backend configuration, so only `SF_EMAIL` and
|
|
45
|
+
`SF_PASSWORD` are required (endpoints override via env for a dev backend).
|
|
46
|
+
|
|
47
|
+
### Notes
|
|
48
|
+
|
|
49
|
+
- The cryptographic core (`@shieldfive/crypto`) has not had an external audit.
|
|
50
|
+
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.
|
|
55
|
+
- `sf sync` is append-only: it does not yet mirror local deletions or renames.
|
package/README.md
CHANGED
|
@@ -42,7 +42,20 @@ size, uploading nothing.
|
|
|
42
42
|
- Node.js >= 20
|
|
43
43
|
- A ShieldFive account with a vault (create one in the web app first)
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
npm install -g @shieldfive/cli # provides the `sf` command
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Or run it without installing:
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
npx @shieldfive/cli --help
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
To read and build from source (the whole point — verify what it does before you
|
|
58
|
+
trust it):
|
|
46
59
|
|
|
47
60
|
```sh
|
|
48
61
|
git clone https://github.com/shieldfive/cli.git
|
|
@@ -81,11 +94,22 @@ sf sync ./my-folder --watch
|
|
|
81
94
|
|
|
82
95
|
The backend endpoints default to ShieldFive, so there is nothing else to
|
|
83
96
|
configure. `SF_API_BASE_URL`, `SF_SUPABASE_URL`, and `SF_SUPABASE_ANON_KEY` are
|
|
84
|
-
baked in with ShieldFive's public values
|
|
85
|
-
JWT gated by row-level security, the same value any browser receives
|
|
86
|
-
need overriding if you point the CLI at a development backend.
|
|
87
|
-
|
|
88
|
-
|
|
97
|
+
baked in with ShieldFive's public values (the Supabase anon key is a `role=anon`
|
|
98
|
+
JWT gated by row-level security, the same value any browser receives) and only
|
|
99
|
+
need overriding if you point the CLI at a development backend.
|
|
100
|
+
|
|
101
|
+
### Two-factor authentication
|
|
102
|
+
|
|
103
|
+
If your account has an authenticator app (TOTP) enabled, the CLI performs the
|
|
104
|
+
AAL2 step-up automatically: after your password it prompts
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
Two-factor code (6 digits):
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Enter the current code from your authenticator. In a non-interactive context
|
|
111
|
+
(scripts, CI) set `SF_TOTP_CODE` to the current code instead of being prompted.
|
|
112
|
+
Only TOTP is supported; SMS and other factors are not.
|
|
89
113
|
|
|
90
114
|
## How the upload works (for auditors)
|
|
91
115
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@shieldfive/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.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",
|
|
@@ -34,6 +34,7 @@
|
|
|
34
34
|
"src",
|
|
35
35
|
"README.md",
|
|
36
36
|
"SECURITY.md",
|
|
37
|
+
"CHANGELOG.md",
|
|
37
38
|
"LICENSE"
|
|
38
39
|
],
|
|
39
40
|
"engines": {
|
package/src/auth.mjs
CHANGED
|
@@ -1,16 +1,88 @@
|
|
|
1
1
|
// ShieldFive CLI — authentication.
|
|
2
2
|
//
|
|
3
|
-
// Signs in via Supabase to obtain a Bearer access token
|
|
4
|
-
//
|
|
5
|
-
//
|
|
3
|
+
// Signs in via Supabase to obtain a Bearer access token, elevating to AAL2 when
|
|
4
|
+
// the account has two-factor authentication (TOTP) enabled. The upload routes
|
|
5
|
+
// accept this token, and their server-side MFA gate requires an AAL2 token for
|
|
6
|
+
// enrolled accounts — so the step-up here is what makes `sf push` / `sf sync`
|
|
7
|
+
// work with 2FA on.
|
|
6
8
|
//
|
|
7
|
-
//
|
|
8
|
-
//
|
|
9
|
-
//
|
|
9
|
+
// This uses the standard Supabase MFA API (challenge + verify) directly on the
|
|
10
|
+
// signed-in client. The resulting AAL2 session token is what the server checks
|
|
11
|
+
// via getAuthenticatorAssuranceLevel.
|
|
10
12
|
|
|
11
13
|
import { createClient } from '@supabase/supabase-js'
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
// If the account requires an AAL2 step-up, run the TOTP challenge/verify flow
|
|
16
|
+
// and return the elevated access token. Returns null when no step-up is needed
|
|
17
|
+
// (the caller keeps the AAL1 token). `getTotpCode` is an async function that
|
|
18
|
+
// yields the 6-digit code; it is only invoked when a step-up is actually needed.
|
|
19
|
+
export async function stepUpMfaIfRequired({ supabase, getTotpCode }) {
|
|
20
|
+
const { data: aal, error: aalError } =
|
|
21
|
+
await supabase.auth.mfa.getAuthenticatorAssuranceLevel()
|
|
22
|
+
if (aalError) {
|
|
23
|
+
throw new Error(`Could not check two-factor status: ${aalError.message}`)
|
|
24
|
+
}
|
|
25
|
+
const needsStepUp = aal?.nextLevel === 'aal2' && aal?.currentLevel !== 'aal2'
|
|
26
|
+
if (!needsStepUp) return null
|
|
27
|
+
|
|
28
|
+
if (typeof getTotpCode !== 'function') {
|
|
29
|
+
throw new Error(
|
|
30
|
+
'This account has two-factor authentication enabled. Run in an ' +
|
|
31
|
+
'interactive terminal, or set SF_TOTP_CODE to your current 6-digit code.',
|
|
32
|
+
)
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const { data: factors, error: factorsError } =
|
|
36
|
+
await supabase.auth.mfa.listFactors()
|
|
37
|
+
if (factorsError) {
|
|
38
|
+
throw new Error(`Could not list two-factor methods: ${factorsError.message}`)
|
|
39
|
+
}
|
|
40
|
+
const totp = (factors?.totp ?? []).filter(
|
|
41
|
+
(f) => f?.id && f?.status === 'verified',
|
|
42
|
+
)
|
|
43
|
+
if (totp.length === 0) {
|
|
44
|
+
throw new Error(
|
|
45
|
+
'Two-factor is required but no verified authenticator app (TOTP) is ' +
|
|
46
|
+
'enrolled on this account. The CLI supports TOTP only.',
|
|
47
|
+
)
|
|
48
|
+
}
|
|
49
|
+
const factorId = totp[0].id
|
|
50
|
+
|
|
51
|
+
const { data: challenge, error: challengeError } =
|
|
52
|
+
await supabase.auth.mfa.challenge({ factorId })
|
|
53
|
+
if (challengeError) {
|
|
54
|
+
throw new Error(
|
|
55
|
+
`Could not start two-factor challenge: ${challengeError.message}`,
|
|
56
|
+
)
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const code = String(await getTotpCode()).trim()
|
|
60
|
+
if (!/^\d{6}$/.test(code)) {
|
|
61
|
+
throw new Error('Expected a 6-digit authenticator code.')
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const { data: verified, error: verifyError } = await supabase.auth.mfa.verify({
|
|
65
|
+
factorId,
|
|
66
|
+
challengeId: challenge.id,
|
|
67
|
+
code,
|
|
68
|
+
})
|
|
69
|
+
if (verifyError) {
|
|
70
|
+
throw new Error(`Two-factor verification failed: ${verifyError.message}`)
|
|
71
|
+
}
|
|
72
|
+
const token = verified?.access_token
|
|
73
|
+
if (!token) {
|
|
74
|
+
throw new Error('Two-factor verification did not return a session token.')
|
|
75
|
+
}
|
|
76
|
+
return token
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export async function signIn({
|
|
80
|
+
supabaseUrl,
|
|
81
|
+
anonKey,
|
|
82
|
+
email,
|
|
83
|
+
password,
|
|
84
|
+
getTotpCode,
|
|
85
|
+
}) {
|
|
14
86
|
const supabase = createClient(supabaseUrl, anonKey, {
|
|
15
87
|
auth: {
|
|
16
88
|
persistSession: false,
|
|
@@ -24,12 +96,11 @@ export async function signIn({ supabaseUrl, anonKey, email, password }) {
|
|
|
24
96
|
})
|
|
25
97
|
if (error) throw new Error(`Sign-in failed: ${error.message}`)
|
|
26
98
|
|
|
27
|
-
const
|
|
28
|
-
if (!
|
|
29
|
-
throw new Error(
|
|
30
|
-
'No access token returned. If 2FA is enabled, the MFA step-up is not yet ' +
|
|
31
|
-
'implemented in the CLI.',
|
|
32
|
-
)
|
|
99
|
+
const aal1Token = data.session?.access_token
|
|
100
|
+
if (!aal1Token) {
|
|
101
|
+
throw new Error('Sign-in returned no access token.')
|
|
33
102
|
}
|
|
34
|
-
|
|
103
|
+
|
|
104
|
+
const aal2Token = await stepUpMfaIfRequired({ supabase, getTotpCode })
|
|
105
|
+
return { accessToken: aal2Token ?? aal1Token }
|
|
35
106
|
}
|
package/src/cli.mjs
CHANGED
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
import { webcrypto } from 'node:crypto'
|
|
14
14
|
import { readFile, readdir, stat } from 'node:fs/promises'
|
|
15
15
|
import { join } from 'node:path'
|
|
16
|
+
import { createInterface } from 'node:readline'
|
|
16
17
|
|
|
17
18
|
import { deriveVaultIdentity, encryptFileForVault } from './sfCrypto.mjs'
|
|
18
19
|
|
|
@@ -29,8 +30,9 @@ function usage() {
|
|
|
29
30
|
'',
|
|
30
31
|
'push / sync need only your ShieldFive account:',
|
|
31
32
|
' SF_EMAIL, SF_PASSWORD [SF_VAULT_PASSWORD if your vault password differs]',
|
|
32
|
-
'
|
|
33
|
-
'(
|
|
33
|
+
'If two-factor (TOTP) is enabled, you are prompted for a 6-digit code',
|
|
34
|
+
'(or set SF_TOTP_CODE). SF_API_BASE_URL, SF_SUPABASE_URL, SF_SUPABASE_ANON_KEY',
|
|
35
|
+
'default to ShieldFive (override only for a development backend).',
|
|
34
36
|
'',
|
|
35
37
|
].join('\n') + '\n',
|
|
36
38
|
)
|
|
@@ -98,9 +100,36 @@ function readLiveConfig() {
|
|
|
98
100
|
}
|
|
99
101
|
}
|
|
100
102
|
|
|
101
|
-
//
|
|
102
|
-
//
|
|
103
|
-
|
|
103
|
+
// Prompt for a single line on the terminal. A TOTP code is short-lived, not a
|
|
104
|
+
// long-term secret, so echoing it is fine (unlike the password).
|
|
105
|
+
function promptLine(question) {
|
|
106
|
+
return new Promise((resolve, reject) => {
|
|
107
|
+
const rl = createInterface({ input: process.stdin, output: process.stderr })
|
|
108
|
+
rl.question(question, (answer) => {
|
|
109
|
+
rl.close()
|
|
110
|
+
resolve(answer)
|
|
111
|
+
})
|
|
112
|
+
rl.on('error', reject)
|
|
113
|
+
})
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// Source a TOTP code for the 2FA step-up: SF_TOTP_CODE if set (handy for
|
|
117
|
+
// scripting), otherwise prompt interactively. Only invoked when the account
|
|
118
|
+
// actually requires a step-up.
|
|
119
|
+
async function readTotpCode() {
|
|
120
|
+
if (process.env.SF_TOTP_CODE) return process.env.SF_TOTP_CODE
|
|
121
|
+
if (!process.stdin.isTTY) {
|
|
122
|
+
throw new Error(
|
|
123
|
+
'Two-factor code required but no terminal is attached. Set SF_TOTP_CODE ' +
|
|
124
|
+
'to your current 6-digit authenticator code.',
|
|
125
|
+
)
|
|
126
|
+
}
|
|
127
|
+
return promptLine('Two-factor code (6 digits): ')
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// Sign in (Supabase -> Bearer, with 2FA step-up if enabled) then fetch + unlock
|
|
131
|
+
// the vault root key. Shared by `push` and `sync`. Network deps are imported
|
|
132
|
+
// lazily so `sf encrypt` runs without @supabase/supabase-js.
|
|
104
133
|
async function authAndUnlock(cfg) {
|
|
105
134
|
const { signIn } = await import('./auth.mjs')
|
|
106
135
|
const { fetchAndUnlockVault } = await import('./vault.mjs')
|
|
@@ -111,6 +140,7 @@ async function authAndUnlock(cfg) {
|
|
|
111
140
|
anonKey: cfg.anonKey,
|
|
112
141
|
email: cfg.email,
|
|
113
142
|
password: cfg.password,
|
|
143
|
+
getTotpCode: readTotpCode,
|
|
114
144
|
})
|
|
115
145
|
|
|
116
146
|
process.stderr.write('unlocking vault…\n')
|