Freeze the Go implementation as a test-only oracle, with vectors

oracle/go is the Go code at 4c1507c, moved unchanged, plus test-only generators that record what it computes. tests/vectors holds the deterministic crypto/store vectors and synthetic fixtures they produce. Co-Authored-By: Claude <noreply@anthropic.com>
2026-10-08 09:55:17 +01:00
parent 4c1507c463
commit 69f4b90777
60 changed files with 4843 additions and 0 deletions
@@ -0,0 +1,42 @@
+# Go oracle (test-only)
+
+`oracle/go` is a frozen copy of the Go implementation of vault, taken from
+commit `4c1507c` ("Add unlock --idle, and packaging/repo.sh for
+repo.dixon.cx"), the last Go release on `master`. It is kept as the
+reference that the Rust implementation is checked against. It is **not**
+part of the shipped product: release builds, packages and the `vault`
+binary contain no Go code and need no Go toolchain.
+
+Provenance:
+
+- Every file under `oracle/go` is byte-identical to the same path at the
+  repository root at `4c1507c`, except the three added test files below.
+- `oracle_vectors_test.go`, `internal/pqcrypt/oracle_vectors_test.go` and
+  `internal/stream/oracle_vectors_test.go` are test-only generators. They
+  call the frozen code and write what it computes; they skip themselves
+  unless `VAULT_ORACLE_OUT` is set, and add nothing to the oracle binary.
+- Dependencies are pinned by `go.mod`/`go.sum`: CIRCL v1.6.4,
+  golang.org/x/crypto v0.53.0, x/sys v0.46.0, x/term v0.44.0. The module
+  needs Go 1.26.6 or newer.
+
+Check the copy is still faithful:
+
+```sh
+git diff --stat 4c1507c HEAD -M -- oracle/go   # renames only, plus the generators
+```
+
+Use:
+
+```sh
+oracle/gen-vectors.sh          # rewrite tests/vectors from the oracle
+(cd oracle/go && go build -o ../../target/vault-go .)   # build the oracle CLI
+(cd oracle/go && go test ./...)                          # its own test-suite
+```
+
+`cargo test` builds the oracle binary itself for the interoperability tests
+when `go` is on `PATH` (or uses `$VAULT_GO_ORACLE`), and reports them as
+skipped otherwise.
+
+All passphrases, seeds and plaintexts in the vectors are synthetic and
+public (`oracle-real passphrase`, `oracle-decoy passphrase`, fixed byte
+patterns). Never commit real keys or real vault contents.