hanzio 1.1.0 → 1.2.0

package/src/secrets/deadline.ts

@@ -0,0 +1,69 @@
+import { SecretLoadError } from './errors'
+
+export type SecretRequestOptions = {
+	readonly timeoutMs?: number
+	readonly signal?: AbortSignal
+}
+
+/** One deadline includes authentication, retries, body reads, and validation. */
+export async function withSecretDeadline<T>(
+	options: SecretRequestOptions,
+	operation: (signal: AbortSignal) => Promise<T>
+): Promise<T> {
+	const timeoutMs = options.timeoutMs ?? 30_000
+
+	if (
+		!Number.isFinite(timeoutMs) ||
+		timeoutMs <= 0 ||
+		timeoutMs > 2_147_483_647
+	) {
+		throw new SecretLoadError(
+			'CONFIGURATION',
+			'Secret timeoutMs must be a positive finite timer duration.'
+		)
+	}
+
+	// Normalize caller cancellation so arbitrary abort reasons cannot leak secrets.
+	const controller = new AbortController()
+	const cancel = () =>
+		controller.abort(
+			new SecretLoadError('ABORTED', 'Secret loading was cancelled.')
+		)
+
+	if (options.signal?.aborted) {
+		cancel()
+	} else {
+		options.signal?.addEventListener('abort', cancel, { once: true })
+	}
+
+	const timer = setTimeout(
+		() =>
+			controller.abort(
+				new SecretLoadError(
+					'TIMEOUT',
+					`Secret loading timed out after ${timeoutMs}ms.`
+				)
+			),
+		timeoutMs
+	)
+	let rejectOnAbort: () => void = () => {}
+
+	try {
+		const aborted = new Promise<never>((_, reject) => {
+			rejectOnAbort = () => reject(controller.signal.reason)
+			controller.signal.addEventListener('abort', rejectOnAbort, { once: true })
+		})
+
+		if (controller.signal.aborted) {
+			throw controller.signal.reason
+		}
+
+		// Reject promptly even if a custom loader ignores the abort signal.
+		return await Promise.race([operation(controller.signal), aborted])
+	} finally {
+		// Neither completed loads nor failures should retain listeners or timers.
+		clearTimeout(timer)
+		options.signal?.removeEventListener('abort', cancel)
+		controller.signal.removeEventListener('abort', rejectOnAbort)
+	}
+}

package/src/secrets/environment.ts

@@ -0,0 +1,69 @@
+import { SecretLoadError } from './errors'
+
+export type SecretEnvironment = 'dev' | 'staging' | 'prod'
+
+export type SecretEnvironmentOption =
+	| SecretEnvironment
+	| { readonly slug: string }
+	| (() => SecretEnvironment | { readonly slug: string })
+
+export type EnvironmentVariables = Record<string, string | undefined>
+
+export function getProcessEnvironment(): EnvironmentVariables | undefined {
+	return typeof process === 'undefined' ? undefined : process.env
+}
+
+export function resolveSecretEnvironment(
+	option?: SecretEnvironmentOption,
+	env?: EnvironmentVariables
+): string {
+	// Resolve callbacks once; every reload stays in the same environment.
+	const explicit = typeof option === 'function' ? option() : option
+
+	if (typeof explicit === 'object' && explicit !== null) {
+		if (
+			typeof explicit.slug !== 'string' ||
+			!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(explicit.slug)
+		) {
+			throw new SecretLoadError(
+				'CONFIGURATION',
+				'Custom secret environment requires a valid slug.'
+			)
+		}
+
+		return explicit.slug
+	}
+
+	// Explicit configuration is strict. Typos must not silently select dev.
+	const selected = explicit ?? env?.SECRETS_ENV
+
+	if (selected !== undefined) {
+		if (selected === 'production' || selected === 'prod') {
+			return 'prod'
+		}
+
+		if (selected === 'development' || selected === 'dev') {
+			return 'dev'
+		}
+
+		if (selected === 'staging') {
+			return 'staging'
+		}
+
+		throw new SecretLoadError(
+			'CONFIGURATION',
+			'Invalid secret environment. Use dev, staging, prod, or an explicit { slug } option.'
+		)
+	}
+
+	// NODE_ENV retains the conventional development/test fallback.
+	if (env?.NODE_ENV === 'production' || env?.NODE_ENV === 'prod') {
+		return 'prod'
+	}
+
+	if (env?.NODE_ENV === 'staging') {
+		return 'staging'
+	}
+
+	return 'dev'
+}

