@gajae-code/ai 0.13.2 → 0.14.0

package/src/utils/json-parse.ts

@@ -110,6 +110,86 @@ export function repairJson(json: string): string {
 	return parts.join("");
 }
 
+/**
+ * First unnecessary `\uXXXX` escape in a JSON document, or `undefined` when the
+ * document contains none.
+ *
+ * "Unnecessary" means the escape encodes a character JSON can carry literally:
+ * any non-ASCII printable character. Control characters (< U+0020) MUST be
+ * escaped, and an unpaired surrogate CANNOT be written literally, so neither
+ * counts. A `\\uXXXX` sequence is a literal backslash followed by `u` — the
+ * intended source syntax when the model is writing code or a nested JSON
+ * document — and is skipped, which is why this scans the raw text with the same
+ * string/escape state machine as {@link repairJson} instead of using a regex.
+ *
+ * Models that spell non-ASCII text as hand-written hex instead of literal UTF-8
+ * mistype the digits, and every mistyped nibble silently decodes to a different
+ * but perfectly valid character (`\uc7a5` vs `\uc7a4`). The resulting arguments
+ * parse cleanly and cannot be repaired after the fact, so the escape itself is
+ * the only observable evidence that the payload is untrustworthy.
+ */
+export function findUnnecessaryUnicodeEscape(json: string): string | undefined {
+	const len = json.length;
+	let inString = false;
+	let i = 0;
+
+	const hexAt = (start: number): number | undefined => {
+		if (start + 3 >= len) return undefined;
+		for (let k = start; k <= start + 3; k++) if (!isHexDigit(json.charCodeAt(k))) return undefined;
+		return Number.parseInt(json.slice(start, start + 4), 16);
+	};
+
+	while (i < len) {
+		if (!inString) {
+			const open = json.indexOf('"', i);
+			if (open === -1) return undefined;
+			inString = true;
+			i = open + 1;
+			continue;
+		}
+
+		// Jump straight to the next quote or backslash. A per-character walk costs
+		// ~40ms on a 1MB literal-UTF-8 payload (a large `write`), and every byte in
+		// between is by definition uninteresting.
+		const nextQuote = json.indexOf('"', i);
+		const nextBackslash = json.indexOf("\\", i);
+		if (nextQuote === -1 && nextBackslash === -1) return undefined;
+		i = nextBackslash === -1 || (nextQuote !== -1 && nextQuote < nextBackslash) ? nextQuote : nextBackslash;
+
+		if (json.charCodeAt(i) === QUOTE) {
+			inString = false;
+			i++;
+			continue;
+		}
+		if (json.charCodeAt(i + 1) !== U) {
+			// Any other escape (including `\\`) consumes its own second character,
+			// so a literal `\uXXXX` in the decoded value is never misread as one.
+			i += 2;
+			continue;
+		}
+
+		const first = hexAt(i + 2);
+		if (first === undefined) {
+			i += 2;
+			continue;
+		}
+		if (first >= 0xd800 && first <= 0xdbff) {
+			// High surrogate: only a completed pair denotes a real character.
+			const low = json.charCodeAt(i + 6) === BACKSLASH && json.charCodeAt(i + 7) === U ? hexAt(i + 8) : undefined;
+			if (low !== undefined && low >= 0xdc00 && low <= 0xdfff) {
+				return json.slice(i, i + 12);
+			}
+			i += 6;
+			continue;
+		}
+		if (first >= 0x80 && !(first >= 0xdc00 && first <= 0xdfff)) {
+			return json.slice(i, i + 6);
+		}
+		i += 6;
+	}
+	return undefined;
+}
+
 export function parseJsonWithRepair<T>(json: string): T {
 	try {
 		return JSON.parse(json) as T;

package/src/utils/oauth/callback-server.ts

@@ -36,6 +36,17 @@ export interface OAuthCallbackFlowOptions {
 	 * `onManualCodeInput` handler on the controller.
 	 */
 	skipCallbackServer?: boolean;
+	/**
+	 * Expected authorization-server issuer recorded from validated metadata
+	 * (RFC 9207 / MCP 2026-07-28). When set, a present `iss` that differs
+	 * rejects the response before any other parameter is acted on.
+	 */
+	expectedIssuer?: string;
+	/**
+	 * `authorization_response_iss_parameter_supported` from the same metadata.
+	 * When true, a response WITHOUT `iss` is rejected.
+	 */
+	issuerResponseIssSupported?: boolean;
 }
 
 /**
@@ -48,6 +59,8 @@ export abstract class OAuthCallbackFlow {
 	callbackHostname: string;
 	callbackBindHostname: string;
 	redirectUri?: string;
+	expectedIssuer?: string;
+	issuerResponseIssSupported?: boolean;
 	readonly #skipCallbackServer: boolean;
 	#callbackResolve?: (result: CallbackResult) => void;
 	#callbackReject?: (error: string) => void;
@@ -72,6 +85,8 @@ export abstract class OAuthCallbackFlow {
 		this.callbackHostname = preferredPortOrOptions.callbackHostname ?? DEFAULT_HOSTNAME;
 		this.callbackBindHostname = preferredPortOrOptions.callbackBindHostname ?? this.callbackHostname;
 		this.redirectUri = preferredPortOrOptions.redirectUri;
+		this.expectedIssuer = preferredPortOrOptions.expectedIssuer;
+		this.issuerResponseIssSupported = preferredPortOrOptions.issuerResponseIssSupported;
 		this.#skipCallbackServer = preferredPortOrOptions.skipCallbackServer === true;
 	}
 
@@ -202,12 +217,27 @@ export abstract class OAuthCallbackFlow {
 		const state = url.searchParams.get("state") || "";
 		const error = url.searchParams.get("error") || "";
 		const errorDescription = url.searchParams.get("error_description") || error;
+		const iss = url.searchParams.get("iss");
 
 		type OkState = { ok: true; code: string; state: string };
 		type ErrorState = { ok?: false; error?: string };
 		let resultState: OkState | ErrorState;
 
-		if (error) {
+		// RFC 9207 §2.4 (MCP 2026-07-28): validate the response issuer before acting
+		// on any other parameter; on mismatch, server-supplied error details must not
+		// be acted on or displayed, so the failure message is generic by design.
+		let issuerFailure: string | null = null;
+		if (this.expectedIssuer) {
+			if (iss !== null && iss !== this.expectedIssuer) {
+				issuerFailure = "Authorization response issuer mismatch";
+			} else if (iss === null && this.issuerResponseIssSupported === true) {
+				issuerFailure = "Authorization response missing required issuer (iss)";
+			}
+		}
+
+		if (issuerFailure) {
+			resultState = { ok: false, error: issuerFailure };
+		} else if (error) {
 			resultState = { ok: false, error: `Authorization failed: ${errorDescription}` };
 		} else if (!code) {
 			resultState = { ok: false, error: "Missing authorization code" };

package/src/utils/oauth/index.ts

@@ -275,6 +275,11 @@ const builtInOAuthProviders: OAuthProviderInfo[] = [
 		name: "Vercel AI Gateway",
 		available: true,
 	},
+	{
+		id: "kiro",
+		name: "Kiro (Amazon Q Developer / CodeWhisperer)",
+		available: true,
+	},
 ];
 
 const customOAuthProviders = new Map<string, OAuthProviderInterface>();
@@ -375,6 +380,11 @@ export async function refreshOAuthToken(
 			newCredentials = await refreshGlmZcodeToken(credentials);
 			break;
 		}
+		case "kiro": {
+			const { refreshKiroToken } = await import("./kiro");
+			newCredentials = await refreshKiroToken(credentials);
+			break;
+		}
 		case "kilo":
 		case "perplexity":
 		case "huggingface":
@@ -487,7 +497,10 @@ export async function getOAuthApiKey(
 	}
 	// For providers that need request-time credential metadata, return JSON.
 	const needsStructuredApiKey =
-		provider === "github-copilot" || provider === "google-gemini-cli" || provider === "google-antigravity";
+		provider === "github-copilot" ||
+		provider === "google-gemini-cli" ||
+		provider === "google-antigravity" ||
+		provider === "kiro";
 	const apiKey = needsStructuredApiKey
 		? JSON.stringify({
 				token: creds.access,

package/src/utils/oauth/kiro.ts

@@ -0,0 +1,448 @@
+/**
+ * Kiro (Amazon Q Developer / CodeWhisperer) OAuth flow via AWS SSO OIDC.
+ *
+ * Implements the device-code authorization flow and token refresh using the
+ * published AWS SSO OIDC service model (botocore sso-oidc/2019-06-10).
+ *
+ * Clean-room: derived from the published Amazon SSO OIDC service model shapes
+ * and AWS public documentation, not from any third-party reference.
+ */
+import { scheduler } from "node:timers/promises";
+import type { OAuthCredentials } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Published SSO OIDC endpoints and constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Builder ID start URL for device authorization. */
+const BUILDER_ID_START_URL = "https://view.awsapps.com/start";
+
+/** Default AWS region for SSO OIDC. */
+const DEFAULT_REGION = "us-east-1";
+
+/** Client registration metadata for the Gajae Code application. */
+const CLIENT_NAME = "gajae-code";
+const CLIENT_TYPE = "public";
+
+/**
+ * Scopes requested for CodeWhisperer / Amazon Q access. These are the published
+ * scopes from the AWS SSO OIDC model for the CodeWhisperer service.
+ */
+const CODEWHISPERER_SCOPES = [
+	"codewhisperer:completions",
+	"codewhisperer:analysis",
+	"codewhisperer:conversations",
+	"codewhisperer:transformations",
+	"codewhisperer:taskassist",
+	"sso:account:access",
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Wire types (matching published SSO OIDC service model)
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RegisterClientResponse {
+	clientId: string;
+	clientSecret: string;
+	clientIdIssuedAt: number;
+	clientSecretExpiresAt: number;
+	authorizationEndpoint?: string;
+	tokenEndpoint?: string;
+}
+
+interface StartDeviceAuthorizationResponse {
+	deviceCode: string;
+	userCode: string;
+	verificationUri: string;
+	verificationUriComplete?: string;
+	interval: number;
+	expiresIn: number;
+}
+
+interface CreateTokenSuccess {
+	accessToken: string;
+	tokenType: string;
+	expiresIn: number;
+	refreshToken?: string;
+}
+
+interface CreateTokenError {
+	error: string;
+	error_description?: string;
+	error_uri?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Typed SSO OIDC error names from the published service model
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SSO_OIDC_FATAL_ERRORS = new Set([
+	"access_denied_exception",
+	"expired_token_exception",
+	"internal_server_exception",
+	"invalid_client_exception",
+	"invalid_client_metadata_exception",
+	"invalid_grant_exception",
+	"invalid_redirect_uri_exception",
+	"invalid_request_exception",
+	"invalid_request_region_exception",
+	"invalid_scope_exception",
+	"unauthorized_client_exception",
+	"unsupported_grant_type_exception",
+]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Registration cache (client registration is reusable until expiry)
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ClientRegistration {
+	clientId: string;
+	clientSecret: string;
+	expiresAt: number; // epoch ms
+}
+
+let cachedRegistration: ClientRegistration | undefined;
+
+/**
+ * Register a public SSO OIDC client. Registration responses include an expiry
+ * timestamp (`clientSecretExpiresAt`); we cache until then to avoid re-registering
+ * on every login attempt.
+ *
+ * The SSO OIDC `RegisterClient` endpoint is public (no authentication required).
+ */
+export async function registerClient(
+	region: string,
+	startUrl: string,
+	signal?: AbortSignal,
+): Promise<ClientRegistration> {
+	if (cachedRegistration && Date.now() < cachedRegistration.expiresAt - 60_000) {
+		return cachedRegistration;
+	}
+
+	const url = ssoOidcEndpoint(region, "/client/register");
+	const body = {
+		clientName: CLIENT_NAME,
+		clientType: CLIENT_TYPE,
+		scopes: CODEWHISPERER_SCOPES,
+		grantTypes: ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"],
+		redirectUris: [],
+		issuerUrl: startUrl,
+	};
+
+	const response = await fetchOidc(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+		signal,
+	});
+
+	const data = (await response.json()) as RegisterClientResponse;
+	if (!data.clientId || !data.clientSecret) {
+		throw new Error("SSO OIDC RegisterClient: missing clientId or clientSecret");
+	}
+
+	cachedRegistration = {
+		clientId: data.clientId,
+		clientSecret: data.clientSecret,
+		// `clientSecretExpiresAt` is epoch seconds in the published model
+		expiresAt: data.clientSecretExpiresAt * 1000,
+	};
+	return cachedRegistration;
+}
+
+/** Drop cached client registration — used by tests. */
+export function clearClientRegistrationCache(): void {
+	cachedRegistration = undefined;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Device authorization flow
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Start device authorization. The SSO OIDC `StartDeviceAuthorization` endpoint
+ * is public (requires registered clientId/clientSecret, not SigV4).
+ */
+export async function startDeviceAuthorization(
+	region: string,
+	startUrl: string,
+	registration: ClientRegistration,
+	signal?: AbortSignal,
+): Promise<StartDeviceAuthorizationResponse> {
+	const url = ssoOidcEndpoint(region, "/device_authorization");
+	const body = {
+		clientId: registration.clientId,
+		clientSecret: registration.clientSecret,
+		startUrl,
+	};
+
+	const response = await fetchOidc(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+		signal,
+	});
+
+	const data = (await response.json()) as StartDeviceAuthorizationResponse;
+	if (!data.deviceCode || !data.userCode || !data.verificationUri) {
+		throw new Error("SSO OIDC StartDeviceAuthorization: missing required fields");
+	}
+	return data;
+}
+
+/**
+ * Poll `CreateToken` until the user completes authorization or the device code
+ * expires. Handles `authorization_pending` (continue polling) and `slow_down`
+ * (increase interval) per the published SSO OIDC model.
+ */
+export async function pollForToken(
+	region: string,
+	registration: ClientRegistration,
+	deviceCode: string,
+	intervalSeconds: number,
+	expiresInSeconds: number,
+	signal?: AbortSignal,
+): Promise<CreateTokenSuccess> {
+	const url = ssoOidcEndpoint(region, "/token");
+	const deadline = Date.now() + expiresInSeconds * 1000;
+	let currentInterval = Math.max(intervalSeconds, 1) * 1000;
+
+	while (Date.now() < deadline) {
+		if (signal?.aborted) throw new Error("Login cancelled");
+
+		const remainingMs = deadline - Date.now();
+		const waitMs = Math.min(currentInterval, remainingMs);
+		try {
+			await scheduler.wait(waitMs, { signal });
+		} catch {
+			throw new Error("Login cancelled");
+		}
+
+		if (signal?.aborted) throw new Error("Login cancelled");
+
+		const body = {
+			clientId: registration.clientId,
+			clientSecret: registration.clientSecret,
+			grantType: "urn:ietf:params:oauth:grant-type:device_code",
+			deviceCode,
+		};
+
+		const response = await fetchOidc(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+			signal,
+		});
+
+		const data = (await response.json()) as CreateTokenSuccess | CreateTokenError;
+
+		if ("accessToken" in data && typeof data.accessToken === "string") {
+			return data;
+		}
+
+		if ("error" in data) {
+			const errorCode = data.error;
+			if (errorCode === "authorization_pending") continue;
+			if (errorCode === "slow_down") {
+				currentInterval = Math.ceil(currentInterval * 1.5);
+				continue;
+			}
+			if (SSO_OIDC_FATAL_ERRORS.has(errorCode)) {
+				const desc = data.error_description ? `: ${data.error_description}` : "";
+				throw new Error(`SSO OIDC token error: ${errorCode}${desc}`);
+			}
+			// Unknown error — fail closed
+			const desc = data.error_description ? `: ${data.error_description}` : "";
+			throw new Error(`SSO OIDC unrecognized token error: ${errorCode}${desc}`);
+		}
+
+		throw new Error("SSO OIDC CreateToken: unrecognized response shape");
+	}
+
+	throw new Error("SSO OIDC device authorization timed out");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Token refresh
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Refresh an expired access token using the stored refresh token via
+ * `CreateToken` with `grantType: "refresh_token"`.
+ *
+ * Rotation is published behavior: the response includes a new `refreshToken`.
+ * If the server does not return a new one, the old refresh token is retained.
+ */
+export async function refreshKiroToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+	const region = DEFAULT_REGION;
+
+	// We need client registration to refresh. If we have a cached one, use it;
+	// otherwise re-register.
+	const registration = cachedRegistration ?? (await registerClient(region, BUILDER_ID_START_URL));
+
+	const url = ssoOidcEndpoint(region, "/token");
+	const body = {
+		clientId: registration.clientId,
+		clientSecret: registration.clientSecret,
+		grantType: "refresh_token",
+		refreshToken: credentials.refresh,
+	};
+
+	const response = await fetchOidc(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+	});
+
+	const data = (await response.json()) as CreateTokenSuccess | CreateTokenError;
+
+	if ("accessToken" in data && typeof data.accessToken === "string") {
+		const expiresAt = Date.now() + data.expiresIn * 1000;
+		return {
+			access: data.accessToken,
+			refresh: data.refreshToken ?? credentials.refresh,
+			expires: expiresAt,
+			enterpriseUrl: credentials.enterpriseUrl,
+			projectId: credentials.projectId,
+			email: credentials.email,
+			accountId: credentials.accountId,
+		};
+	}
+
+	if ("error" in data) {
+		const errorCode = data.error;
+		const desc = data.error_description ? `: ${data.error_description}` : "";
+		if (errorCode === "invalid_grant_exception" || errorCode === "invalid_grant") {
+			throw new Error(
+				`Kiro refresh token is invalid or expired. Run 'gjc auth-broker login kiro' to re-authenticate. (${errorCode}${desc})`,
+			);
+		}
+		if (errorCode === "expired_token_exception") {
+			throw new Error(
+				`Kiro client registration has expired. Run 'gjc auth-broker login kiro' to re-authenticate. (${errorCode}${desc})`,
+			);
+		}
+		throw new Error(`Kiro token refresh failed: ${errorCode}${desc}`);
+	}
+
+	throw new Error("Kiro token refresh: unrecognized response");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Full login flow (device code)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface KiroLoginOptions {
+	onAuth: (url: string, instructions?: string) => void;
+	onPrompt: (prompt: { message: string; placeholder?: string; allowEmpty?: boolean }) => Promise<string>;
+	onProgress?: (message: string) => void;
+	signal?: AbortSignal;
+	/** Override for tests. */
+	fetchImpl?: typeof globalThis.fetch;
+}
+
+export async function loginKiro(options: KiroLoginOptions): Promise<OAuthCredentials> {
+	const region = DEFAULT_REGION;
+	const startUrl = BUILDER_ID_START_URL;
+
+	if (options.signal?.aborted) throw new Error("Login cancelled");
+
+	options.onProgress?.("Registering client with AWS SSO OIDC...");
+	const registration = await registerClient(region, startUrl, options.signal);
+
+	if (options.signal?.aborted) throw new Error("Login cancelled");
+
+	options.onProgress?.("Requesting device authorization...");
+	const deviceAuth = await startDeviceAuthorization(region, startUrl, registration, options.signal);
+
+	const verificationUrl = deviceAuth.verificationUriComplete ?? deviceAuth.verificationUri;
+	options.onAuth(verificationUrl, `Enter code: ${deviceAuth.userCode}`);
+
+	options.onProgress?.("Waiting for authorization...");
+	const token = await pollForToken(
+		region,
+		registration,
+		deviceAuth.deviceCode,
+		deviceAuth.interval,
+		deviceAuth.expiresIn,
+		options.signal,
+	);
+
+	const expiresAt = Date.now() + token.expiresIn * 1000;
+	return {
+		access: token.accessToken,
+		refresh: token.refreshToken ?? "",
+		expires: expiresAt,
+	};
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SSO cache import (reuse existing ~/.aws/sso/cache/*.json pattern)
+// ─────────────────────────────────────────────────────────────────────────────
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface SsoCachedAccessToken {
+	accessToken: string;
+	expiresAt?: number;
+	startUrl?: string;
+	region?: string;
+}
+
+/**
+ * Attempt to import a cached SSO access token from `~/.aws/sso/cache/`.
+ * Returns the token if a valid (non-expired) one exists, otherwise undefined.
+ *
+ * This reuses the documented AWS CLI SSO cache location, not any third-party
+ * credential store.
+ */
+export function importSsoCacheToken(): OAuthCredentials | undefined {
+	const homeDir = process.env.HOME ?? process.env.USERPROFILE;
+	if (!homeDir) return undefined;
+	const cacheDir = path.join(homeDir, ".aws", "sso", "cache");
+
+	let files: string[];
+	try {
+		files = fs.readdirSync(cacheDir).filter(f => f.endsWith(".json"));
+	} catch {
+		return undefined;
+	}
+
+	for (const file of files) {
+		try {
+			const raw = fs.readFileSync(path.join(cacheDir, file), "utf8");
+			const cached = JSON.parse(raw) as SsoCachedAccessToken;
+			if (!cached.accessToken) continue;
+			if (cached.expiresAt && cached.expiresAt * 1000 < Date.now()) continue;
+			return {
+				access: cached.accessToken,
+				refresh: "",
+				expires: cached.expiresAt ? cached.expiresAt * 1000 : Date.now() + 3600_000,
+			};
+		} catch {}
+	}
+	return undefined;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function ssoOidcEndpoint(region: string, pathSuffix: string): string {
+	return `https://oidc.${region}.amazonaws.com${pathSuffix}`;
+}
+
+async function fetchOidc(url: string, init: RequestInit & { signal?: AbortSignal }): Promise<Response> {
+	const response = await fetch(url, init);
+	if (!response.ok) {
+		let errorBody = "";
+		try {
+			errorBody = await response.text();
+		} catch {}
+		throw new Error(
+			`SSO OIDC request to ${url} failed: ${response.status} ${response.statusText}: ${errorBody.slice(0, 500)}`,
+		);
+	}
+	return response;
+}

package/src/utils/oauth/synthetic.ts

@@ -8,9 +8,8 @@ export const loginSynthetic = createApiKeyLogin({
 	promptMessage: "Paste your Synthetic API key",
 	placeholder: "sk-...",
 	validation: {
-		kind: "chat-completions",
+		kind: "models-endpoint",
 		provider: "Synthetic",
-		baseUrl: "https://api.synthetic.new/openai/v1",
-		model: "hf:moonshotai/Kimi-K2.5",
+		modelsUrl: "https://api.synthetic.new/openai/v1/models",
 	},
 });

package/src/utils/oauth/types.ts

@@ -9,6 +9,7 @@ export type OAuthCredentials = {
 };
 
 export type OAuthProvider =
+	| "kiro"
 	| "alibaba-token-plan"
 	| "anthropic"
 	| "bizrouter"

package/src/utils/parse-bind.ts

@@ -3,6 +3,7 @@
  * paths. Centralized so the two servers can't drift on what they accept (the
  * gateway used to silently allow empty hostnames; this fixes it).
  */
+import { isIP } from "node:net";
 
 export interface ParsedBind {
 	hostname: string;
@@ -52,3 +53,29 @@ export function parseBind(raw: string): ParsedBind {
 	}
 	return { hostname: hostPart, port: parsePort(portPart, raw) };
 }
+
+/** True for loopback-only hostnames the auth servers may bind without credentials. */
+export function isLoopbackHostname(hostname: string): boolean {
+	const normalized = hostname
+		.trim()
+		.toLowerCase()
+		.replace(/^\[|\]$/g, "");
+	if (normalized === "localhost" || normalized === "::1") return true;
+	// Strict numeric IPv4 loopback literals only: a bare prefix match would
+	// accept attacker-controlled names like `127.evil.example`, and short/hex
+	// IPv4 forms (`127.1`, `0x7f.1`) are rejected by the parser anyway.
+	return isIP(normalized) === 4 && normalized.split(".")[0] === "127";
+}
+
+/**
+ * Fail closed when an unauthenticated auth server (empty bearer token set)
+ * would bind a non-loopback address: that exposes credential operations to the
+ * network with no proof of possession.
+ */
+export function assertAuthenticatedOrLoopback(bind: ParsedBind, bearerTokenCount: number, serverName: string): void {
+	if (bearerTokenCount > 0) return;
+	if (isLoopbackHostname(bind.hostname)) return;
+	throw new Error(
+		`${serverName} refuses to bind ${bind.hostname}:${bind.port} without bearer tokens; unauthenticated mode is loopback-only.`,
+	);
+}