Harden the lint-guard shell scanner against silent evasions (closes #121)

The guard test's shell scanner was weaker than its commit message
claimed. Two holes are closed.

shellCode now treats `<<` as a here-document only when it is a real
redirection: outside single and double quotes, followed by a delimiter
word. A `<<` inside a quoted string no longer opens a phantom
here-document that swallows the rest of the file, and a here-document
still open at end of file is a loud error rather than a silent
truncation.

assertLinterIsContainerised now cuts the joined line into the simple
commands the shell would run -- on `;`, `&&`, `||` and `|` -- and
requires the command that names the linter to begin with docker. So
`docker info; golangci-lint run` and `docker info || golangci-lint run`
are rejected, while script/lint-fix's `docker run ... golangci-lint`
still passes.

The scanner comment now names the inherent limits of a text scan.
Dockerfile.lint's citation is corrected from `lll` to `revive`, the
finding the recorded evidence actually named.

Model: opus-4-8

ARCHITECTURE.md

@@ -366,17 +366,11 @@ bucket/
 │           └── {full-hash}          # Compressed+encrypted blob
 │
 └── metadata/
-    └── {remote-key}/
+    └── {snapshot-id}/
         ├── db.zst.age               # Encrypted binary SQLite database
         └── manifest.json.zst        # Blob list (for pruning/verification)
 ```
 
-The `{remote-key}` directory name is a one-way double SHA-256 hash of the human
-snapshot ID, so the human ID (hostname, snapshot name, timestamp) is never
-written to the store as a directory name. See
-[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#remote-key-derivation) for the
-derivation and a worked example.
-
 ## Thread Safety
 
 - `Packer`: Thread-safe via mutex. Multiple goroutines can call `AddChunk()`.

Dockerfile.lint

@@ -72,11 +72,11 @@ RUN [ -n "$CHECK_EPOCH" ] || exit 1
 # running, and exits 0 reporting `0 issues.` on a tree the real config
 # fails. Demonstrated on this repo at this pin, recorded on
 # https://git.eeqj.de/sneak/vaultik/pulls/114: with a planted
-# over-length line, `script/lint` exits 1 naming the `lll` finding with
+# over-length line, `script/lint` exits 1 naming the `revive` finding
-# `linters:` and exits 0 with `linterz:`. A set-but-ineffective config
+# with `linters:` and exits 0 with `linterz:`. A set-but-ineffective
-# quietly falling back to defaults is precisely the false-green class
+# config quietly falling back to defaults is precisely the false-green
-# this gate exists to eliminate, so it must not sit in the gate's own
+# class this gate exists to eliminate, so it must not sit in the gate's
-# configuration.
+# own configuration.
 #
 # `config verify` catches it, and it does so OFFLINE at this pinned
 # version -- verified, not assumed. Under `docker run --network none`

README.md

@@ -344,7 +344,7 @@ both are set.
 ├── blobs/
 │   └── <aa>/<bb>/<full_blob_hash>
 └── metadata/
-    └── <remote-key>/
+    └── <snapshot_id>/
         ├── db.zst.age          # Encrypted binary SQLite database
         └── manifest.json.zst   # Unencrypted blob list (for pruning)
 ```
@@ -355,18 +355,8 @@ both are set.
 * `manifest.json.zst` is an unencrypted compressed JSON blob list, enabling
   pruning without the private key
 
-Snapshot IDs follow the human-readable format
+Snapshot IDs follow the format `<hostname>_<snapshot-name>_<RFC3339-timestamp>`
-`<hostname>_<snapshot-name>_<RFC3339-timestamp>` (e.g.
+(e.g. `server1_home_2025-06-01T12:00:00Z`).
-`server1_home_2025-06-01T12:00:00Z`), but this ID is never written to the
-destination store in plaintext. Each snapshot's metadata directory is named
-with its `<remote-key>`, a one-way double SHA-256 hash of the ID, so a listing
-of the store reveals no hostname or snapshot name. The backup time is not
-hidden: manifest.json.zst carries a plaintext timestamp, and object
-modification times are visible at the storage layer regardless. For example,
-`server1_home_2025-06-01T12:00:00Z` is stored under
-`metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`.
-See [docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#remote-key-derivation) for the
-derivation.
 
 ### data flow
 
@@ -383,7 +373,7 @@ derivation.
 
 **restore:**
 
-1. Download and decrypt `metadata/<remote-key>/db.zst.age`
+1. Download and decrypt `metadata/<snapshot_id>/db.zst.age`
 2. Open the binary SQLite database
 3. Query files (optionally filtered by paths)
 4. Download and decrypt required blobs

cmd/vaultik/lintdocker_test.go

@@ -1,6 +1,8 @@
 package main_test
 
 import (
+	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -252,29 +254,64 @@ func TestNoHostLintPathRemains(t *testing.T) {
 		}
 
 		name := filepath.Join("script", entry.Name())
-		for _, line := range shellCode(readRepoFile(t, name)) {
+
+		lines, err := shellCode(readRepoFile(t, name))
+		require.NoError(t, err, "scanning %s", name)
+
+		for _, line := range lines {
 			assertLinterIsContainerised(t, name, line)
 		}
 	}
 }
 
-// assertLinterIsContainerised fails if the line runs the linter without
+// assertLinterIsContainerised fails unless every command that names the
-// handing it to docker first. Position matters: docker has to come
+// linter on this joined line is a docker command. Merely mentioning
-// before the binary, or the line is running the host linter and merely
+// docker somewhere on the line is not enough; see linterRunsInDocker.
-// mentioning docker afterwards.
 func assertLinterIsContainerised(t *testing.T, name, line string) {
 	t.Helper()
 
-	at := strings.Index(line, linterBinary)
+	assert.True(t, linterRunsInDocker(line),
-	if at < 0 {
+		"%s runs %s outside a container; every command that names the"+
-		return
+			" linter must begin with docker (line: %s)", name, linterBinary,
+		line)
+}
+
+// linterRunsInDocker reports whether the linter, wherever it appears on
+// this joined shell line, is only ever the argument of a docker command.
+// The line is cut into the simple commands the shell would run -- on
+// `;`, `&&`, `||` and `|` -- and every command that names the linter
+// must begin with `docker`. This is what distinguishes the one
+// legitimate invocation, script/lint-fix's `docker run ... golangci-lint
+// run ...`, from evasions like `docker info; golangci-lint run` or
+// `docker info || golangci-lint run`, where the linter sits in a command
+// of its own that docker does not introduce.
+func linterRunsInDocker(line string) bool {
+	for _, command := range splitShellCommands(line) {
+		if !strings.Contains(command, linterBinary) {
+			continue
+		}
+
+		if !strings.HasPrefix(strings.TrimSpace(command), "docker") {
+			return false
+		}
 	}
 
-	docker := strings.Index(line, "docker")
+	return true
+}
 
-	assert.True(t, docker >= 0 && docker < at,
+// splitShellCommands breaks a joined shell line into the separate simple
-		"%s runs %s on the host; every lint run happens in a container"+
+// commands the shell would run, cutting at the `;`, `&&`, `||` and `|`
-			" (line: %s)", name, linterBinary, line)
+// operators (`||` before `|`, so the two-character operator is not split
+// twice). It is deliberately blind to quoting and to `$(...)`: no line
+// under guard puts one of these operators inside a string, and a scan
+// that tried to account for that would be the kind of half-parser this
+// file avoids.
+func splitShellCommands(line string) []string {
+	for _, op := range []string{"&&", "||", "|", ";"} {
+		line = strings.ReplaceAll(line, op, "\n")
+	}
+
+	return strings.Split(line, "\n")
 }
 
 // TestShellCodeSeesCodeAndNotProse keeps the scanner above honest. It
@@ -287,20 +324,70 @@ func assertLinterIsContainerised(t *testing.T, name, line string) {
 func TestShellCodeSeesCodeAndNotProse(t *testing.T) {
 	t.Parallel()
 
+	// A `<<` inside quotes is not a here-document, so the code after it
+	// is still scanned; a real `<<EOF` opens one and its body is dropped.
 	script := strings.Join([]string{
 		"#!/bin/sh",
 		"# a comment naming golangci-lint",
 		"cat >&2 <<EOF",
 		"prose naming golangci-lint, printed not executed",
 		"EOF",
+		`echo "a left shift << is not a here-document"`,
 		"docker run --rm \\",
 		"    \"$image\" \\",
 		"    golangci-lint run ./...",
 	}, "\n")
 
+	lines, err := shellCode(script)
+	require.NoError(t, err)
 	assert.Equal(t,
-		[]string{"cat >&2 <<EOF", `docker run --rm "$image" golangci-lint run ./...`},
+		[]string{
-		shellCode(script))
+			"cat >&2 <<EOF",
+			`echo "a left shift << is not a here-document"`,
+			`docker run --rm "$image" golangci-lint run ./...`,
+		},
+		lines)
+
+	// A here-document still open at end of file must be a loud error,
+	// not a silent truncation of everything the scanner has yet to see.
+	unterminated := strings.Join([]string{
+		"cat <<EOF",
+		"body line naming golangci-lint, no terminator follows",
+	}, "\n")
+
+	_, err = shellCode(unterminated)
+	require.Error(t, err)
+}
+
+// TestLinterCommandMustBeginWithDocker pins the property that a mention
+// of docker somewhere on the line is not enough: the command that
+// actually runs the linter has to be a docker command. The two evasions
+// from the issue place the linter in a command of its own, joined to a
+// harmless docker command by `;` or `||`; both must be rejected. The
+// containerised invocation script/lint-fix writes -- docker run with the
+// linter as its argument -- must still be accepted.
+func TestLinterCommandMustBeginWithDocker(t *testing.T) {
+	t.Parallel()
+
+	rejected := []string{
+		"docker info >/dev/null; golangci-lint run ./...",
+		"docker info || golangci-lint run ./...",
+		"docker build . && golangci-lint run ./... | tee log",
+	}
+	for _, line := range rejected {
+		assert.False(t, linterRunsInDocker(line),
+			"a linter command docker does not introduce must be rejected: %s",
+			line)
+	}
+
+	accepted := []string{
+		`docker run --rm "$image" golangci-lint run ./...`,
+		`docker run --rm --user x --volume "$ROOT:/src" img golangci-lint run --fix ./...`,
+	}
+	for _, line := range accepted {
+		assert.True(t, linterRunsInDocker(line),
+			"a docker-introduced linter command must be accepted: %s", line)
+	}
 }
 
 // assertEpochExpandedInto fails unless some instruction runs the named
@@ -410,7 +497,9 @@ func indexContaining(found []string, want string) int {
 // shellCode returns a POSIX shell script's executable lines: comments
 // dropped, here-document bodies dropped, and backslash continuations
 // joined so a multi-line command is a single string. Whitespace is
-// collapsed, as it is for Dockerfile instructions.
+// collapsed, as it is for Dockerfile instructions. A here-document left
+// open at end of file is an error rather than a silent truncation of
+// everything after its opener.
 //
 // Both exclusions are load-bearing rather than tidiness. The scripts
 // name golangci-lint in prose to state that the host binary is never
@@ -418,7 +507,11 @@ func indexContaining(found []string, want string) int {
 // container invocation -- script/lint-fix's `docker run`, whose linter
 // command sits several lines below the word `docker` -- be recognised
 // as containerised.
-func shellCode(contents string) []string {
+//
+// This is a text scan, not a shell: it cannot see a linter name
+// assembled at runtime, one split across a continuation, a script in a
+// subdirectory of script/, or anything in the Makefile.
+func shellCode(contents string) ([]string, error) {
 	var (
 		out       []string
 		joined    string
@@ -452,23 +545,82 @@ func shellCode(contents string) []string {
 		joined = ""
 	}
 
-	return out
+	if terminate != "" {
-}
+		return nil, fmt.Errorf("%w: terminator %q", errUnterminatedHeredoc,
-
+			terminate)
-// heredocTerminator returns the terminator of the here-document a
-// command opens, or "" if it opens none. Only the first on a line is
-// recognised; nothing in script/ opens two.
-func heredocTerminator(line string) string {
-	_, after, opens := strings.Cut(line, "<<")
-	if !opens {
-		return ""
 	}
 
-	// `<<-` strips leading tabs from the body; the terminator word is
+	return out, nil
-	// the same either way, and callers compare against trimmed lines.
+}
-	word, _, _ := strings.Cut(strings.TrimPrefix(after, "-"), " ")
 
-	return strings.Trim(word, `'"`)
+// errUnterminatedHeredoc is what shellCode returns when a here-document
+// is still open at end of file. Its callers require its absence, so an
+// unterminated body -- which would otherwise be swallowed silently --
+// fails the guard loudly.
+var errUnterminatedHeredoc = errors.New(
+	"here-document opened but never closed before end of file")
+
+// heredocTerminator returns the delimiter word of the here-document the
+// command opens, or "" if it opens none. A `<<` only opens one when it
+// is a real redirection: outside single and double quotes, and followed
+// by a delimiter word. A `<<` inside a quoted string, or an arithmetic
+// left shift like `$((x << 2))`, is not a here-document; the former is
+// the case this guards, the latter appears in no script here. Only the
+// first opener on a line is recognised; nothing in script/ opens two.
+func heredocTerminator(line string) string {
+	var quote byte // 0 when outside quotes, else '\'' or '"'
+
+	for i := 0; i+1 < len(line); i++ {
+		c := line[i]
+
+		switch {
+		case quote != 0:
+			if c == quote {
+				quote = 0
+			}
+		case c == '\'' || c == '"':
+			quote = c
+		case c == '<' && line[i+1] == '<':
+			return heredocWord(line[i+2:])
+		}
+	}
+
+	return ""
+}
+
+// heredocWord extracts the delimiter that follows `<<` or `<<-`: it drops
+// an optional `-`, skips blanks, then reads the delimiter -- quoted or
+// bare -- and returns it with quotes removed. `<<-'EOF'` and `<< EOF`
+// both yield "EOF". It returns "" when no word follows, so a bare `<<`
+// opens nothing.
+func heredocWord(after string) string {
+	after = strings.TrimLeft(strings.TrimPrefix(after, "-"), " \t")
+
+	var (
+		word  strings.Builder
+		quote byte
+	)
+
+	for i := range len(after) {
+		c := after[i]
+
+		switch {
+		case quote != 0:
+			if c == quote {
+				quote = 0
+			} else {
+				word.WriteByte(c)
+			}
+		case c == '\'' || c == '"':
+			quote = c
+		case c == ' ' || c == '\t':
+			return word.String()
+		default:
+			word.WriteByte(c)
+		}
+	}
+
+	return word.String()
 }
 
 // readRepoFile reads a file by its path relative to the repository

docs/DATAMODEL.md

@@ -194,10 +194,8 @@ After a snapshot is completed:
 2. Clean temporary database to contain only current snapshot data
 3. Export to SQL dump using sqlite3
 4. Compress with zstd and encrypt with age
-5. Upload to S3 as `metadata/{remote-key}/db.zst.age`
+5. Upload to S3 as `metadata/{snapshot-id}/db.zst.age`
-6. Generate blob manifest and upload as `metadata/{remote-key}/manifest.json.zst`
+6. Generate blob manifest and upload as `metadata/{snapshot-id}/manifest.json.zst`
-
-The `{remote-key}` directory name is a one-way hash of the human snapshot ID, so the ID is never written to the store in plaintext; see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation).
 
 ### 4. Restore Process
 

docs/REPOSTRUCTURE.md

@@ -17,13 +17,11 @@ Vaultik stores all backup data in an S3-compatible object store. The repository
 │       └── <hash[2:4]>/
 │           └── <full-hash>
 └── metadata/
-    └── <remote-key>/
+    └── <snapshot-id>/
         ├── db.zst.age
         └── manifest.json.zst
 ```
 
-The metadata subdirectory is named with the **remote key**, a one-way hash of the snapshot ID, not with the human-readable snapshot ID itself. See [Remote Key Derivation](#remote-key-derivation).
-
 ## Blobs Directory (`blobs/`)
 
 ### Structure
@@ -42,11 +40,9 @@ Blobs contain the actual file data from backups and must be encrypted for securi
 
 ## Metadata Directory (`metadata/`)
 
-Each snapshot has its own subdirectory. The directory is **not** named with the human-readable snapshot ID; it is named with the remote key — a one-way hash of that ID. The human ID is never written to the destination store as a directory name (see [Remote Key Derivation](#remote-key-derivation)).
+Each snapshot has its own subdirectory named with the snapshot ID.
 
 ### Snapshot ID Format
-
-The human-readable snapshot ID is used in CLI arguments, log lines, and the local database. It is not written to the destination store.
 - **Format**: `<hostname>_<snapshot-name>_<RFC3339>` (or `<hostname>_<RFC3339>` if no
   name was specified)
 - **Example**: `laptop_home_2024-01-15T14:30:52Z`
@@ -55,19 +51,6 @@ The human-readable snapshot ID is used in CLI arguments, log lines, and the loca
   - Snapshot name from the configured `snapshots:` map (optional)
   - RFC3339 UTC timestamp
 
-This ID reveals the hostname, the configured snapshot name, and the backup time, so it is never used as the on-disk directory name — the remote key is used instead.
-
-### Remote Key Derivation
-
-The remote key is `hex(SHA256(SHA256("vaultik|" + snapshot-id)))`: a double SHA-256 over the snapshot ID, with a `vaultik|` domain-separation prefix. The result is a 64-character hex string with no structure a remote observer can reverse. Implemented in `internal/snapshot/remotekey.go`.
-
-Worked example:
-- Snapshot ID: `server1_home_2025-06-01T12:00:00Z`
-- Remote key: `17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa`
-- Directory: `metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`
-
-Because the hash is one-way, a listing of the destination store reveals neither the hostname nor the snapshot name of any backup. The same remote key is stored in the manifest's `snapshot_id` field.
-
 ### Files in Each Snapshot Directory
 
 #### `db.zst.age` - Encrypted Database
@@ -85,17 +68,16 @@ Because the hash is one-way, a listing of the destination store reveals neither
 - **Structure**:
 ```json
 {
-  "snapshot_id": "17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa",
+  "snapshot_id": "laptop_home_2024-01-15T14:30:52Z",
-  "timestamp": "2025-06-01T12:00:00Z",
+  "timestamp": "2024-01-15T14:30:52Z",
   "blob_count": 42,
-  "total_compressed_size": 1048576,
   "blobs": [
-    { "hash": "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 24576 },
+    "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678",
-    { "hash": "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 32768 }
+    "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
+    ...
   ]
 }
 ```
-`snapshot_id` is the remote key (a hash), not the human ID; `timestamp` is written in the clear.
 
 ### Why Manifest is Unencrypted
 The manifest must be readable without the private key to enable:
@@ -104,7 +86,7 @@ The manifest must be readable without the private key to enable:
 3. **Verification** - Checking blob existence without decryption
 4. **Cross-snapshot deduplication analysis** - Finding shared blobs between snapshots
 
-The manifest contains the remote key, the backup timestamp, the blob count and total compressed size, and each blob's hash and compressed size. It contains no file names, paths, or other decrypted metadata.
+The manifest only contains blob hashes, not file names or any other sensitive information.
 
 ## Security Considerations
 
@@ -114,21 +96,19 @@ The manifest contains the remote key, the backup timestamp, the blob count and t
 - **File-to-chunk mappings** (in db.zst.age)
 
 ### What's Not Encrypted
-- **The remote key** — directory names and the manifest `snapshot_id`, a one-way hash of the snapshot ID (see [Remote Key Derivation](#remote-key-derivation))
+- **Blob hashes** (in manifest.json.zst)
-- **The backup timestamp** (in manifest.json.zst)
+- **Snapshot IDs** (directory names)
-- **Blob hashes and their compressed sizes** (in manifest.json.zst)
+- **Blob count per snapshot** (in manifest.json.zst)
-- **Blob count and total compressed size per snapshot** (in manifest.json.zst)
 
 ### Privacy Implications
-From the unencrypted data, an observer of the destination store can determine:
+From the unencrypted data, an observer can determine:
-- **When each backup was taken** — not from the directory name, which is a one-way hash, but from the plaintext `timestamp` field in manifest.json.zst, which is published in the clear
+- When backups were taken (from snapshot IDs)
-- How many blobs each snapshot references, and the total compressed size
+- Which hostname created backups (from snapshot IDs)
-- The compressed size of each blob, and which blobs are shared between snapshots (deduplication patterns)
+- How many blobs each snapshot references
-
+- Which blobs are shared between snapshots (deduplication patterns)
-Together these give an observer a timing-and-size profile of every snapshot. This is an accepted, documented property of the format, not a defect: the manifest is unencrypted so that pruning can run without the private key, and the timing channel could not be closed by encrypting it anyway — object creation times and per-object sizes stay visible at the storage layer on both `s3://` and `file://` destinations regardless.
+- The size of each encrypted blob
 
 An observer cannot determine:
-- The hostname or snapshot name of any backup (the directory name and the manifest `snapshot_id` are one-way hashes of the human ID)
 - File names or paths
 - File contents
 - File permissions or ownership

internal/snapshot/remotekey.go

@@ -22,9 +22,8 @@ const remoteKeyPrefix = "vaultik|"
 //
 //   - the "metadata/<remote-key>/..." subdirectory on the storage
 //     backend so a directory listing of the bucket / file:// dest
-//     doesn't reveal hostnames or configured snapshot names. (The
+//     doesn't reveal hostnames, configured snapshot names, or backup
-//     backup time is not hidden: the manifest.json.zst inside that
+//     timestamps;
-//     directory carries a plaintext RFC3339 timestamp.)
 //   - the `snapshot_id` field of the unencrypted manifest.json.zst
 //     for the same reason;
 //   - any code path that needs to translate a known local snapshot ID

internal/snapshot/snapshot.go

@@ -840,10 +840,8 @@ func (sm *SnapshotManager) generateBlobManifest(
 	}
 
 	// Create manifest. SnapshotID in the unencrypted manifest is the
-	// double-SHA256 remote key (see RemoteSnapshotKey), not the human ID,
+	// double-SHA256 remote key, not the human ID, so the public bytes
-	// so neither this field nor the directory name reveals the hostname or
+	// don't reveal hostname/snapshot-name/timestamp metadata.
-	// snapshot name. Timestamp below is written in the clear, so the backup
-	// time is observable to anyone who can read the manifest.
 	manifest := &Manifest{
 		SnapshotID:          RemoteSnapshotKey(snapshotID),
 		Timestamp:           time.Now().UTC().Format(time.RFC3339),