// Sealed Doppler secret provider for Kody. See the JSDoc on the default export. const DOPPLER_API = 'https://api.doppler.com' const RESOLVE_BUDGET_MS = 7500 /** Doppler secret names: letters, digits, underscores; not starting with a digit. */ const SECRET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,255}$/ /** Exact DNS hostname, lowercase, at least one dot. No scheme, port, path, or wildcard. */ 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])?$/ /** Doppler project and config slugs. */ const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/ /** Token prefixes this provider accepts. Personal and CLI tokens are refused (read/write on the whole account). */ const ACCEPTED_TOKEN_PREFIXES = ['dp.st.', 'dp.sa.'] type SecretProviderInvokeInput = { action: 'canonicalize' | 'resolve' providerId?: string ref: string canonicalRef?: string | null doorSecretName?: string doorSecretValue?: string config?: Record } type Field = 'computed' | 'raw' type ParsedRef = { name: string; field: Field } function fail(message: string): never { throw new Error(message) } /** * Parse a Doppler ref. Accepted forms (one canonical form per meaning): * - `s/` (canonical, computed value) and the synonyms ``, `s//computed` * - `s//raw` (canonical, raw value with references unexpanded) */ function parseRef(raw: unknown): ParsedRef { const ref = typeof raw === 'string' ? raw.trim() : '' if (!ref) fail('Doppler ref is empty. Use s/, for example s/STRIPE_API_KEY.') if (SECRET_NAME_RE.test(ref)) return { name: ref, field: 'computed' } const m = /^s\/([^/]+)(?:\/([^/]+))?$/.exec(ref) if (!m) { fail( 'Unrecognized Doppler ref. Use s/ (computed value) or s//raw (raw value).', ) } const name = m[1]! if (!SECRET_NAME_RE.test(name)) { fail( 'Doppler secret names use letters, digits, and underscores and cannot start with a digit.', ) } const fieldRaw = (m[2] ?? 'computed').toLowerCase() if (fieldRaw !== 'computed' && fieldRaw !== 'raw') { fail('Unknown Doppler ref field. Use s/ or s//raw.') } return { name, field: fieldRaw } } function toCanonicalRef(parsed: ParsedRef): string { return parsed.field === 'raw' ? `s/${parsed.name}/raw` : `s/${parsed.name}` } function parseHostList(raw: string, key: string): string[] { const hosts: string[] = [] for (const part of raw.split(',')) { const host = part.trim().toLowerCase() if (!host) continue if (!HOSTNAME_RE.test(host)) { fail( `Binding config "${key}" has an entry that is not a plain hostname. Use comma-separated hostnames such as api.example.com (no scheme, port, path, or wildcard).`, ) } if (!hosts.includes(host)) hosts.push(host) } return hosts } /** * Host allowlist for one secret: `hosts.` wins over `hosts`. * Empty fails closed so a value is never released without a destination list. */ function hostsFor(config: Record, name: string): string[] { const perSecretKey = `hosts.${name}` const perSecret = config[perSecretKey] if (typeof perSecret === 'string' && perSecret.trim()) { const hosts = parseHostList(perSecret, perSecretKey) if (hosts.length) return hosts } const shared = typeof config.hosts === 'string' ? parseHostList(config.hosts, 'hosts') : [] if (shared.length) return shared fail( `No destination hosts are configured for Doppler secret ${name}. Rebind with config {"hosts":"api.example.com"} or {"hosts.${name}":"api.example.com"}. Empty hosts fail closed.`, ) } /** Optional project/config scoping. Both or neither. */ function projectAndConfig( config: Record, ): { project: string; config: string } | null { const project = typeof config.project === 'string' ? config.project.trim() : '' const cfg = typeof config.config === 'string' ? config.config.trim() : '' if (!project && !cfg) return null if (!project || !cfg) { fail('Binding config must set both "project" and "config", or neither (a service token already implies its config).') } if (!SLUG_RE.test(project) || !SLUG_RE.test(cfg)) { fail('Binding config "project" and "config" must be Doppler slugs (letters, digits, dashes, underscores).') } return { project, config: cfg } } function assertToken(token: string | undefined): string { const value = typeof token === 'string' ? token.trim() : '' if (!value) { fail('The Doppler door secret is empty. Save a Doppler service token as the bound user secret and rebind.') } if (!ACCEPTED_TOKEN_PREFIXES.some((p) => value.startsWith(p))) { fail( 'The Doppler door secret is not a service token or service account token. Use a read-only service token scoped to one config (it starts with dp.st.). Personal and CLI tokens are refused.', ) } return value } function retryAfterSeconds(res: Response): number | null { const header = res.headers.get('retry-after') if (!header) return null const n = Number(header.trim()) return Number.isFinite(n) && n >= 0 ? Math.ceil(n) : null } /** Map a non-OK Doppler response to a clear error. Never includes the token, response body, or any value. */ function dopplerHttpError(res: Response, name: string): Error { const status = res.status switch (status) { case 400: return new Error( `Doppler rejected the request for ${name} (HTTP 400). Check the binding config project/config values and the secret name.`, ) case 401: return new Error( 'Doppler rejected the service token (HTTP 401). It may be revoked, expired, or mistyped. Create a new service token and update the door secret.', ) case 403: return new Error( `Doppler denied access to ${name} (HTTP 403). The service token is scoped to a different project/config, or the binding config points at a config it cannot read.`, ) case 404: return new Error( `Doppler secret ${name} was not found (HTTP 404). Check the secret name and that the token's config contains it.`, ) case 429: { const wait = retryAfterSeconds(res) return new Error( `Doppler rate limit reached (HTTP 429).${wait !== null ? ` Retry after ${wait}s.` : ' Retry later.'} Limits are per token per minute.`, ) } default: if (status >= 500) { return new Error(`Doppler API is unavailable (HTTP ${status}). Retry later.`) } return new Error(`Doppler API request for ${name} failed (HTTP ${status}).`) } } async function dopplerGet(url: URL, token: string, signal: AbortSignal): Promise { try { return await fetch(url.toString(), { method: 'GET', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' }, signal, }) } catch (err) { if (err instanceof Error && err.name === 'AbortError') throw err // Do not forward the underlying message; it can carry request details. fail('Could not reach api.doppler.com. Retry later.') } } async function readJson(res: Response): Promise { try { return await res.json() } catch { fail('Doppler returned a response that is not JSON.') } } /** Computed value through the download endpoint, limited to one secret. */ async function fetchComputed( name: string, token: string, scope: { project: string; config: string } | null, signal: AbortSignal, ): Promise { const url = new URL('/v3/configs/config/secrets/download', DOPPLER_API) if (scope) { url.searchParams.set('project', scope.project) url.searchParams.set('config', scope.config) } url.searchParams.set('format', 'json') url.searchParams.set('secrets', name) const res = await dopplerGet(url, token, signal) if (!res.ok) throw dopplerHttpError(res, name) const body = await readJson(res) if (!body || typeof body !== 'object' || Array.isArray(body)) { fail('Doppler download returned an unexpected body shape.') } const value = (body as Record)[name] if (value === undefined) { fail(`Doppler secret ${name} was not found in the token's config.`) } if (typeof value !== 'string') { fail(`Doppler secret ${name} did not download as a string.`) } return value } /** Raw value through the single-secret endpoint. */ async function fetchRaw( name: string, token: string, scope: { project: string; config: string } | null, signal: AbortSignal, ): Promise { const url = new URL('/v3/configs/config/secret', DOPPLER_API) if (scope) { url.searchParams.set('project', scope.project) url.searchParams.set('config', scope.config) } url.searchParams.set('name', name) const res = await dopplerGet(url, token, signal) if (!res.ok) throw dopplerHttpError(res, name) const body = (await readJson(res)) as { value?: { raw?: unknown } } | null const raw = body && typeof body === 'object' ? body.value?.raw : undefined if (typeof raw !== 'string') { fail(`Doppler secret ${name} has no readable raw value (it may be restricted).`) } return raw } /** * Sealed Doppler secret provider handler for Kody secret-aware fetch. * The platform fetch boundary calls it with action "canonicalize" (map a ref * to its grant key, no network) or "resolve" (read one secret value from * Doppler with the bound service token). Ordinary execute or kody:@ imports * of this export are refused by the platform. Use placeholders instead. * * @param input - action, ref, canonicalRef, door secret name/value, and the non-secret binding config (hosts, optional project/config) * @returns For canonicalize, `{ canonicalRef }`. For resolve, `{ value, hosts, canonicalRef }`. * * @example * // Not callable from execute. Reference a Doppler secret in a fetch instead: * // headers: { Authorization: 'Bearer {{secret/doppler:s/}}' } */ export default async function secretProvider( input: SecretProviderInvokeInput, ): Promise<{ canonicalRef: string } | { value: string; hosts: string[]; canonicalRef: string }> { const action = input?.action if (action !== 'canonicalize' && action !== 'resolve') { fail(`Unknown secret provider action "${String(action)}". Expected "canonicalize" or "resolve".`) } const parsed = parseRef(input.canonicalRef || input.ref) const canonicalRef = toCanonicalRef(parsed) if (action === 'canonicalize') return { canonicalRef } const token = assertToken(input.doorSecretValue) const config = input.config ?? {} const hosts = hostsFor(config, parsed.name) const scope = projectAndConfig(config) const controller = new AbortController() const timer = setTimeout(() => controller.abort(), RESOLVE_BUDGET_MS) try { const value = parsed.field === 'raw' ? await fetchRaw(parsed.name, token, scope, controller.signal) : await fetchComputed(parsed.name, token, scope, controller.signal) if (value.length === 0) fail(`Doppler secret ${parsed.name} is empty.`) return { value, hosts, canonicalRef } } catch (err) { if (err instanceof Error && err.name === 'AbortError') { fail('Doppler resolve timed out. Check api.doppler.com reachability and retry.') } throw err } finally { clearTimeout(timer) } }