@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 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
- Not yet published to npm. For now, clone and run:
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 — the Supabase anon key is a `role=anon`
85
- JWT gated by row-level security, the same value any browser receives — and only
86
- need overriding if you point the CLI at a development backend. If two-factor
87
- authentication is enabled on your account, the MFA step-up is not yet handled by
88
- the CLI.
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.1.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. The web upload routes
4
- // now accept this token (Track A: cookie -> Bearer), so it is what `sf push`
5
- // will use. Same token shape the mobile app uses.
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
- // NEEDS LIVE TEST: requires your real Supabase URL + anon key + account. If you
8
- // have 2FA enabled, an AAL2 step-up is required and is NOT handled here yet
9
- // (mirror the mobile MFA flow when you wire it).
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
- export async function signIn({ supabaseUrl, anonKey, email, password }) {
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 accessToken = data.session?.access_token
28
- if (!accessToken) {
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
- return { accessToken }
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
- 'SF_API_BASE_URL, SF_SUPABASE_URL, SF_SUPABASE_ANON_KEY default to ShieldFive',
33
- '(override only for a development backend).',
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
- // Sign in (Supabase -> Bearer) then fetch + unlock the vault root key. Shared by
102
- // `push` and `sync`. Network deps are imported lazily so `sf encrypt` runs
103
- // without @supabase/supabase-js.
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')