Security & Integrity

Tova's package management includes several mechanisms to protect against supply chain attacks and ensure reproducible builds.

Lock File

The tova.lock file pins every dependency to an exact version and commit SHA:

[lock]
generated = "2026-02-27T10:00:00Z"

["github.com/alice/tova-http"]
version = "1.3.0"
sha = "a1b2c3d4e5f6..."
source = "https://github.com/alice/tova-http.git"

["github.com/bob/tova-jwt"]
version = "1.0.0"
sha = "f6e5d4c3b2a1..."
source = "https://github.com/bob/tova-jwt.git"

[npm]
cookie-parser = "1.4.7"

What the lock file guarantees

• Reproducible builds. Everyone who runs tova install gets exactly the same versions, byte-for-byte.
• Tamper detection. If a git tag is force-pushed (changing the commit SHA), Tova detects the mismatch.
• Audit trail. The lock file shows exactly what code your project depends on, at what exact commit.

Best practices

• Commit tova.lock to version control. This ensures your entire team and CI pipeline use the same dependency versions.
• Review lock file changes. When dependencies are updated, the lock file diff shows exactly which versions changed and their new SHAs.
• Never edit tova.lock by hand. It's generated by tova install and tova update.

SHA Pinning

Every entry in tova.lock includes a sha field -- the git commit SHA that the version tag pointed to at resolution time.

How it protects you

When a package author force-pushes a git tag (changing the commit it points to), the SHA changes. On the next tova install, Tova detects the mismatch:

error: integrity check failed for github.com/alice/tova-http@v1.3.0

  Expected SHA: a1b2c3d4e5f6...
  Got SHA:      9z8y7x6w5v4u...

  The git tag may have been force-pushed. This could indicate tampering.
  Run `tova update github.com/alice/tova-http` to re-resolve.

This prevents a class of supply chain attack where an attacker compromises a repository and replaces a tagged release with malicious code.

Resolving integrity failures

If you trust the new version:

tova update github.com/alice/tova-http

This re-resolves the package, fetching the new commit and updating the SHA in tova.lock.

If you don't trust the change, investigate before updating. The SHA mismatch could indicate:

• A legitimate re-tag by the maintainer (rare but happens)
• A compromised repository
• A compromised maintainer account

Private Repository Authentication

Tova uses your existing git credentials for authentication. If you can git clone a repository, you can depend on it as a Tova package.

SSH keys

The most common setup. If your SSH key has access to a private repo:

[dependencies]
"github.com/myorg/internal-auth" = "^1.0.0"

This works because git clone uses your SSH agent.

Git credential helpers

If you use HTTPS with a credential helper (e.g., GitHub CLI, macOS Keychain), Tova inherits those credentials.

Authentication errors

If authentication fails:

error: authentication failed for github.com/myorg/internal-lib

  git clone returned: Permission denied (publickey)
  Tip: Ensure your SSH key or git credentials have access to this repo.

Verify you can access the repo manually:

git ls-remote https://github.com/myorg/internal-lib.git

Error Messages

Tova provides clear, actionable error messages for all package management failures:

Version conflict

error: version conflict for github.com/alice/tova-http

  github.com/carol/web-framework requires ^1.0.0
  github.com/dave/api-toolkit requires ^2.0.0

  These constraints cannot be satisfied simultaneously.
  Tip: Check if either dependency has a newer version that resolves this.

Network failure

error: failed to fetch github.com/alice/tova-http

  git clone failed: Could not resolve host: github.com

  Cached versions available: v1.2.0, v1.2.1
  Tip: Run with --offline to use cached versions only.

Missing entry point

error: no entry point found for github.com/alice/tova-http@v1.3.0

  Looked for: src/lib.tova, lib.tova, index.tova, src/index.tova, src/main.tova, main.tova
  Tip: Add an `entry` field to the package's tova.toml.

Circular dependency

error: circular dependency detected

  github.com/alice/http → github.com/bob/middleware → github.com/alice/http

  Tova does not allow circular module dependencies.

Comparison with Other Systems

Feature	Tova	npm	Go
Registry	None (git)	npmjs.com	None (git)
Lock file	tova.lock (TOML)	package-lock.json	go.sum
SHA pinning	Yes (commit SHA)	Yes (content hash)	Yes (content hash)
Version selection	Minimum (MVS)	Latest satisfying	Minimum (MVS)
Duplicate versions	Not allowed	Allowed (node_modules tree)	Not allowed
Private packages	Git auth	npm tokens / registry	Git auth
Integrity check	SHA match on tags	npm audit	go.sum verification

Practical Tips

Review dependency updates carefully. When tova.lock changes in a PR, check:

• Are the version bumps expected?
• Did any SHAs change for the same version? (Red flag -- possible force-push)
• Are new transitive dependencies introduced?

Use exact versions for critical infrastructure. For packages that handle auth, encryption, or data access, pin exact versions:

[dependencies]
"github.com/alice/tova-auth" = "2.1.3"

Audit your dependency tree. Run tova install and review tova.lock to see every transitive dependency your project relies on.

Prefer well-maintained packages. Check the repository's last update date, star count, and issue activity before depending on it.