goraz v0.2.0

Feature matrix

The goal is for goraz to eventually carry every good idea from earlier projects. Not all of them are realistic or safe in a first release, so this document records each decision, including the deferrals, rather than dropping anything silently.

Tiers

  • v0.1: in the first release.
  • v0.2: the next release. The design leaves room for it.
  • Later: planned, but it needs a new subsystem or significant design work.
  • Not planned: rejected for a stated security or scope reason. It can be reconsidered.

⚠ marks an item that is unrealistic for a first release even though it is valuable.

Vault and secret management

FeatureLearned fromTierNotes
Encrypted store over untrusted storageVault, KeePassXCv0.1Single authenticated file
All metadata encrypted, including namesKeePassXC, LastPass lessonv0.1Item count and approximate sizes remain visible
Ciphertext bound to vault, item and versionSOPS path AAD, ETH Zurichv0.1
Whole-vault integrity, with swap and deletion detectedKDBX, ETH Zurichv0.1
Key commitmentLen et al., Albertini et al.v0.1Hard to add later, costs 32 bytes per blob
Rollback detectionTUF, KeePassXC auditv0.1Local state. Limits are documented. Vault and OpenBao exclude this entirely
Multiple unlock slotsLUKS pattern, Vault recovery keysv0.1One passphrase, plus recovery code and machine keys
Fork detection between devicesOriginal, TUFv0.1Hash lineage in the manifest. Conflicts are refused, not merged
Optional key fileKeePassXC, 1Password two-secret ideav0.1Raw random bytes, no parser
Passphrase rotation without re-encryptionVault rekeyv0.1Replaces a slot
Full vault rekeyVault rekey, SOPS rotatev0.1New master key, every item re-encrypted
Secret version history and rollbackVault KV v2, Infisicalv0.1Rollback records a new version
Explicit destroyVault KV v2v0.1Backups and filesystem snapshots may still hold old data
Secret references (goraz://), read, run1Password, Teller, chamberv0.1run warns about environment exposure
inject with plain substitution1Passwordv0.2No template engine, because of the Conjur and gopass findings
redact and output maskingTeller, 1Passwordv0.2Documented as a convenience, not a boundary
scan for leaked secrets in CITellerv0.2Prefixed tokens make this practical
doctor diagnosticsgopass fsck, runtime/secret honestyv0.1Reports real protections and vault integrity
Local session agentgopass, Bitwarden sessionsv0.2⚠ Local IPC is a trust boundary (CVE-2024-42219). Needs peer credential checks
OS keyring integrationgo-keyring, 99designsv0.2⚠ See section below
Team sharing with recipientsage, SOPS, gopassLater⚠ Needs public-key authentication first. The ETH Zurich attacks concentrate here
Hybrid post-quantum recipientsage v1.3LaterVia filippo.io/age, with sharing. At-rest symmetric keys are already 256-bit
Recipient pinning and reviewgopass, SOPS updatekeysLaterWith sharing
Git-friendly per-value encryptionSOPSLater⚠ A separate seal format. It exposes key names by design, so it can't be the default store
Service vaults for scoped production and CI access1Password service accountsv0.1Scope enforced by cryptography, not by checks
Runtime client with reload and fail-closed stalenessVault agent, Dopplerv0.1service package. No listener or server
Key delivery through Kubernetes, Docker, systemd1Password Connectv0.1File or descriptor. Not through environment variables
Audit to stdout for containersVault audit devicesv0.1JSON sink. Integrity depends on the receiving log system
Sync with conflict handlingBitwarden, KeePassXCLaterv0.1 detects forks and refuses to overwrite. It doesn't merge
Pluggable blob backends (S3 and others)Vault storageLaterAn internal interface exists in v0.1 and isn't public yet
Shamir unlock quorumVault, SOPS key groupsLaterWould use a reviewed implementation
Dynamic secretsVault, InfisicalLater⚠ Needs a server and per-provider code. Every integration is a hostile parser
LeasesVaultLater⚠ Needs a running service
Encryption as a service (transit)VaultLater⚠ Needs a server
Automatic rotation with two active secretsInfisical, DopplerLaterToken rotation with overlap is in v0.1. Rotating third-party credentials needs integrations
Server, HTTP API, HA, namespacesVault, OpenBao, InfisicalLater⚠ See the explanation below
Policy language, RBAC, ABACVault, Conjur, InfisicalLater⚠ Needs a server. Almond's audit recommends keeping policies basic
Cloud KMS auto-unseal, HSMVault, InfisicalLater⚠ Network credentials and vendor SDKs, against the small-dependency goal
Identity integrations (OIDC, cloud IAM, Kubernetes)Vault, ConjurLater⚠ The most repeated source of authentication bypasses in this research
Pluginsage, Vault, passNot planned for nowThe route to code execution in several incidents. Would need a strict grammar and no data-driven lookup
Templates over stored dataConjur, gopassNot plannedCVE-2025-49828 and gopass findings
FIPS 140-3 modeInfisical, Go GOFIPS140Later⚠ Argon2id and XChaCha20 are outside the Go FIPS module. It needs a separate PBKDF2 and AES-GCM profile, which adds a second format

Token management

FeatureLearned fromTierNotes
Store third-party tokens with expiry trackingVault KV, Dopplerv0.1goraz token expiring
Issue opaque tokens with at least 256-bit secretVault service tokens, GitHubv0.1Library and CLI
Prefix and checksum for scannersGitHub, Stripe, Dopplerv0.1CRC32 is a filter only, never authentication
Only a keyed hash storedGitHub, Bitwarden Secrets Managerv0.1HMAC-SHA-256 with a separate verifier key
Shown onceStripev0.1
Public token ID for lookup and revocationVault accessorsv0.1Can't act as the token
Mandatory expiry, checked at each useOpenBao AppRole lessonv0.1No "never expires" option
Immediate revocation, fail-closed on store errorsInfisical, Doppler lessonsv0.1Staleness limit for long-running services
Rotation with an overlap periodStripe, Infisical, Dopplerv0.1
Exact-match scopesDopplerv0.1No wildcards or patterns
Pluggable token store for servicesOriginalv0.1Interface for a service's own database
Rate limiting and lockoutVault, Infisicalv0.2Left to the host service in v0.1, with guidance. Tokens have 256-bit secrets, so guessing isn't practical
Token hierarchy with cascading revocationVaultv0.2
Stateless signed tokens (PASETO v4)PASETOLaterCan't be revoked without state, so opaque tokens come first
JWT issuanceRFC 8725, RFC 9068Not planned for nowAlgorithm confusion is a known class. Interoperability may justify it later
Macaroons, BiscuitGoogle, BiscuitLaterAttenuation is valuable, but the policy language is large
Response wrappingVaultLater⚠ Needs a server to be meaningful
Sender-constrained tokens1Password Okta lessonLater
GitHub secret scanning partnershipGitHubLaterNeeds a public verification endpoint and project adoption

Password management

FeatureLearned fromTierNotes
Login items: username, password, URLs, notesAllv0.1Stored entirely inside the encrypted item
Password and passphrase generatorBitwarden, KeePassXCv0.1crypto/rand, unbiased, EFF wordlist
TOTP and HOTP codesgopass, Bitwardenv0.1RFC vectors, strict otpauth:// parser. Warns that this reduces 2FA separation, as KeePassXC does
Clipboard with automatic clearingpass, KeePassXCv0.1Default 20 seconds. Clipboard history tools remain a documented limit
Vault password report: reused, weak, oldgopass, KeePassXCv0.1Offline
Breach check by k-anonymityKeePassXC, HIBP APIv0.1Opt-in by flag. No other network use exists in v0.1
Offline breach check fileKeePassXCv0.2
Master passphrase policyNIST SP 800-63B-4v0.115 characters minimum, blocklist, no composition rules
No "zero knowledge" claimETH Zurichv0.1Documentation
Plain export, explicit and auditedAllv0.1Refuses to write to a terminal without a flag
Import from .envSOPS, dotenvxv0.1Fuzzed
Import from Bitwarden, KeePassXC, 1PasswordAllv0.2KeePassXC's 2026 advisories show importers need care. Legacy .kdb isn't planned
AttachmentsBitwarden, KeePassXCv0.2v0.1 limits values to 1 MiB, per Vaultwarden's attachment advisory
Emergency accessBitwardenLater⚠ Needs a server and authenticated public keys. BW01 and BW02 show the danger
Secure sendBitwardenLater⚠ Needs a server
Hardware keys (YubiKey, FIDO2)KeePassXC, passageLater⚠ Needs device libraries and possibly cgo. The per-use touch from passage is valuable
Secret-key style device factor1Passwordv0.1, as key fileThe key file gives the same offline resistance when kept off the synced path
PasskeysKeePassXCLater⚠ Needs browser or OS integration
SSH agentKeePassXCLaterInherits the x/crypto/ssh advisory stream
Browser extension and autofillBitwarden, KeePassXCLater⚠ A separate product. Clickjacking research affected 10 of 11 tested managers (secondary)
Auto-TypeKeePassXCLater⚠ OS-specific GUI work
Desktop and mobile appsBitwarden, KeePassXC, 1PasswordLater⚠ Each one is a separate product
Website iconsBitwarden, LastPassNot plannedThe BW06 and LP03 exfiltration channel
Organisations and SSOBitwarden, 1PasswordLater⚠ Needs a server and identity integrations

Assurance and project practice

ItemLearned fromTierNotes
Published threat model and non-goals1Password, gopass, Vaultv0.1
Published format spec with golden vectorsage, SOPS #2243v0.1
Tests: KAT, tamper, fuzz, race, canaryStandard practice, Vault lessonsv0.1
go vet, staticcheck, gosec, govulncheckProject requirementv0.1
SECURITY.md stating there has been no auditHonest reportingv0.1
Static binaries, no install scriptsBitwarden npm lessonv0.1CGO_ENABLED=0 -trimpath
Build attestations and checksumsKeeLoader, slsa-github-generator deprecationv0.1GitHub attestations, without the unmaintained generator
OpenSSF Scorecard, Best Practices badgeOpenSSFLater
OSS-FuzzOSS-FuzzLaterAcceptance usually depends on adoption
Independent cryptographic reviewBitwarden, KeePassXC, AlmondLater⚠ Needs funding or a volunteer reviewer. It can't be claimed until it has happened, and it matters more than most features
SOC 2, FedRAMP and similarDoppler, 1PasswordNot plannedOrganisational certifications, not applicable to a personal open-source project

Why a server isn't in the first release

A server is the feature that people will most expect, and it is the largest deferral. It should be understood as a deliberate choice.

  1. It is a different attack surface. Almost every serious server incident in the research came from authentication, authorization, policy, plugin or audit-sink code. The file-based design has none of that code. A local file tool can reach a defensible state as a one-person project in a way a multi-tenant server can't.
  2. The scale is large. Vault's public audit alone spent 60 person-days on an existing mature code base, and still found a traversal issue. OpenBao's advisories for code inherited from Vault show how long these classes persist.
  3. A secure local core is a prerequisite. A later server can reuse the format, keys and audit log, and treat the file format as its storage layer. The reverse order doesn't work as well.

Why the OS keyring waits for v0.2

Each current option has a real cost. go-keyring's default macOS path leaves items owned by /usr/bin/security. 99designs/keyring appears dormant. ByteNess/keyring is maintained but pulls in a large dependency tree and cgo on macOS. Cgo conflicts with reproducible builds, and frequently rebuilt unsigned binaries cause repeated keychain prompts. The cost of waiting is that each command asks for the passphrase and spends about the time of one KDF run.

Edit this page on GitHub