Credentials#

Declare credential paths in credentials/schema.zon:

.{
    .stripe = .{
        .publishable_key = .public,
        .secret_key = .private,
    },
}

Every value is a string and is encrypted at rest. .public credentials may be used in views; .private credentials are available only to Zig code. Use .optional_private for a private credential which may be absent from profiles where its integration is inactive; its generated Zig field has type ?[]const u8.

Set and unset values#

# Pass a non-secret value directly.
zyn credentials set stripe.publishable_key pk_test_123 -p development

# Omit the value to type a secret with bullet masking, then press Enter.
zyn credentials set stripe.secret_key -p development

# Remove a value from this profile.
zyn credentials unset stripe.secret_key -p development

set adds a new path to the schema as .private. unset removes only the profile value, leaving the schema unchanged. Run zyn credentials schema to list declared paths and zyn credentials edit -p development to edit the whole profile.

Use credentials#

const secret_key = zyn.credentials.stripe.secret_key;

Views receive only public credentials:

@credentials['stripe']['publishable_key']

zyn dev and zyn serve use the development profile; zyn test uses test. Other servers select a profile with ZYN_ENV. Environment variables can override values by uppercasing the path, for example STRIPE_SECRET_KEY.

Commit encrypted credentials/PROFILE.zon.enc and credentials/PROFILE.data-keys.zon.enc files, but do not commit their .key files. credentials/test.key is the exception so tests are reproducible. Changing values requires an application restart; changing the schema requires a rebuild.

Profile files and command inputs#

Profiles contain credentials/PROFILE.zon.enc, the private PROFILE.key, and PROFILE.data-keys.zon.enc. Profile loading and master rotation require a valid data-key file. Rotation rewraps the unchanged database key; it neither scans nor deletes database data. See Credentials command for rotation precautions and examples.

Profile names are limited to 237 bytes. schema is reserved: a profile created with that name by an earlier release must be recreated under another name using that release; renaming encrypted files is not sufficient. Creating an additional profile does not update build.zig.zon. Add its exact encrypted profile and data-key paths when it must enter a Zig package; do not package private keys.

Profile options may precede the operation or follow its operands. get, set, and unset require the path immediately after the operation; rotate requires master. Positional profile names are not accepted. --no-input cannot replace an operand. A missing value on terminal stdin fails rather than prompting in that mode; an empty redirected stream fails as an invalid value.

Terminal input submits one line without its line ending. Redirected input reads through EOF and removes one trailing LF or CRLF. Explicit arguments and editor values are not trimmed. Editor commands may include arguments; the temporary file path is appended last. Unchanged saves ignore formatting, comments, and field order but preserve whitespace within values.

New credential paths that conflict with an existing leaf or container are rejected. Schema and profile changes commit together; the next credential or schema read completes an interrupted update before using either file. schema reads declarations without a profile key or decryption, although it may first complete such recovery. Invalid or missing schemas fail with diagnostics on stderr and no stdout. An empty schema prints No credential paths declared.