goraz

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0

README

goraz: encrypted secrets, API tokens and passwords for Go

CI Go Reference

goraz is a Go library and command-line tool that keeps API tokens, secrets and passwords in an encrypted file. It needs no server. Each production service gets its own file holding only what it needs.

goraz 0.1 is an early release and has not had an independent security audit. Don't make it the only protection for highly sensitive credentials. Read what it does not defend against.

The official source is github.com/mtnaskari/goraz. The github.com/goraz organization is an unrelated project.

Install

Requires Go 1.26.11 or later, on macOS or Linux.

go install github.com/mtnaskari/goraz/cmd/goraz@latest

Prebuilt binaries with checksums and build attestations are on the releases page.

Quick start

goraz init
goraz put prod/db/password
goraz run --env DB_PASSWORD=goraz://prod/db/password -- ./my-app

Find what you need

I want to Guide
Store API tokens in a production Go service Guide
Use secrets in Docker, Kubernetes, systemd or CI Follow the link for each
See a complete service: Postgres, rotating JWT keys, a webhook and a Telegram bot in Docker Compose goraz-example
Issue and verify API tokens from my own Go API Guide
Replace a .env file Guide
Manage passwords and TOTP codes in the terminal Guide
Respond to a leaked secret or key Guide
Fix an error Troubleshooting
Compare it with Vault, OpenBao, SOPS or gopass Comparison

The documentation site has everything, including the command reference, limits, threat model and file format. What changed in each release is in the changelog.

Read a token in a Go service

Create a file holding only this service's items:

goraz service create api --prefix prod/api --out api.goraz --key-out api.key

Deploy the two files separately, then:

c, err := service.Open(ctx, service.Options{
	Path:  "/etc/goraz/api.goraz",
	Key:   service.KeyFile("/run/secrets/goraz-key"),
	Audit: audit.NewJSONSink(os.Stdout),
})
if err != nil {
	return err
}
defer c.Close()

stripeKey, err := c.Value("prod/api/stripe")

The client picks up new files with no restart, refuses tampered or older ones, and fails closed when its data is stale.

Issue API tokens from your own service

m, err := token.New(token.Config{Keys: keys, Store: myDatabaseStore, Sink: audit.NewJSONSink(os.Stdout)})

tok, rec, err := m.Issue(ctx, token.IssueRequest{Name: "billing", Scopes: []string{"payments:read"}, TTL: time.Hour})

rec, err = m.Verify(ctx, presented, "payments:read")

Only a keyed hash is stored. Every token expires, and it can be revoked or rotated with an overlap.

What's different

  • All metadata is encrypted. Names, usernames and URLs aren't visible in the file.
  • Tampering is detected. Changed, swapped, removed or older data is refused. Older-file detection has documented limits.
  • Per-service limits come from encryption. A service's file doesn't contain anyone else's secrets.
  • Secrets stay off the command line. They're never read from arguments or environment variables.
  • Audit by default. A read fails if it can't be logged, and the log holds no names or values.
  • Few dependencies. Only Go's standard library and golang.org/x modules.

When to use something else

goraz has no server, policies, dynamic credentials, team sharing, sync or browser extension. If you need central control or instant revocation across many servers, OpenBao or Vault fits better. An attacker who controls a running service gets everything that service can read, with goraz or any other local tool. See the full comparison and the feature matrix.

Cryptography

Argon2id, HKDF-SHA-256 and XChaCha20-Poly1305, from Go's standard library and golang.org/x/crypto, as one fixed suite. The file format is published. Its key-commitment composition follows Albertini et al. (2022), and it hasn't been independently reviewed. Review is very welcome: see SECURITY.md.

The name

Goraz evokes the Persian word for wild boar, and combines "Go" with the Persian word raz, meaning secret.

Author

goraz is written and maintained by Matin Askari (@mtnaskari).

License

Copyright 2026 Matin Askari. Licensed under Apache-2.0. The embedded word list is from the Electronic Frontier Foundation, under CC BY 3.0 US.

Directories

Path Synopsis
Package audit records what goraz did without recording any secret.
Package audit records what goraz did without recording any secret.
cmd
goraz command
Command goraz is a local secrets tool.
Command goraz is a local secrets tool.
internal
envelope
Package envelope implements the sealed envelope in docs/security-design.md, section 4.
Package envelope implements the sealed envelope in docs/security-design.md, section 4.
format
Package format parses and writes the v1 header.
Package format parses and writes the v1 header.
fsutil
Package fsutil holds the only code that opens goraz's own files.
Package fsutil holds the only code that opens goraz's own files.
harden
Package harden applies best-effort process and memory protections.
Package harden applies best-effort process and memory protections.
kdf
Package kdf derives unlock keys.
Package kdf derives unlock keys.
names
Package names is the single place item names are validated.
Package names is the single place item names are validated.
projecttest
Package projecttest holds tests that check the module as a whole: its dependencies, its public API and its documentation.
Package projecttest holds tests that check the module as a whole: its dependencies, its public API and its documentation.
state
Package state implements local rollback and fork detection, per docs/security-design.md, section 7.
Package state implements local rollback and fork detection, per docs/security-design.md, section 7.
tokfmt
Package tokfmt encodes and strictly parses token strings and recovery codes.
Package tokfmt encodes and strictly parses token strings and recovery codes.
Package password generates passwords and passphrases, enforces the master passphrase policy, and produces one-time codes.
Package password generates passwords and passphrases, enforces the master passphrase policy, and produces one-time codes.
hibp
Package hibp checks passwords against the Have I Been Pwned range API by k-anonymity.
Package hibp checks passwords against the Have I Been Pwned range API by k-anonymity.
Package secret provides a byte-slice wrapper that refuses to reveal its contents through formatting or encoding.
Package secret provides a byte-slice wrapper that refuses to reveal its contents through formatting or encoding.
Package service lets a production service read its secrets and verify its tokens without a person present.
Package service lets a production service read its secrets and verify its tokens without a person present.
Package token issues and verifies opaque bearer tokens.
Package token issues and verifies opaque bearer tokens.
Package vault implements the encrypted store.
Package vault implements the encrypted store.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL