hanzio 3.0.0 → 3.1.1

package/src/secrets/infisical-identity-file.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+import type { EnvironmentVariables } from './environment'
+import { SecretLoadError } from './errors'
+
+const identityFileSchema = z.object({
+	clientId: z.string().min(1),
+	clientSecret: z.string().min(1),
+	siteUrl: z.string().url()
+})
+
+/**
+ * Machine identity (Universal Auth) credentials kept in a private file for every
+ * process on this machine, for example by agentgate, which syncs one identity to
+ * all of a user's machines. `INFISICAL_UNIVERSAL_AUTH_FILE` overrides the default
+ * `~/.infisical/universal-auth.json`. Only credentials for `siteUrl`'s instance are
+ * returned, so a secret is never sent to another Infisical instance.
+ */
+export async function readInfisicalIdentityFile(
+	env: EnvironmentVariables | undefined,
+	siteUrl: string
+): Promise<{ clientId: string; clientSecret: string } | undefined> {
+	// Runtimes without a filesystem (browsers, workers) have no identity file.
+	const modules = await Promise.all([
+		import('node:fs/promises'),
+		import('node:os'),
+		import('node:path')
+	]).catch(() => undefined)
+
+	if (!modules) {
+		return undefined
+	}
+
+	const [fs, os, path] = modules
+	const file =
+		env?.INFISICAL_UNIVERSAL_AUTH_FILE ||
+		path.join(os.homedir(), '.infisical', 'universal-auth.json')
+	let text: string
+
+	try {
+		text = await fs.readFile(file, 'utf8')
+	} catch (error) {
+		if ((error as { code?: string }).code === 'ENOENT') {
+			return undefined
+		}
+
+		throw new SecretLoadError(
+			'CONFIGURATION',
+			`The Infisical identity file ${file} could not be read.`
+		)
+	}
+
+	let identity: z.infer<typeof identityFileSchema>
+
+	try {
+		identity = identityFileSchema.parse(JSON.parse(text))
+	} catch {
+		// Never echo the file: it holds a client secret.
+		throw new SecretLoadError(
+			'CONFIGURATION',
+			`The Infisical identity file ${file} is not valid; it needs clientId, clientSecret and siteUrl.`
+		)
+	}
+
+	if (new URL(identity.siteUrl).origin !== new URL(siteUrl).origin) {
+		return undefined
+	}
+
+	return { clientId: identity.clientId, clientSecret: identity.clientSecret }
+}

package/src/secrets/infisical.ts

@@ -5,6 +5,7 @@ import { getProcessEnvironment } from './environment'
 import { SecretLoadError } from './errors'
 import { readInfisicalCliToken } from './infisical-cli'
 import { validateInfisicalScope, type InfisicalScope } from './infisical-config'
+import { readInfisicalIdentityFile } from './infisical-identity-file'
 import { parseInfisicalSessionToken } from './infisical-session'
 
 export const DEFAULT_INFISICAL_SITE_URL = 'https://eu.infisical.com'
@@ -74,14 +75,26 @@ export async function loadInfisicalSecrets<K extends string>(
 	validateInfisicalScope(options)
 
 	const env = getProcessEnvironment()
-	const clientId = env?.[options.clientIdEnvKey]
-	const clientSecret = env?.[options.clientSecretEnvKey]
 	const mode = options.auth ?? 'auto'
 
 	if (!['auto', 'http', 'cli'].includes(mode)) {
 		throw new SecretLoadError('CONFIGURATION', 'Invalid Infisical auth mode.')
 	}
 
+	// Environment credentials win; with neither set, a machine identity file
+	// stands in for them (see readInfisicalIdentityFile).
+	const fromEnv = Boolean(
+		env?.[options.clientIdEnvKey] || env?.[options.clientSecretEnvKey]
+	)
+	const file =
+		mode === 'cli' || fromEnv
+			? undefined
+			: await readInfisicalIdentityFile(env, options.siteUrl)
+	const clientId = fromEnv ? env?.[options.clientIdEnvKey] : file?.clientId
+	const clientSecret = fromEnv
+		? env?.[options.clientSecretEnvKey]
+		: file?.clientSecret
+
 	// Explicit modes take precedence. Auto mode uses HTTP only when both
 	// credentials exist; a failed HTTP request must not switch accounts.
 	const useHttp =
@@ -95,7 +108,9 @@ export async function loadInfisicalSecrets<K extends string>(
 			)
 		}
 
