# @kody/doppler Reference custom secret provider for Doppler. Provider id: `doppler`. Forkers: replace `@kody/doppler` below with your fork's name. ## Imports ```ts 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`. - `./secretProvider` default export receives `{ action, providerId, ref, canonicalRef, doorSecretName, doorSecretValue, config }`. - `canonicalize` returns `{ canonicalRef }`. Local only, no network. - `resolve` returns `{ value, hosts, canonicalRef }`. Throws instead of returning empty `hosts`. - The door key arrives as `doorSecretValue` from the binding's `door_secret_name`. Never call `secret_get` for it. It is sent only to `https://api.doppler.com` as `Authorization: Bearer`. - Resolve budget: about 7.5s, then a timeout error. ## Ref grammar | Ref | Meaning | Canonical | | --- | --- | --- | | `s/` | Computed value (download endpoint, `format=json`, `secrets=`) | yes | | ``, `s//computed` | Synonyms of the above | maps to `s/` | | `s//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 `/@/-/secret-providers`: ```ts 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.` (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: ```ts 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: ```ts 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) or `dp.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-After` seconds when Doppler sends it. - Error messages include the secret name and HTTP status only. Never the token, a value, or a Doppler response body. - `describe` rejects unknown keys. ## Fork and adapt - Consumer slots look up `package` in 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.id` values, 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.