Skip to content
← Public packages

@kody/doppler

Use Doppler secrets in secret-aware fetch through a read-only service token, without the agent ever seeing the values.

FollowFork

Files

AGENTS.md

115 lines · 4.3 KB · Markdown

@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.
  • ./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

RefMeaningCanonical
s/<SECRET_NAME>Computed value (download endpoint, format=json, secrets=<SECRET_NAME>)yes
<SECRET_NAME>, s/<SECRET_NAME>/computedSynonyms of the abovemaps to s/<SECRET_NAME>
s/<SECRET_NAME>/rawRaw 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) 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.