@kody/doppler
Use Doppler secrets in secret-aware fetch through a read-only service token, without the agent ever seeing the values.
Files
@kody/doppler
Reference custom secret provider for Doppler. Provider id: doppler.
Forkers: replace @kody/doppler below with your fork's name.
Imports
import describe from 'kody:@kody/doppler'Do not import kody:@kody/doppler/secretProvider. It is sealed. Only the
platform fetch boundary calls it.
Contract (modeled on @kentcdodds/onepassword and @noah/bitwarden-secrets)
- Manifest:
kody.secretProvider.id = "doppler"and export./secretProvider. ./secretProviderdefault export receives{ action, providerId, ref, canonicalRef, doorSecretName, doorSecretValue, config }.canonicalizereturns{ canonicalRef }. Local only, no network.resolvereturns{ value, hosts, canonicalRef }. Throws instead of returning emptyhosts.
- The door key arrives as
doorSecretValuefrom the binding'sdoor_secret_name. Never callsecret_getfor it. It is sent only tohttps://api.doppler.comasAuthorization: Bearer. - Resolve budget: about 7.5s, then a timeout error.
Ref grammar
| Ref | Meaning | Canonical |
|---|---|---|
s/<SECRET_NAME> | Computed value (download endpoint, format=json, secrets=<SECRET_NAME>) | yes |
<SECRET_NAME>, s/<SECRET_NAME>/computed | Synonyms of the above | maps to s/<SECRET_NAME> |
s/<SECRET_NAME>/raw | Raw value (GET /v3/configs/config/secret?name=) | yes |
Names: letters, digits, underscores, not starting with a digit. Case is kept as written. Grants key on the canonical ref.
Binding
Door secret prefill (user scope, host api.doppler.com). Send the link; never
ask for the value in chat:
https://kody.codes/connect/secret-set?name=dopplerServiceToken&description=Doppler%20read-only%20service%20token%20(door%20key%20for%20the%20doppler%20secret%20provider)&allowedHosts=api.doppler.com&scope=user
Bind only after the owner confirms the secret is saved. Only the account owner
can bind, usually on /@<slug>/-/secret-providers:
import { kody } from 'kody:runtime'
export default async function main(params) {
return await kody.secretProviderBind({
provider: 'doppler',
package_id: params.packageId, // the owner's fork
door_secret_name: 'dopplerServiceToken',
config: { hosts: 'api.example.com' },
})
}Config keys: hosts (comma-separated hostnames), hosts.<SECRET_NAME>
(per-secret, wins), project + config (optional, both or neither).
Smoke tests
Unit tests (mocked fetch, no Doppler calls): npm test (Node 22+).
Overview, no network:
import describe from 'kody:@kody/doppler'
export default async function main() {
return await describe({ hosts: ['api.example.com'] })
}Live check after bind (needs the owner's own Doppler token and an allowed host that echoes nothing sensitive). Send the placeholder in a header, assert on status only, and never print the response body or value:
export default async function main() {
const res = await fetch('https://api.example.com/health', {
headers: { Authorization: 'Bearer {{secret/doppler:s/EXAMPLE_API_KEY}}' },
})
return { status: res.status }
}Expect "No secret provider is bound" until bind is done, and a grant prompt for saved packages until the ref is allowed.
Edge cases
- Empty
hosts(or only commas) fails closed before any Doppler call. - Host entries must be plain hostnames: no scheme, port, path, or wildcard.
- Tokens must start with
dp.st.(service token) ordp.sa.(service account token). Personal (dp.pt.) and CLI (dp.ct.) tokens are refused. - 401: token revoked or wrong. 403: token scoped to another project/config.
404 or missing key in the download body: secret not in this config.
429: reports
Retry-Afterseconds when Doppler sends it. - Error messages include the secret name and HTTP status only. Never the token, a value, or a Doppler response body.
describerejects unknown keys.
Fork and adapt
- Consumer slots look up
packagein the publishing org, so consumers name their own fork ("kind": "secret-provider", "package": "@their-slug/doppler"). - Several configs: fork per config with distinct
kody.secretProvider.idvalues, or add a ref form naming project and config for a service account token. - Whole-document formats (
env,yaml) send every secret in the config. Add them only as an explicit new ref form.