package/src/secrets/errors.ts

@@ -0,0 +1,29 @@
+export type SecretErrorCode =
+	| 'CONFIGURATION'
+	| 'AUTHENTICATION'
+	| 'HTTP'
+	| 'CLI'
+	| 'VALIDATION'
+	| 'MISSING_SECRETS'
+	| 'TIMEOUT'
+	| 'ABORTED'
+	| 'LOADER'
+
+/** Contains only safe diagnostic metadata; never attach underlying errors. */
+export class SecretLoadError extends Error {
+	readonly code: SecretErrorCode
+	readonly operation?: string
+	readonly status?: number
+
+	constructor(
+		code: SecretErrorCode,
+		message: string,
+		details: { operation?: string; status?: number } = {}
+	) {
+		super(message)
+		this.name = 'SecretLoadError'
+		this.code = code
+		this.operation = details.operation
+		this.status = details.status
+	}
+}

package/src/secrets/index.ts

@@ -1,225 +1,94 @@
-import { colorize, createCoolLogger } from '../cool-console-log'
-import { DEFAULT_INFISICAL_SITE_URL, loadInfisicalSecrets } from './infisical'
-const logger = createCoolLogger()
-
-export type SecretEnvironment = 'dev' | 'staging' | 'prod'
-export type SecretEnvironmentOption =
-	| SecretEnvironment
-	| (() => SecretEnvironment)
-
-export type InfisicalDefineSecretSetOptions = {
-	readonly projectId: string
-	readonly siteUrl?: string
-	readonly environment?: SecretEnvironmentOption
-	readonly clientIdEnvKey?: string
-	readonly clientSecretEnvKey?: string
-	readonly loader?: undefined
-}
-
-export type CustomLoaderDefineSecretSetOptions<SecretKey extends string> = {
-	readonly loader: SecretSetLoader<SecretKey>
-	readonly environment?: SecretEnvironmentOption
-}
-
-export type DefineSecretSetOptions<SecretKey extends string> =
-	| InfisicalDefineSecretSetOptions
-	| CustomLoaderDefineSecretSetOptions<SecretKey>
-
-export type SecretSetLoaderContext<SecretKey extends string> = {
-	readonly keys: readonly SecretKey[]
-	readonly environment: SecretEnvironment
-}
-
-export type SecretSetLoader<SecretKey extends string> = (
-	context: SecretSetLoaderContext<SecretKey>
-) => Promise<Partial<Record<SecretKey, string>>>
-
-type ResolvedSecretSetOptions<SecretKey extends string> = {
-	readonly loader: SecretSetLoader<SecretKey>
-	readonly environment: SecretEnvironment
-}
-
-export type SecretSet<SecretKey extends string> = {
-	secret: (key: SecretKey) => string
-	secrets: () => Record<SecretKey, string>
-	reload: () => Promise<SecretSet<SecretKey>>
-}
-
+import {
+	defineSecretSet as defineCoreSecretSet,
+	type CommonSecretSetOptions,
+	type CustomLoaderDefineSecretSetOptions,
+	type SecretSet,
+	type SecretSetLoader
+} from './core'
+import {
+	getProcessEnvironment,
+	resolveSecretEnvironment,
+	type SecretEnvironment
+} from './environment'
+import {
+	DEFAULT_INFISICAL_SITE_URL,
+	loadInfisicalSecrets,
+	type InfisicalAuthMode
+} from './infisical'
+import {
+	validateInfisicalOrganizationId,
+	type InfisicalProjectOptions
+} from './infisical-config'
+
+export * from './core'
 export * from './infisical'
 export * from './loaders'
 export * from './vite'
