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

index.ts

102 lines · 4.2 KB · TypeScript
/**
 * Describe the Doppler secret provider: provider id, placeholder grammar,
 * binding config keys, and a bind template you can adapt. Use when setting
 * up or debugging a Doppler binding. It never reads Doppler and never returns
 * secret values (values flow only through the sealed ./secretProvider export).
 *
 * @param input - Optional `{ project?, config?, hosts? }` to tailor the bind template. Unknown keys are rejected.
 * @returns Provider id, ref grammar, config keys, a door-secret setup URL, and a bind template
 *
 * @example
 * import describe from 'kody:@kody/doppler'
 *
 * const overview = await describe({ hosts: ['api.example.com'] })
 */
export default async function describe(input?: unknown) {
	const opts = parseInput(input)
	const config: Record<string, string> = {}
	if (opts.project && opts.config) {
		config.project = opts.project
		config.config = opts.config
	}
	config.hosts = (opts.hosts ?? ['api.example.com']).join(',')

	return {
		providerId: 'doppler',
		sealedExport: './secretProvider',
		placeholder: '{{secret/doppler:s/<SECRET_NAME>}}',
		refs: {
			's/<SECRET_NAME>': 'Computed value (references expanded). Canonical. Synonyms: <SECRET_NAME>, s/<SECRET_NAME>/computed.',
			's/<SECRET_NAME>/raw': 'Raw value as stored (references not expanded). Canonical.',
		},
		configKeys: {
			hosts: 'Required unless every secret has hosts.<NAME>. Comma-separated hostnames the resolved value may be sent to.',
			'hosts.<SECRET_NAME>': 'Optional per-secret host list. Wins over hosts.',
			project: 'Optional Doppler project slug. Set together with config.',
			config: 'Optional Doppler config slug. Set together with project.',
		},
		doorSecret: {
			suggestedName: 'dopplerServiceToken',
			allowedHosts: ['api.doppler.com'],
			setupUrl:
				'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',
		},
		bindTemplate: {
			provider: 'doppler',
			package_id: '<your saved package id for your fork of this package>',
			door_secret_name: 'dopplerServiceToken',
			config,
		},
		notes: [
			'./secretProvider is sealed: only the platform fetch boundary may invoke it.',
			'Use a read-only Doppler service token scoped to one config. Personal and CLI tokens are refused.',
			'The token is only ever sent to api.doppler.com. Resolved values only go to the configured hosts.',
			'Empty hosts fail closed.',
			'One binding serves one provider id. For several configs, fork once per config with a different kody.secretProvider.id.',
		],
	}
}

type DescribeInput = { project?: string; config?: string; hosts?: string[] }

const ALLOWED_KEYS = new Set(['project', 'config', 'hosts'])
const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/
const HOSTNAME_RE =
	/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/

function parseInput(input: unknown): DescribeInput {
	if (input === undefined || input === null) return {}
	if (typeof input !== 'object' || Array.isArray(input)) {
		throw new Error('Expected an optional object { project?, config?, hosts? }.')
	}
	const obj = input as Record<string, unknown>
	for (const key of Object.keys(obj)) {
		if (!ALLOWED_KEYS.has(key)) {
			throw new Error(`Unknown key "${key}". Accepted shape: { project?: string, config?: string, hosts?: string[] }.`)
		}
	}
	const out: DescribeInput = {}
	for (const key of ['project', 'config'] as const) {
		const v = obj[key]
		if (v === undefined) continue
		if (typeof v !== 'string' || !SLUG_RE.test(v)) {
			throw new Error(`"${key}" must be a Doppler slug (letters, digits, dashes, underscores).`)
		}
		out[key] = v
	}
	if (Boolean(out.project) !== Boolean(out.config)) {
		throw new Error('Pass both "project" and "config", or neither.')
	}
	if (obj.hosts !== undefined) {
		if (!Array.isArray(obj.hosts) || obj.hosts.length === 0) {
			throw new Error('"hosts" must be a non-empty array of hostnames.')
		}
		out.hosts = obj.hosts.map((h) => {
			if (typeof h !== 'string' || !HOSTNAME_RE.test(h.trim().toLowerCase())) {
				throw new Error('Each "hosts" entry must be a plain hostname such as api.example.com.')
			}
			return h.trim().toLowerCase()
		})
	}
	return out
}