@vib-rato/ai 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-09-14
+
+### Added
+
+- Air-gapped mode support (`VIB_AIRV=1`, see the coding-agent changelog): the models.dev catalog fetch, `AuthStorage.fetchUsageReports`, both auth-broker request paths, OAuth token refresh and API-key acquisition, and proxy resolution return early or refuse before any network is touched; the proxied TLS socket path classifies its destination; and `SqliteAuthCredentialStore` accepts `excludeProviders` so excluded providers' credential rows are never read from SQLite. Provider model discovery against a private endpoint is unaffected.
+
 ## [0.18.0] - 2026-09-08
 
 - Transport failure facts now retain the Vibrato Usage Gateway's `x-vug-daily-limit`, `x-vug-daily-used`, `x-vug-daily-remaining`, `x-vug-daily-reset`, `x-vug-queue-depth`, `x-vug-inflight`, and `x-vug-queued-ms` headers (raw string values, allowlisted like the existing `retry-after`/`retry-after-ms` entries), and classify a gateway `daily_token_limit` provider code as a `quota` fallback trigger instead of `rate_limit`. Previously the gateway's daily-limit 429 was treated as an ordinary rate limit with a 12-hour retry window, and the `x-vug-daily-*` headers were dropped before reaching consumers. A code-less 429 still classifies as `rate_limit`, and 503 `queue_timeout`/`queue_full` still classify as `server`.

package/dist/types/auth-storage.d.ts

@@ -1013,10 +1013,24 @@ export declare class AuthStorage {
  * `getApiKey`, `listProviders`, `deleteProvider`) that callers can use directly
  * without going through `AuthStorage`.
  */
+/**
+ * `excludeProviders` removes those providers from every credential *read* at
+ * the SQL level: the listing statements carry a `provider NOT IN (…)` clause,
+ * so the `data` column of an excluded row is never fetched and its payload
+ * never enters the process. Writes are untouched — this hides rows from a
+ * reader, it does not make the store forget them.
+ *
+ * The air-gapped mode (`airv`) is the caller: hosted-provider credentials must
+ * not be read at all, while local-endpoint keys live in the same database and
+ * must keep working.
+ */
+export interface SqliteAuthCredentialStoreOptions {
+    excludeProviders?: readonly string[];
+}
 export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     #private;
-    constructor(db: Database);
-    static open(dbPath?: string): Promise<SqliteAuthCredentialStore>;
+    constructor(db: Database, options?: SqliteAuthCredentialStoreOptions);
+    static open(dbPath?: string, options?: SqliteAuthCredentialStoreOptions): Promise<SqliteAuthCredentialStore>;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
     listCredentialInventory(provider?: string): CredentialInventoryRecord[];
     listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@vib-rato/ai",
-	"version": "0.18.0",
+	"version": "0.19.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://github.com/Keonho-Chu/Vibrato",
 	"author": "Yeachan-Heo and Vibrato Contributors",
@@ -40,8 +40,8 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@vib-rato/natives": "0.18.0",
-		"@vib-rato/utils": "0.18.0",
+		"@vib-rato/natives": "0.19.0",
+		"@vib-rato/utils": "0.19.0",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-broker/client.ts

@@ -5,7 +5,8 @@
  * `vib auth-broker status` (liveness checks). All endpoints except
  * `/v1/healthz` require a bearer token.
  */
-import { readSseEvents } from "@vib-rato/utils";
+import { logger, readSseEvents } from "@vib-rato/utils";
+import { AIR_REFUSAL_MESSAGE, isAirMode } from "@vib-rato/utils/air/mode";
 import type { ZodType, infer as zInfer } from "zod/v4";
 import type { AuthCredential } from "../auth-storage";
 import type { Provider } from "../types";