-		options.reportSource?.('Infisical HTTP')
+		options.reportSource?.(
+			file ? 'Infisical HTTP (identity file)' : 'Infisical HTTP'
+		)
 
 		return fetchInfisicalSecrets({ ...options, clientId, clientSecret })
 	}

package/src/string/index.ts

@@ -322,3 +322,62 @@ function safeDecodeURIComponent(value: string): string {
 		return value
 	}
 }
+
+/** Escapes `& < > " '` for HTML or XML text and attribute values. */
+export function escapeHtml(text: string): string {
+	return text
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;')
+}
+
+/**
+ * Pictographs plus the parts that build an emoji sequence: regional indicators
+ * (flags), skin tones, the keycap combiner, the emoji variation selector and
+ * the zero-width joiner. Digits, `#` and `*` also carry the `Emoji` property
+ * but are ordinary text, so they are deliberately not matched.
+ */
+const EMOJI_PATTERN =
+	/[\p{Extended_Pictographic}\u{1F1E6}-\u{1F1FF}\u{1F3FB}-\u{1F3FF}\u{20E3}\u{FE0F}\u{200D}]/gu
+
+/**
+ * Removes emoji and tidies the spacing they leave, so `'Hi there 👋, welcome'`
+ * becomes `'Hi there, welcome'`. Use it for text that is spoken (TTS drops
+ * emoji from the audio but not from the transcript). Text without emoji is
+ * returned unchanged.
+ */
+export function stripEmoji(text: string): string {
+	const stripped = text.replace(EMOJI_PATTERN, '')
+	if (stripped === text) return text
+	return stripped
+		.replace(/ {2,}/g, ' ')
+		.replace(/ +([,.!?;:])/g, '$1')
+		.trim()
+}
+
+/**
+ * Lowercased extension of a file name or path, without the dot. `undefined`
+ * when there is none; like `path.extname`, a leading dot (`.env`) is not one.
+ */
+export function fileExtension(filename: string): string | undefined {
+	const name = filename.slice(
+		Math.max(filename.lastIndexOf('/'), filename.lastIndexOf('\\')) + 1
+	)
+	const dot = name.lastIndexOf('.')
+	if (dot <= 0 || dot === name.length - 1) return undefined
+	return name.slice(dot + 1).toLowerCase()
+}
+
+/**
+ * Normalizes a value the way a JSON round trip does: `undefined` properties
+ * are dropped, `Date`s become ISO strings and `NaN` becomes `null`. Top-level
+ * `undefined` becomes `null`. Use it before storing loosely typed data in a
+ * JSON column. Throws on `bigint` and circular references.
+ */
+export function toJsonValue(value: unknown): JsonValue {
+	if (value === undefined) return null
+	const text = JSON.stringify(value)
+	return text === undefined ? null : (JSON.parse(text) as JsonValue)
+}

package/src/testing/README.md