+export type { SecretRequestOptions } from './deadline'
+
+export type InfisicalDefineSecretSetOptions<
+	K extends string = string,
+	Parsed = Record<K, string>
+> = CommonSecretSetOptions<K, Parsed> &
+	InfisicalProjectOptions & {
+		readonly auth?: InfisicalAuthMode
+		readonly clientIdEnvKey?: string
+		readonly clientSecretEnvKey?: string
+		readonly loader?: undefined
+	}
+
+export type DefineSecretSetOptions<
+	K extends string,
+	Parsed = Record<K, string>
+> =
+	| InfisicalDefineSecretSetOptions<K, Parsed>
+	| CustomLoaderDefineSecretSetOptions<K, Parsed>
 
 export function getSecretEnvironment(): SecretEnvironment {
-	const env = process.env.SECRETS_ENV || process.env.NODE_ENV
-	if (env === 'production' || env === 'prod') return 'prod'
-	if (env === 'staging') return 'staging'
-	return 'dev'
+	return resolveSecretEnvironment(
+		undefined,
+		getProcessEnvironment()
+	) as SecretEnvironment
 }
 
 export async function defineSecretSet<
-	const SecretKeys extends readonly string[]
+	const Keys extends readonly string[],
+	Parsed = Record<Keys[number], string>
 >(
-	keys: SecretKeys,
-	options: DefineSecretSetOptions<SecretKeys[number]>
-): Promise<SecretSet<SecretKeys[number]>> {
-	type SecretKey = SecretKeys[number]
-
-	const keySet = [...new Set(keys)] as SecretKey[]
-	const resolvedOptions = resolveSecretSetOptions(options)
-	let cachedSecrets: Record<SecretKey, string> | null = null
-
-	const loadSecrets = async (force = false) => {
-		const nextSecrets = await loadAndMergeSecrets({
-			keySet,
-			cachedSecrets,
-			force,
-			...resolvedOptions
-		})
-		cachedSecrets = nextSecrets
-		return nextSecrets
-	}
-
-	const secretSet = createSecretSet({
-		getCachedSecrets: () => cachedSecrets,
-		reload: loadSecrets
-	})
-
-	await loadSecrets()
-	return secretSet
-}
-
-function resolveSecretSetOptions<SecretKey extends string>(
-	options: DefineSecretSetOptions<SecretKey>
-): ResolvedSecretSetOptions<SecretKey> {
-	const environment = resolveEnvironment(options.environment)
-	const loader: SecretSetLoader<SecretKey> = options.loader
-		? options.loader
-		: (context) =>
-				loadInfisicalSecrets({
-					...context,
-					projectId: options.projectId,
-					siteUrl: options.siteUrl ?? DEFAULT_INFISICAL_SITE_URL,
-					clientIdEnvKey: options.clientIdEnvKey ?? 'INFISICAL_CLIENT_ID',
-					clientSecretEnvKey:
-						options.clientSecretEnvKey ?? 'INFISICAL_CLIENT_SECRET'
-				})
-
-	return {
-		loader,
-		environment
+	keys: Keys,
+	options: DefineSecretSetOptions<Keys[number], Parsed>
+): Promise<SecretSet<Keys[number], Parsed>> {
+	let loader: SecretSetLoader<Keys[number]>
+
+	if (!options.loader) {
+		// Validate even when environment overrides satisfy every key.
+		validateInfisicalOrganizationId(options.organizationId)
+		loader = createDefaultInfisicalLoader(options)
+	} else {
+		loader = options.loader
 	}
-}
 
-async function loadAndMergeSecrets<SecretKey extends string>({
-	keySet,
-	cachedSecrets,
-	loader,
-	environment,
-	force
-}: {
-	readonly keySet: readonly SecretKey[]
-	readonly cachedSecrets: Record<SecretKey, string> | null
-	readonly loader: SecretSetLoader<SecretKey>
-	readonly environment: SecretEnvironment
-	readonly force: boolean
-}): Promise<Record<SecretKey, string>> {
-	const processEnvSecrets = readProcessEnvSecrets(
-		keySet,
-		force ? cachedSecrets : null
+	// Supply process.env only from this Node/Bun entry point, keeping the core portable.
+	return defineCoreSecretSet(
+		keys,
+		{ ...options, loader },
+		getProcessEnvironment()
 	)
-	const keysMissingFromEnv = keySet.filter((key) => !processEnvSecrets[key])
-
-	logSecretEnvironment(environment, keySet.length)
-
-	const loaderKeys = force ? keySet : keysMissingFromEnv
-	const loadedSecrets: Partial<Record<SecretKey, string>> =
-		loaderKeys.length === 0
-			? {}
-			: await loader({
-					keys: loaderKeys,
-					environment
-				})
-
-	const missingKeys = keySet.filter(
-		(key) => !(processEnvSecrets[key] ?? loadedSecrets[key])
-	)
-	if (missingKeys.length > 0) {
-		throw new Error(`Missing secrets: ${missingKeys.join(', ')}`)
-	}
-
-	const nextSecrets = Object.fromEntries(
-		keySet.map((key) => [
-			key,
-			(processEnvSecrets[key] ?? loadedSecrets[key]) as string
-		])
-	) as Record<SecretKey, string>
-
-	for (const [key, value] of Object.entries(nextSecrets)) {
-		process.env[key] = value as string
-	}
-
-	return nextSecrets
-}
-
-function createSecretSet<SecretKey extends string>({
-	getCachedSecrets,
-	reload
-}: {
-	readonly getCachedSecrets: () => Record<SecretKey, string> | null
-	readonly reload: (force?: boolean) => Promise<Record<SecretKey, string>>
-}): SecretSet<SecretKey> {
-	const secretSet: SecretSet<SecretKey> = {
-		secret(key) {
-			const value = getCachedSecrets()?.[key] ?? process.env[key]
-			if (!value) {
-				throw new Error(`Secret ${key} not found`)
-			}
-			return value
-		},
-		secrets() {
-			const cachedSecrets = getCachedSecrets()
-			if (!cachedSecrets) {
-				throw new Error('Secrets not initialized.')
-			}
-			return { ...cachedSecrets }
-		},
-		async reload() {
-			await reload(true)
-			return secretSet
-		}
-	}
-
-	return secretSet
 }
 
-function resolveEnvironment(
-	environment?: SecretEnvironmentOption
-): SecretEnvironment {
-	if (typeof environment === 'function') return environment()
-	return environment ?? getSecretEnvironment()
-}
-
-function logSecretEnvironment(
-	environment: SecretEnvironment,
-	secretCount: number
-): void {
-	logger.info(colorize('Loading secrets', 'cyan', 'bold'), {
-		environment: colorize(environment, 'brightCyan', 'bold'),
-		count: secretCount
-	})
-}
-
-function readProcessEnvSecrets<SecretKey extends string>(
-	keys: readonly SecretKey[],
-	previousSecrets: Record<SecretKey, string> | null = null
-): Partial<Record<SecretKey, string>> {
-	// On forced reloads, skip cached values so the loader can refresh them.
-	return Object.fromEntries(
-		keys
-			.filter((key) => {
-				const value = process.env[key]
-				return value && value !== previousSecrets?.[key]
-			})
-			.map((key) => [key, process.env[key] as string])
-	) as Partial<Record<SecretKey, string>>
+function createDefaultInfisicalLoader<K extends string, Parsed>(
+	options: InfisicalDefineSecretSetOptions<K, Parsed>
+): SecretSetLoader<K> {
+	return (context) =>
+		loadInfisicalSecrets({
+			...context,
+			projectId: options.projectId,
+			organizationId: options.organizationId,
+			siteUrl: options.siteUrl ?? DEFAULT_INFISICAL_SITE_URL,
+			secretPath: options.secretPath,
+			auth: options.auth,
+			clientIdEnvKey: options.clientIdEnvKey ?? 'INFISICAL_CLIENT_ID',
+			clientSecretEnvKey:
+				options.clientSecretEnvKey ?? 'INFISICAL_CLIENT_SECRET'
+		})
 }

package/src/secrets/infisical-cli.ts

@@ -0,0 +1,99 @@
+import type { SecretRequestOptions } from './deadline'
+import { getProcessEnvironment } from './environment'
+import { SecretLoadError } from './errors'
+
+/** Read the active CLI session without a shell or credential-bearing errors. */
+export async function readInfisicalCliToken(
+	options: SecretRequestOptions & { siteUrl: string; signal: AbortSignal }
+): Promise<string> {
+	// Import subprocess support only when the CLI is actually selected.
+	const { execFile } = await import('node:child_process').catch(() => {
+		throw new SecretLoadError(
+			'CLI',
+			'Infisical CLI fallback requires a runtime with subprocess support. Provide Infisical client credentials or a custom secret loader.'
+		)
+	})
+
+	options.signal.throwIfAborted()
+
+	const env: Record<string, string | undefined> = {
+		...getProcessEnvironment(),
+		INFISICAL_DISABLE_UPDATE_CHECK: 'true'
+	}
+
+	// Inherited machine tokens would override the CLI's signed-in user session.
+	// Remove them from the child copy without changing the parent's environment.
+	delete env.INFISICAL_TOKEN
+	delete env.INFISICAL_UNIVERSAL_AUTH_ACCESS_TOKEN
+	delete env.TOKEN
+
+	try {
+		const stdout = await new Promise<string>((resolve, reject) => {
+			const child = execFile(
+				'infisical',
+				[
+					'user',
+					'get',
+					'token',
+					'--plain',
+					`--domain=${options.siteUrl}`,
+					'--silent'
+				],
+				{
+					env,
+					encoding: 'utf8',
+					shell: false,
+					timeout: options.timeoutMs ?? 30_000,
+					signal: options.signal,
+					killSignal: 'SIGKILL',
+					maxBuffer: 10 * 1024 * 1024,
+					windowsHide: true
+				},
+				(error, output) => {
+					if (error) {
+						reject(error)
+					} else {
+						resolve(output)
+					}
+				}
+			)
+
+			// Startup cannot wait for interactive input.
+			child.stdin?.end()
+		})
+		return stdout.trim()
+	} catch (error) {
+		if (options.signal.aborted) {
+			throw options.signal.reason
+		}
+
+		// Subprocess errors can contain secret stdout/stderr, so rebuild the error.
+		const failure = error as { code?: string | number; killed?: boolean } | null
+
+		if (failure?.code === 'ENOENT') {
+			throw new SecretLoadError(
+				'CLI',
+				'Infisical CLI not found. Install infisical and ensure it is on PATH, or provide Infisical client credentials.'
+			)
+		}
+
+		if (failure?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+			throw new SecretLoadError(
+				'CLI',
+				'Infisical CLI output exceeded the 10 MiB limit.'
+			)
+		}
+
+		if (failure?.killed) {
+			throw new SecretLoadError(
+				'TIMEOUT',
+				`Infisical CLI timed out after ${(options.timeoutMs ?? 30_000) / 1000} seconds or was terminated.`
+			)
+		}
+
+		throw new SecretLoadError(
+			'CLI',
+			`Infisical CLI session token failed. Run infisical login --domain=${options.siteUrl} and verify access to the configured organization, project, and environment.`
+		)
+	}
+}

package/src/secrets/infisical-config.ts

@@ -0,0 +1,70 @@
+import type { SecretRequestOptions } from './deadline'
+import { SecretLoadError } from './errors'
+
+/** Project scope shared by the public Infisical loaders. */
+export type InfisicalProjectOptions = {
+	readonly projectId: string
+
+	/** Scope CLI user authentication; machine identities already have an organization. */
+	readonly organizationId: string
+	readonly siteUrl?: string
+	readonly secretPath?: string
+}
+
+export type InfisicalScope<K extends string> = InfisicalProjectOptions &
+	SecretRequestOptions & {
+		readonly keys: readonly K[]
+		readonly environment: string
+		readonly siteUrl: string
+	}
+
+export function validateInfisicalScope(options: InfisicalScope<string>): void {
+	validateInfisicalOrganizationId(options.organizationId)
+
+	let url: URL
+
+	try {
+		url = new URL(options.siteUrl)
+	} catch {
+		throw new SecretLoadError('CONFIGURATION', 'Invalid Infisical siteUrl.')
+	}
+
+	// Keep credentials and other sensitive URL components out of diagnostics.
+	if (
+		!['http:', 'https:'].includes(url.protocol) ||
+		url.username ||
+		url.password ||
+		url.search ||
+		url.hash
+	) {
+		throw new SecretLoadError(
+			'CONFIGURATION',
+			'Infisical siteUrl must be an HTTP(S) URL without credentials, query, or fragment.'
+		)
+	}
+
+	if (
+		!options.projectId.trim() ||
+		!options.environment.trim() ||
+		!(options.secretPath ?? '/').startsWith('/')
+	) {
+		throw new SecretLoadError(
+			'CONFIGURATION',
+			'Infisical requires a projectId, environment, and absolute secretPath.'
+		)
+	}
+}
+
+/** Validate at configuration time, including for JavaScript callers and local-only loads. */
+export function validateInfisicalOrganizationId(organizationId: unknown): void {
+	if (
+		typeof organizationId !== 'string' ||
+		!organizationId.trim() ||
+		/\s/.test(organizationId)
+	) {
+		throw new SecretLoadError(
+			'CONFIGURATION',
+			'Infisical organizationId is required and must be a nonempty ID without whitespace.'
+		)
+	}
+}

package/src/secrets/infisical-session.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+import { SecretLoadError } from './errors'
+
+const sessionClaimsSchema = z.object({
+	organizationId: z.string().optional(),
+	subOrganizationId: z.string().optional(),
+	exp: z.number().finite().optional()
+})
+
+/** Read routing metadata only. JWT signature and permissions are verified by Infisical. */
+export function parseInfisicalSessionToken(token: string): {
+	organizationId?: string
+} {
+	let claims: z.infer<typeof sessionClaimsSchema>
+
+	try {
+		// Reject empty, formatted, or multiline CLI output before making an HTTP request.
+		if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token)) {
+			throw new Error('Invalid token format')
+		}
+
+		const payload = token.split('.')[1]!
+		const json = atob(payload.replace(/-/g, '+').replace(/_/g, '/'))
+
+		claims = sessionClaimsSchema.parse(JSON.parse(json))
+	} catch {
+		throw new SecretLoadError(
+			'AUTHENTICATION',
+			'Infisical returned an invalid user session token. Run infisical login for the configured domain.'
+		)
+	}
+
+	if (claims.exp !== undefined && claims.exp <= Date.now() / 1000) {
+		throw new SecretLoadError(
+			'AUTHENTICATION',
+			'Infisical user session has expired. Run infisical login for the configured domain.'
+		)
+	}
+
+	// For sub-organizations, the root organization claim does not identify the scope.
+	return { organizationId: claims.subOrganizationId ?? claims.organizationId }
+}