@@ -201,6 +202,13 @@ export class AuthBrokerClient {
 	 * to long-polling for the remainder of its lifetime.
 	 */
 	async *openSnapshotStream(opts: { signal?: AbortSignal } = {}): AsyncGenerator<SnapshotStreamEvent> {
+		if (isAirMode()) {
+			logger.debug("airv: skipped auth-broker-snapshot-stream", {
+				feature: "auth-broker-snapshot-stream",
+				destination: "auth-broker",
+			});
+			throw new AuthBrokerError(AIR_REFUSAL_MESSAGE);
+		}
 		const url = `${this.#baseUrl}/v1/snapshot/stream`;
 		const headers: Record<string, string> = {
 			Accept: "text/event-stream",
@@ -389,6 +397,13 @@ export class AuthBrokerClient {
 			timeoutMs?: number;
 		},
 	): Promise<Response> {
+		if (isAirMode()) {
+			logger.debug("airv: skipped auth-broker-request", {
+				feature: "auth-broker-request",
+				destination: "auth-broker",
+			});
+			throw new AuthBrokerError(AIR_REFUSAL_MESSAGE);
+		}
 		const auth = opts.auth ?? true;
 		const url = `${this.#baseUrl}${path}`;
 		const headers: Record<string, string> = { Accept: "application/json", ...(opts.headers ?? {}) };

package/src/auth-storage.ts

@@ -12,6 +12,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getAgentDbPath, logger } from "@vib-rato/utils";
+import { isAirMode } from "@vib-rato/utils/air/mode";
 import { checkOpenCodexStatus } from "./providers/openai-opencodex-responses";
 import { getEnvApiKey } from "./stream";
 import type { Provider } from "./types";
@@ -4127,6 +4128,13 @@ export class AuthStorage {
 		/** Disable provider/account/error logging for secret-safe control surfaces. */
 		logDetails?: boolean;
 	}): Promise<UsageReport[] | null> {
+		if (isAirMode()) {
+			logger.debug("airv: skipped auth-storage-usage-reports", {
+				feature: "auth-storage-usage-reports",
+				destination: "usage-api",
+			});
+			return [];
+		}
 		// Caller override > store-level hook > local per-credential fan-out.
 		// `RemoteAuthCredentialStore` implements the store hook so a gateway
 		// backed by a broker automatically routes usage to the broker without
@@ -6411,8 +6419,24 @@ function extractOAuthTokenIdentifiers(token: string | undefined): string[] | und
  * `getApiKey`, `listProviders`, `deleteProvider`) that callers can use directly
  * without going through `AuthStorage`.
  */
+/**
+ * `excludeProviders` removes those providers from every credential *read* at
+ * the SQL level: the listing statements carry a `provider NOT IN (…)` clause,
+ * so the `data` column of an excluded row is never fetched and its payload
+ * never enters the process. Writes are untouched — this hides rows from a
+ * reader, it does not make the store forget them.
+ *
+ * The air-gapped mode (`airv`) is the caller: hosted-provider credentials must
+ * not be read at all, while local-endpoint keys live in the same database and
+ * must keep working.
+ */
+export interface SqliteAuthCredentialStoreOptions {
+	excludeProviders?: readonly string[];
+}
+
 export class SqliteAuthCredentialStore implements AuthCredentialStore {
 	#db: Database;
+	readonly #excludedProviders: readonly string[];
 	#listActiveStmt: Statement;
 	#listActiveByProviderStmt: Statement;
 	#listAllStmt: Statement;
@@ -6432,21 +6456,35 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 	#deleteExpiredCacheStmt: Statement;
 	#closed = false;
 
-	constructor(db: Database) {
+	constructor(db: Database, options: SqliteAuthCredentialStoreOptions = {}) {
 		this.#db = db;
 		this.#initializeSchema();
+		this.#excludedProviders = Object.freeze(
+			[...new Set((options.excludeProviders ?? []).map(provider => provider.trim().toLowerCase()))].filter(
+				provider => provider.length > 0,
+			),
+		);
+		// One extra `AND provider NOT IN (…)` folded into the listing statements
+		// when an exclusion is configured; with none, the SQL is byte-identical to
+		// what it has always been.
+		const notExcluded =
+			this.#excludedProviders.length === 0
+				? ""
+				: ` AND lower(provider) NOT IN (${this.#excludedProviders.map(() => "?").join(", ")})`;
 
 		this.#listActiveStmt = this.#db.prepare(
-			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE disabled_cause IS NULL ORDER BY id ASC",
+			`SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE disabled_cause IS NULL${notExcluded} ORDER BY id ASC`,
 		);
 		this.#listActiveByProviderStmt = this.#db.prepare(
-			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ? AND disabled_cause IS NULL ORDER BY id ASC",
+			`SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ? AND disabled_cause IS NULL${notExcluded} ORDER BY id ASC`,
 		);
 		this.#listAllStmt = this.#db.prepare(
-			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials ORDER BY id ASC",
+			`SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials${
+				notExcluded === "" ? "" : ` WHERE 1 = 1${notExcluded}`
+			} ORDER BY id ASC`,
 		);
 		this.#listAllByProviderStmt = this.#db.prepare(
-			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ? ORDER BY id ASC",
+			`SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ?${notExcluded} ORDER BY id ASC`,
 		);
 		this.#listDisabledByProviderStmt = this.#db.prepare(
 			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ? AND disabled_cause IS NOT NULL ORDER BY id ASC",
