vaultscribe 0.2.0

Type-safe secrets management and code generation for GCloud Secret Manager.

Vaultscribe

Vaultscribe is a tool for managing secrets. It's intended for solo devs and small teams. It uses Google Cloud Secret Manager to store secrets, and can sync secrets to multiple targets (gcloud run, cloudflare pages, etc). It also generates code so you can access the secrets in your apps.

GCloud Secret Manager offers 6 secrets for free. Vaultscribe bundles up all your secrets, and stores them in a single 'secret slot' - meaning you can practically store as many * secrets as you like.

Installation

uv add --dev vaultscribe

or

pip install vaultscribe

Quickstart

Prerequisites:

• Google Cloud SDK CLI installed, with Secret Manager set up (see below).

Quick Usage

# Scaffold a new project. This will create a vaultscribe.toml file.
vs init       
# Fetch secrets from GCloud Secret Manager for 'prod' environment, store in '.secrets.prod' file. Unset secrets are left blank.
vs pull prod  
# Push secrets from '.secrets.prod' to GCloud Secret Manager for 'prod' environment. Also generates code and syncs secrets to deploy targets.
vs push prod  
# Fetch secrets from GCloud Secret Manager and display
vs show prod  

Vaultscribe Concepts

Vaultscribe uses vaultscribe.toml to describe the secrets it manages. The secret values are NOT stored here. See `example/vaultscribe.toml' for an example file.

Environments

An environment is a collection of secrets that are deployed together. You can define as many environments as you like in your vaultscribe.toml file. For example, you can have a dev environment, a staging environment, and a prod environment.

# define as [envs.YOUR_NAME], for example
[envs.prod]
slot = "example-secrets-prod"

Targets

A target is a service that uses secrets. It has a 'type' for example, GCoud Run, or CloudFlare Pages. A type also has a flavour, for example Python/Pydantic, or Typescript/Vite.

# define as [targets.YOUR_NAME], for example
[targets.my-backend]
type = "gcloud_run"
flavour = "python:pydantic"

Secrets

These are the secrets that are synced from GCloud Secret Manager to the target environments. They cannot be synced to a frontend target like cloudflare_pages, as that would expose them in the browser.

# define as [secrets.YOUR_NAME], for example
[secrets.MY_SECRET_NAME]
sync_targets = ["my-backend"]

Public

These are values that are not actually secret, but are needed for running your application. For example, the URL of your backend API, or the API key for a service like Google Maps. These may be synced to any target.

# define as [public.YOUR_NAME], for example
[public.MY_PUBLIC_VALUE]
sync_targets = ["my-backend", "my-frontend"]

Vaultscribe Shell

When auth'ing to a sensitive service like secret management, you do not want to leave your credentials hanging around longer than you need. Unfortunately, Google Cloud does not offer a way to authenticate for a short period of time. So Vaultscribe offers a way to do your secrets work inside a shell that has a temporary authentication. It does this by getting you to authenticate, but then throwing away the refresh token. This gives you one hour to do your secrets work, then you will need to re-authenticate. The one hour is a Google thing, it cannot be adjusted.

# Start a vaultscribe shell
vs shell

Note that Vaultscribe does not require you to use the shell. You can always just run gcloud auth login and be permanently logged in. The idea of the shell is that you are intentional about doing secrets work - you won't do it accidentally.

Vaultscribe Run

If you want to run a script with all the secrets injected as environment variables, you can use the vs run command.

# Run a script with all the secrets injected as environment variables
vs run dev --target backend -- python your_script.py

GCloud Secrets Manager first time setup

# Enable Secret Manager for your project
gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID

GCloud Secret Manager Quotas

Each secret 'slot' in GCloud Secret Manager has a 64KiB size limit. See here. So while, to paraphrase, "64KiB ought to be enough for anybody", you may hit this limit if you have a very large number of secrets, or if you store really big secrets. If you hit the limit, you probably need a more 'enterprise-y' secrets manager.