@@ -0,0 +1,119 @@
+---
+description: bun:test helpers - restorable module mocks, a deep Prisma mock, a minimal window shim, and a race contract for API clients that share logins.
+---
+
+# hanzio/testing
+
+For `bun:test`. The module can be imported outside Bun; `bun:test` is only
+loaded when a helper that needs it runs.
+
+```ts
+import {
+	connectionAuthContract,
+	createPrismaMock,
+	installWindowShim,
+	ModuleMocker,
+	mockCallArg,
+	noopLogger
+} from 'hanzio/testing'
+```
+
+## Restorable module mocks
+
+Bun's `mock.module` replaces a module for the whole test run, and
+`mock.restore()` does not undo it, so a stub in one file leaks into every file
+that runs after it. `ModuleMocker` spreads the real exports under your
+overrides and `clear()` puts the originals back.
+
+```ts
+const moduleMocker = new ModuleMocker()
+await moduleMocker.mock(path.resolve(import.meta.dir, '../lib/posthog.ts'), () => ({
+	captureException: mock()
+}))
+afterAll(() => moduleMocker.clear())
+```
+
+Bun resolves a relative specifier from the file that registers the mock, which
+would be hanzio's. Pass absolute paths or package names, or give the
+constructor a resolver for your own shorthand:
+
+```ts
+const moduleMocker = new ModuleMocker((specifier) =>
+	specifier.startsWith('@/') ? path.resolve(srcDir, specifier.slice(2)) : specifier
+)
+```
+
+## Prisma
+
+`createPrismaMock<Client>(mock)` builds a client where every model method is a
+Bun mock created on first access. Register it in place of the module that
+exports your client, spreading that module's other exports so they keep
+working for every file in the run:
+
+```ts
+import { mock } from 'bun:test'
+import * as prismaClientExports from '@prisma/client'
+import type { prisma } from '../lib/prisma'
+
+export const prismaMock = createPrismaMock<typeof prisma>(mock)
+mock.module(path.resolve(import.meta.dir, '../lib/prisma/index.ts'), () => ({
+	...prismaClientExports,
+	prisma: prismaMock
+}))
+
+beforeEach(() => prismaMock.$reset())
+prismaMock.user.findUnique.mockResolvedValue({ id: 'u1' })
+```
+
+Model and method names are checked against the client type; arguments and
+return values are not.
+
+## Window shim
+
+`installWindowShim(href?)` installs a minimal `window` (`location`,
+`localStorage`, no-op event listeners) for code that only probes for one, and
+returns a reset for `afterEach`. Tests may assign a partial `window`; the shim
+keeps the `location`, `localStorage` and listeners from it, because libraries
+such as axios and PostHog read them at import time. It deliberately installs no
+`document`, which Vue and PrismJS would treat as a full DOM.
+
+```ts
+// test-setup.ts, preloaded through bunfig.toml
+afterEach(installWindowShim())
+```
+
+`createTestStorage()` is the in-memory `Storage` it uses.
+
+## Connection auth contract
+
+`connectionAuthContract` registers the race tests every API client built on
+`ConnectionAuthCache` ([`hanzio/api-wrapper/connection-auth`](../api-wrapper/README.md#sharing-a-login-across-clients))
+must pass, run through the real client and transport: shared refreshes,
+rotated credentials, late 401s, aborted waiters and failed fresh logins.
+
+```ts
+await connectionAuthContract({
+	reset: () => authCache.clear(),
+	create: (fetch, variant) => new ShopApi(credentialsFor(variant), fetch),
+	identityChanges: ['apiKey', 'secret'],
+	isLogin: (url) => url.endsWith('/oauth/token'),
+	loginResponse: (token) => Response.json({ access_token: token, expires_in: 3600 }),
+	readResponse: () => Response.json({ items: [] }),
+	tokenHeader: 'authorization'
+})
+```
+
+`create(fetch, variant)` builds a client. `variant` is one of
+`identityChanges` (must force a new login), `'settings'` (must reuse it),
+`'connection'` (another connection) or `'secret'` (a rotated secret). `read()`
+makes one request and, on a 401, calls `reject` and retries once; `login()`
+forces a fresh login.
+
+## Small helpers
+
+```ts
+const input = mockCallArg<CreateUserInput>(createUser) // call 0, argument 0
+mockCallArg<boolean>(createUser, 1, 1) // call 1, argument 1
+
+runJob({ logger: noopLogger }) // trace…fatal discard; bind/child return itself
+```

package/src/testing/connection-auth-contract.ts

@@ -0,0 +1,303 @@
+// Bun types `clone()` as the undici Response; it is the same runtime object.
+const cloneResponse = (response: Response) => response.clone() as Response
+
+export type ConnectionAuthContractInput = {
+	reset: () => void
+	create: (
+		fetchImpl: typeof fetch,
+		variant?: string
+	) => {
+		read: () => Promise<unknown>
+		login: (options?: { signal?: AbortSignal }) => Promise<string>
+	}
+	identityChanges: string[]
+	isLogin: (url: string) => boolean
+	loginResponse: (token: string) => Response
+	readResponse: () => Response
+	tokenHeader: string
+}
+
+/**
+ * Registers the races every client built on `ConnectionAuthCache`
+ * (`hanzio/api-wrapper/connection-auth`) must survive, run through the real
+ * client and its transport: shared refreshes, rotated credentials, late 401s,
+ * aborted waiters and failed fresh logins. Await it at the top level of a
+ * `bun:test` file.
+ *
+ * - `create(fetch, variant)` builds a client on the given fetch. `variant` is
+ *   one of `identityChanges` (a credential change that must force a new login),
+ *   `'settings'` (a non-auth setting that must reuse the login), `'connection'`
+ *   (another connection) or `'secret'` (a rotated secret).
+ * - `read()` makes one authenticated request; on a 401 it calls `reject` and
+ *   retries once. `login()` forces a fresh login and resolves its token.
+ * - `reset()` clears the cache between tests.
+ * - `tokenHeader` is where requests carry the token; `'authorization'` means
+ *   `Bearer <token>`.
+ *
+ * @example
+ * await connectionAuthContract({
+ *   reset: () => authCache.clear(),
+ *   create: (fetch, variant) => new ShopApi(credentialsFor(variant), fetch),
+ *   identityChanges: ['apiKey', 'secret'],
+ *   isLogin: (url) => url.endsWith('/oauth/token'),
+ *   loginResponse: (token) => Response.json({ access_token: token, expires_in: 3600 }),
+ *   readResponse: () => Response.json({ items: [] }),
+ *   tokenHeader: 'authorization'
+ * })
+ */
+export async function connectionAuthContract(
+	input: ConnectionAuthContractInput
+): Promise<void> {
+	const { beforeEach, describe, expect, test } = await import('bun:test')
+	describe('shared authentication contract', () => {
+		beforeEach(input.reset)
+
+		function provider(
+			respond: (
+				login: boolean,
+				init: RequestInit
+			) => Promise<Response> | Response
+		) {
+			let exchanges = 0
+			const usedTokens: (string | null)[] = []
+			const fetchImpl = (async (url, init) => {
+				const login = input.isLogin(String(url))
+				if (login) exchanges += 1
+				else usedTokens.push(new Headers(init?.headers).get(input.tokenHeader))
+				return respond(login, init ?? {})
+			}) as typeof fetch
+
+			return { fetchImpl, usedTokens, exchanges: () => exchanges }
+		}
+
+		test.each(
+			input.identityChanges
+		)('%s changes authentication identity', async (variant) => {
+			const fake = provider((login) =>
+				login
+					? input.loginResponse(`token-${fake.exchanges()}`)
+					: input.readResponse()
+			)
+			await input.create(fake.fetchImpl).read()
+			await input.create(fake.fetchImpl, variant).read()
+
+			expect(fake.exchanges()).toBe(2)
+			expect(fake.usedTokens[1]).not.toBe(fake.usedTokens[0])
+		})
+
+		test('non-auth settings reuse completed authentication across instances', async () => {
+			const fake = provider((login) =>
+				login ? input.loginResponse('same') : input.readResponse()
+			)
+			await input.create(fake.fetchImpl).read()
+			await input.create(fake.fetchImpl, 'settings').read()
+
+			expect(fake.exchanges()).toBe(1)
+		})
+
+		test('unrelated connections proceed while another login is blocked', async () => {
+			const pending = Promise.withResolvers<Response>()
+			const fake = provider((login) => {
+				if (!login) return input.readResponse()
+				return fake.exchanges() === 1
+					? pending.promise
+					: input.loginResponse('independent')
+			})
+			const blocked = input.create(fake.fetchImpl).read()
+			await input.create(fake.fetchImpl, 'connection').read()
+			expect(fake.exchanges()).toBe(2)
+
+			pending.resolve(input.loginResponse('blocked'))
+			await blocked
+		})
+
+		test('failed shared refresh is evicted and a later attempt recovers', async () => {
+			const pending = Promise.withResolvers<Response>()
+			const fake = provider((login) =>
+				login ? pending.promise.then(cloneResponse) : input.readResponse()
+			)
+			const results = Promise.allSettled(
+				Array.from({ length: 3 }, () => input.create(fake.fetchImpl).read())
+			)
+			pending.reject(new Error('provider unavailable'))
+			expect((await results).map((result) => result.status)).toEqual([
+				'rejected',
+				'rejected',
+				'rejected'
+			])
+			expect(fake.exchanges()).toBe(1)
+
+			const recovered = provider((login) =>
+				login ? input.loginResponse('recovered') : input.readResponse()
+			)
+			await input.create(recovered.fetchImpl).read()
+			expect(recovered.exchanges()).toBe(1)
+		})
+
+		test('simultaneous 401s share one refresh, and a delayed 401 cannot evict it', async () => {
+			const rejected = Array.from({ length: 3 }, () =>
+				Promise.withResolvers<Response>()
+			)
+			const requestsStarted = Promise.withResolvers<void>()
+			const refresh = Promise.withResolvers<Response>()
+			let oldRequests = 0
+			const fake = provider((login, init) => {
+				if (login)
+					return fake.exchanges() === 1
+						? input.loginResponse('A')
+						: refresh.promise.then(cloneResponse)
+				const header = new Headers(init.headers).get(input.tokenHeader)
+				if (
+					header === (input.tokenHeader === 'authorization' ? 'Bearer A' : 'A')
+				) {
+					const response = rejected[oldRequests++]!
+					if (oldRequests === 3) requestsStarted.resolve()
+					return response.promise
+				}
+				return input.readResponse()
+			})
+			await input.create(fake.fetchImpl).login()
+			const reads = Array.from({ length: 3 }, () =>
+				input.create(fake.fetchImpl).read()
+			)
+			await requestsStarted.promise
+
+			rejected[0]!.resolve(new Response('', { status: 401 }))
+			rejected[1]!.resolve(new Response('', { status: 401 }))
+			refresh.resolve(input.loginResponse('B'))
+			await Promise.all(reads.slice(0, 2))
+			rejected[2]!.resolve(new Response('', { status: 401 }))
+			await reads[2]
+
+			expect(fake.exchanges()).toBe(2)
+			expect(fake.usedTokens).toHaveLength(6)
+			expect(fake.usedTokens.slice(3)).toEqual(
+				Array(3).fill(input.tokenHeader === 'authorization' ? 'Bearer B' : 'B')
+			)
+		})
+
+		test('a delayed 401 cannot evict a new generation with identical token bytes', async () => {
+			const rejected = Promise.withResolvers<Response>()
+			const started = Promise.withResolvers<void>()
+			let reads = 0
+			const fake = provider((login) => {
+				if (login) return input.loginResponse('same')
+				reads += 1
+				if (reads === 1) {
+					started.resolve()
+					return rejected.promise
+				}
+				return input.readResponse()
+			})
+			await input.create(fake.fetchImpl).login()
+			const oldRead = input.create(fake.fetchImpl).read()
+			await started.promise
+			await input.create(fake.fetchImpl).login()
+			rejected.resolve(new Response('', { status: 401 }))
+			await oldRead
+
+			expect(fake.exchanges()).toBe(2)
+			expect(reads).toBe(2)
+		})
+
+		test('failed fresh authentication cannot fall back to the previous completed token', async () => {
+			const fake = provider((login) => {
+				if (!login) return input.readResponse()
+				if (fake.exchanges() === 2) throw new Error('credentials rejected')
+				return input.loginResponse('valid')
+			})
+			await input.create(fake.fetchImpl).read()
+			await expect(input.create(fake.fetchImpl).login()).rejects.toThrow(
+				'credentials rejected'
+			)
+			await input.create(fake.fetchImpl).read()
+
+			expect(fake.exchanges()).toBe(3)
+		})
+
+		test('a late old login cannot replace rotated authentication', async () => {
+			const pending = Promise.withResolvers<Response>()
+			const fake = provider((login) => {
+				if (!login) return input.readResponse()
+				return fake.exchanges() === 1
+					? pending.promise
+					: input.loginResponse('new')
+			})
+			const old = input.create(fake.fetchImpl).read()
+			await input.create(fake.fetchImpl, 'secret').read()
+			pending.resolve(input.loginResponse('old'))
+			await old
+			await input.create(fake.fetchImpl, 'secret').read()
+
+			expect(fake.exchanges()).toBe(2)
+			expect(fake.usedTokens.at(-1)).toBe(
+				input.tokenHeader === 'authorization' ? 'Bearer new' : 'new'
+			)
+		})
+
+		test('fresh logins bypass completed tokens and coalesce identical pending checks', async () => {
+			const pending = Promise.withResolvers<Response>()
+			const fake = provider((login) => {
+				if (!login) return input.readResponse()
+				return fake.exchanges() === 1
+					? input.loginResponse('warm')
+					: pending.promise.then(cloneResponse)
+			})
+			await input.create(fake.fetchImpl).read()
+			const checks = Array.from({ length: 3 }, () =>
+				input.create(fake.fetchImpl).login()
+			)
+			expect(fake.exchanges()).toBe(2)
+			pending.resolve(input.loginResponse('fresh'))
+			expect(await Promise.all(checks)).toEqual(['fresh', 'fresh', 'fresh'])
+		})
+
+		test('aborting the initiating waiter leaves the shared refresh running', async () => {
+			const pending = Promise.withResolvers<Response>()
+			const fake = provider((login, init) => {
+				if (!login) return input.readResponse()
+				expect(init.signal).toBeUndefined()
+				return pending.promise
+			})
+			const controller = new AbortController()
+			const cancelled = input
+				.create(fake.fetchImpl)
+				.login({ signal: controller.signal })
+			const survivor = input.create(fake.fetchImpl).read()
+			controller.abort(new Error('wait cancelled'))
+			await expect(cancelled).rejects.toThrow('wait cancelled')
+
+			pending.resolve(input.loginResponse('survived'))
+			await survivor
+			await input.create(fake.fetchImpl).read()
+			expect(fake.exchanges()).toBe(1)
+		})
+
+		test('a pre-aborted waiter starts no exchange', async () => {
+			const fake = provider(() => {
+				throw new Error('unexpected fetch')
+			})
+			const controller = new AbortController()
+			controller.abort(new Error('already cancelled'))
+
+			await expect(
+				input.create(fake.fetchImpl).login({ signal: controller.signal })
+			).rejects.toThrow('already cancelled')
+			expect(fake.exchanges()).toBe(0)
+		})
+
+		test('a second 401 is surfaced without expanding the retry budget', async () => {
+			const fake = provider((login) =>
+				login
+					? input.loginResponse('rejected')
+					: new Response('', { status: 401 })
+			)
+			await expect(input.create(fake.fetchImpl).read()).rejects.toMatchObject({
+				status: 401
+			})
+
+			expect(fake.exchanges()).toBe(2)
+			expect(fake.usedTokens).toHaveLength(2)
+		})
+	})
+}

package/src/testing/helpers.ts

@@ -0,0 +1,41 @@
+type LogMethod = (...args: unknown[]) => void
+
+export type NoopLogger = {
+	trace: LogMethod
+	debug: LogMethod
+	info: LogMethod
+	warn: LogMethod
+	error: LogMethod
+	fatal: LogMethod
+	bind: (...args: unknown[]) => NoopLogger
+	child: (...args: unknown[]) => NoopLogger
+}
+
+const noop: LogMethod = () => {}
+
+/** A logger that discards everything; `bind` and `child` return itself. */
+export const noopLogger: NoopLogger = {
+	trace: noop,
+	debug: noop,
+	info: noop,
+	warn: noop,
+	error: noop,
+	fatal: noop,
+	bind: () => noopLogger,
+	child: () => noopLogger
+}
+
+/**
+ * Reads one argument from a mock's call history as `T`. Bun types
+ * `mock.calls` as `never[]` for loosely typed mocks.
+ *
+ * @example
+ * const input = mockCallArg<CreateUserInput>(createUser) // first call, first argument
+ */
+export function mockCallArg<T>(
+	fn: { mock: { calls: unknown[][] } },
+	callIndex = 0,
+	argIndex = 0
+): T {
+	return fn.mock.calls[callIndex]?.[argIndex] as T
+}

package/src/testing/index.ts

@@ -0,0 +1,12 @@
+export {
+	type ConnectionAuthContractInput,
+	connectionAuthContract
+} from './connection-auth-contract'
+export { mockCallArg, type NoopLogger, noopLogger } from './helpers'
+export { ModuleMocker } from './module-mocker'
+export {
+	createPrismaMock,
+	type DeepMockedPrisma,
+	type PrismaMethodMock
+} from './prisma'
+export { createTestStorage, installWindowShim } from './window'