@@ -6481,7 +6519,10 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		this.#deleteExpiredCacheStmt = this.#db.prepare(`DELETE FROM cache WHERE expires_at <= ${SQLITE_NOW_EPOCH}`);
 	}
 
-	static async open(dbPath: string = getAgentDbPath()): Promise<SqliteAuthCredentialStore> {
+	static async open(
+		dbPath: string = getAgentDbPath(),
+		options: SqliteAuthCredentialStoreOptions = {},
+	): Promise<SqliteAuthCredentialStore> {
 		const dir = path.dirname(dbPath);
 		const dirExists = await fs
 			.stat(dir)
@@ -6498,7 +6539,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 			// Ignore chmod failures (e.g., Windows)
 		}
 
-		return new SqliteAuthCredentialStore(db);
+		return new SqliteAuthCredentialStore(db, options);
 	}
 
 	#initializeSchema(): void {
@@ -6722,11 +6763,17 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 
 	// ─── AuthCredentialStore interface ──────────────────────────────────────
 
+	/** True when reads must not see this provider's rows at all. */
+	#isExcludedProvider(provider: string): boolean {
+		return this.#excludedProviders.includes(provider.trim().toLowerCase());
+	}
+
 	listAuthCredentials(provider?: string): StoredAuthCredential[] {
+		if (provider !== undefined && this.#isExcludedProvider(provider)) return [];
 		const rows =
 			(provider
-				? (this.#listActiveByProviderStmt.all(provider) as AuthRow[])
-				: (this.#listActiveStmt.all() as AuthRow[])) ?? [];
+				? (this.#listActiveByProviderStmt.all(provider, ...this.#excludedProviders) as AuthRow[])
+				: (this.#listActiveStmt.all(...this.#excludedProviders) as AuthRow[])) ?? [];
 
 		const results: StoredAuthCredential[] = [];
 		for (const row of rows) {
@@ -6738,10 +6785,11 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	listCredentialInventory(provider?: string): CredentialInventoryRecord[] {
+		if (provider !== undefined && this.#isExcludedProvider(provider)) return [];
 		const rows =
 			provider === undefined
-				? (this.#listAllStmt.all() as AuthRow[])
-				: (this.#listAllByProviderStmt.all(provider) as AuthRow[]);
+				? (this.#listAllStmt.all(...this.#excludedProviders) as AuthRow[])
+				: (this.#listAllByProviderStmt.all(provider, ...this.#excludedProviders) as AuthRow[]);
 		const results: CredentialInventoryRecord[] = [];
 		for (const row of rows) {
 			const credential = deserializeCredential(row);
@@ -6766,10 +6814,11 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[] {
+		if (provider !== undefined && this.#isExcludedProvider(provider)) return [];
 		const rows =
 			provider === undefined
-				? (this.#listAllStmt.all() as AuthRow[])
-				: (this.#listAllByProviderStmt.all(provider) as AuthRow[]);
+				? (this.#listAllStmt.all(...this.#excludedProviders) as AuthRow[])
+				: (this.#listAllByProviderStmt.all(provider, ...this.#excludedProviders) as AuthRow[]);
 		return rows.map(row => ({ id: row.id, provider: row.provider, expectedRevision: row.revision }));
 	}
 	removeAuthCredentialsHard(

package/src/model-manager.ts

@@ -1,4 +1,5 @@
-import { sanitizeText } from "@vib-rato/utils";
+import { logger, sanitizeText } from "@vib-rato/utils";
+import { isAirMode } from "@vib-rato/utils/air/mode";
 import { applyFinalCodexGpt56ContextCap } from "./context-cap-policy";
 import { insertModelCacheIfAbsent, readModelCache, updateModelCacheIfUnchanged, writeModelCache } from "./model-cache";
 import { isRetiredModel, isRetiredModelKey } from "./model-retirements";
@@ -178,6 +179,13 @@ async function resolveProviderModelsUncoalesced<TApi extends Api = Api, TModelsD
 	options: ModelManagerOptions<TApi, TModelsDevPayload>,
 	strategy: ModelRefreshStrategy = "online-if-uncached",
 ): Promise<ModelResolutionResult<TApi>> {
+	// airv only blocks the models.dev destination (see `fetchModelsDev` below),
+	// not this whole resolution: a provider's own `fetchDynamicModels` talks to
+	// its configured `baseUrl` (e.g. a local vLLM/Ollama gateway), which is a
+	// destination the EgressGuard and the provider's own boundary classification
+	// gate, not a feature this layer should suppress wholesale. Forcing
+	// `strategy = "offline"` here would also skip that fetcher, leaving airv
+	// users unable to discover local models without hand-writing every entry.
 	const now = options.now ?? Date.now;
 	const ttlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
 	const dbPath = options.cacheDbPath;
@@ -405,6 +413,13 @@ async function fetchModelsDev<TApi extends Api, TModelsDevPayload>(
 	if (!options.modelsDev) {
 		return null;
 	}
+	if (isAirMode()) {
+		// airv blocks only the models.dev destination here; a provider's own
+		// `fetchDynamicModels` (its configured baseUrl) is unaffected — see the
+		// comment in `resolveProviderModelsUncoalesced` above.
+		logger.debug("airv: skipped models-dev-fetch", { feature: "models-dev-fetch", destination: "models.dev" });
+		return null;
+	}
 
 	try {
 		const payload = await options.modelsDev.fetch();

package/src/utils/oauth/index.ts

@@ -1,6 +1,7 @@
 // ============================================================================
 // High-level API
 // ============================================================================
+import { AIR_REFUSAL_MESSAGE, isAirMode } from "@vib-rato/utils/air/mode";
 import type {
 	OAuthCredentials,
 	OAuthProvider,
@@ -332,6 +333,12 @@ export async function refreshOAuthToken(
 	provider: OAuthProvider,
 	credentials: OAuthCredentials,
 ): Promise<OAuthCredentials> {
+	// Rule (c): a refresh POSTs a stored credential to a provider token endpoint
+	// and runs without an explicit user command, so it is refused before the
+	// provider module is even imported. `@vib-rato/ai` cannot reach
+	// coding-agent's `AirRefusedError`, so the standard message is thrown
+	// directly; the string itself is the shared constant.
+	if (isAirMode()) throw new Error(AIR_REFUSAL_MESSAGE);
 	if (!credentials) {
 		throw new Error(`No OAuth credentials found for ${provider}`);
 	}
@@ -476,6 +483,10 @@ export async function getOAuthApiKey(
 	provider: OAuthProvider,
 	credentials: Record<string, OAuthCredentials>,
 ): Promise<{ newCredentials: OAuthCredentials; apiKey: string } | null> {
+	// Rule (c): handing back an OAuth access token exists only to authenticate a
+	// request to that provider's cloud endpoint. Refuse ahead of the lookup so no
+	// credential is read, not merely unused.
+	if (isAirMode()) throw new Error(AIR_REFUSAL_MESSAGE);
 	let creds = credentials[provider];
 	if (!creds) {
 		return null;

package/src/utils/proxy.ts

@@ -1,5 +1,7 @@
 import * as net from "node:net";
 import * as tls from "node:tls";
+import { classifyDestination } from "@vib-rato/utils/air/boundary";
+import { AIR_REFUSAL_MESSAGE, airAllowedSuffixes, isAirMode } from "@vib-rato/utils/air/mode";
 
 export interface ProxyConnectOptions {
 	signal?: AbortSignal;
@@ -248,6 +250,10 @@ function matchesNoProxy(hostname: string, port: number | undefined): boolean {
 }
 
 export function getProxyForUrl(provider: string, url: URL): string | undefined {
+	// airv: a proxy is by definition a third host, and this function already
+	// declines to proxy private targets, so in air-gapped mode a proxy is never
+	// the right answer. Refuse unconditionally rather than dial an env-supplied host.
+	if (isAirMode()) return undefined;
 	const hostname = normalizeHost(url.hostname);
 	if (!hostname || isPrivateOrLocalHost(hostname) || matchesNoProxy(hostname, effectiveUrlPort(url))) return undefined;
 
@@ -586,6 +592,18 @@ export function connectProxiedSocket(
 	targetUrl: string,
 	options: ProxyConnectOptions = {},
 ): Promise<tls.TLSSocket> {
+	// airv defense in depth. `getProxyForUrl` already returns undefined in
+	// air-gapped mode, so nothing should reach here; classify anyway, because
+	// these raw `net.connect` / `tls.connect` sockets never pass the fetch guard.
+	if (isAirMode()) {
+		const suffixes = airAllowedSuffixes();
+		const target = classifyDestination(targetUrl, suffixes);
+		const proxy = classifyDestination(proxyUrl, suffixes);
+		if (!target.allowed || !proxy.allowed) {
+			const reason = target.allowed ? (proxy as { reason: string }).reason : (target as { reason: string }).reason;
+			return Promise.reject(transportError(`${AIR_REFUSAL_MESSAGE} (${reason})`));
+		}
+	}
 	const { promise, resolve, reject } = Promise.withResolvers<tls.TLSSocket>();
 	const sockets = new Set<net.Socket>();
 	const abortController = new AbortController();