Reference syntax

sec://<provider>/<path>[#field]

Part	Meaning
`provider`	Which vault to ask. An alias, not a fixed type — see multiple accounts
`path`	The secret’s identifier within that vault
`field`	Optional. Extracts one key from a JSON secret

The field selector

Most vaults store structured secrets. Given prod/db holding:

{ "user": "app_prod", "password": "S3cur3-P@ss" }

sec://aws/prod/db#password returns only S3cur3-P@ss. Omit the #field and you get the whole JSON string. Nested fields use dot notation: sec://aws/prod/db#creds.primary.password.

Where references can go

Anywhere a string lives:

.env

DB_PASSWORD=sec://aws/prod/db#password

const key = await secRefs.expandString("sec://vault/kv/stripe#key");

// A plain value passes through untouched, so you can migrate gradually.
await secRefs.expandString("not-a-reference"); // -> "not-a-reference"

That last property matters more than it looks: you can accept both forms at the same call site and move consumers over one at a time, rather than needing a flag day.

Strict mode

By default, a reference that cannot be resolved throws. It does not silently become undefined and let your app boot half-configured, which is how a missing secret turns into a confusing failure three layers away.

const secRefs = new SecRefs({ strict: false }); // leave unresolvable refs in place

Strict mode only affects malformed references. An unknown provider or a failed fetch always surfaces as an error regardless.

Getting started

Providers

Guides

Reference

Reference syntax

The field selector

Where references can go

Strict mode

​The field selector

​Where references can go

​Strict mode

The field selector

Where references can go

Strict mode