fix(shared): resolve config on demand without mutating process.env (#183)

* fix(shared): resolve config on demand without mutating process.env

Importing the server entry previously ran dotenv.config() as an
import-time side effect, loading the consuming app's entire .env
(including unrelated keys) into the global process.env.

Remove the module-level exported config singleton in both storage and
iam. Configuration is now resolved on demand via getConfig(), which each
operation calls when it needs it. Env resolution parses .env into a
private object (never process.env), keeps only TIGRIS_-prefixed keys,
and prefers explicitly-set process.env values.

Importing the SDK no longer has side effects, and apps that manage their
own environment are no longer overridden.

Closes #181

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: designcode

.changeset/scoped-env-loading.md

@@ -0,0 +1,8 @@
+---
+'@tigrisdata/storage': patch
+'@tigrisdata/iam': patch
+---
+
+Stop mutating the global `process.env` when loading configuration. Previously, importing the server entry ran `dotenv.config()` as an import-time side effect, loading the consuming app's entire `.env` (including unrelated keys) into `process.env`.
+
+Configuration is now resolved on demand, per operation, directly from the environment: the SDK parses `.env` into a private object (never touching `process.env`), keeps only `TIGRIS_`-prefixed keys, and prefers explicitly-set `process.env` values. Importing the SDK no longer has side effects, and apps that manage their own environment are no longer overridden.

packages/iam/src/lib/config.ts

@@ -1,29 +1,33 @@
-import { isNode, loadEnv } from '@shared/index';
+import { getEnvVar, isNode } from '@shared/index';
 import type { TigrisIAMConfig } from './types';
 
 export const DEFAULT_ENDPOINTS = {
   iam: 'https://iam.storageapi.dev',
   mgmt: 'https://mgmt.storageapi.dev',
 };
 
-function loadIAMConfig(): TigrisIAMConfig {
-  loadEnv();
-
+/**
+ * Resolve the Tigris IAM configuration from the environment, on demand.
+ *
+ * Reads only `TIGRIS_`-prefixed variables — from `process.env`, falling back to
+ * a private parse of `.env` — and never mutates `process.env`. There is no
+ * module-level config and importing this module has no side effects: each
+ * operation calls `getConfig()` when it needs the current configuration.
+ */
+export function getConfig(): TigrisIAMConfig {
   const config: TigrisIAMConfig = {
     iamEndpoint: DEFAULT_ENDPOINTS.iam,
     mgmtEndpoint: DEFAULT_ENDPOINTS.mgmt,
   };
 
   if (isNode()) {
-    config.iamEndpoint = process.env.TIGRIS_IAM_ENDPOINT;
-    config.mgmtEndpoint = process.env.TIGRIS_MGMT_ENDPOINT;
-    config.sessionToken = process.env.TIGRIS_SESSION_TOKEN;
-    config.organizationId = process.env.TIGRIS_ORGANIZATION_ID;
-    config.accessKeyId = process.env.TIGRIS_STORAGE_ACCESS_KEY_ID;
-    config.secretAccessKey = process.env.TIGRIS_STORAGE_SECRET_ACCESS_KEY;
+    config.iamEndpoint = getEnvVar('TIGRIS_IAM_ENDPOINT');
+    config.mgmtEndpoint = getEnvVar('TIGRIS_MGMT_ENDPOINT');
+    config.sessionToken = getEnvVar('TIGRIS_SESSION_TOKEN');
+    config.organizationId = getEnvVar('TIGRIS_ORGANIZATION_ID');
+    config.accessKeyId = getEnvVar('TIGRIS_STORAGE_ACCESS_KEY_ID');
+    config.secretAccessKey = getEnvVar('TIGRIS_STORAGE_SECRET_ACCESS_KEY');
   }
 
   return config;
 }
-
-export const config: TigrisIAMConfig = loadIAMConfig();

packages/iam/src/lib/http-client.ts

@@ -1,5 +1,5 @@
 import { createTigrisHttpClient, type TigrisHttpClient } from '@shared/index';
-import { config, DEFAULT_ENDPOINTS } from './config';
+import { DEFAULT_ENDPOINTS, getConfig } from './config';
 import type { TigrisIAMConfig, TigrisIAMResponse } from './types';
 
 export const IAM_ENDPOINTS = {
@@ -38,17 +38,22 @@ export const IAM_ENDPOINTS = {
 };
 
 function getIAMEndpoint(options?: TigrisIAMConfig): string {
-  return options?.iamEndpoint ?? config.iamEndpoint ?? DEFAULT_ENDPOINTS.iam;
+  return (
+    options?.iamEndpoint ?? getConfig().iamEndpoint ?? DEFAULT_ENDPOINTS.iam
+  );
 }
 
 function getManagementEndpoint(options?: TigrisIAMConfig): string {
-  return options?.mgmtEndpoint ?? config.mgmtEndpoint ?? DEFAULT_ENDPOINTS.mgmt;
+  return (
+    options?.mgmtEndpoint ?? getConfig().mgmtEndpoint ?? DEFAULT_ENDPOINTS.mgmt
+  );
 }
 
 export function createIAMClient(
   options?: TigrisIAMConfig,
   isManagement?: boolean
 ): TigrisIAMResponse<TigrisHttpClient, Error> {
+  const config = getConfig();
   const sessionToken = options?.sessionToken ?? config.sessionToken;
   const organizationId = options?.organizationId ?? config.organizationId;
   const accessKeyId = options?.accessKeyId ?? config.accessKeyId;

packages/storage/src/lib/bucket/snapshot.ts

@@ -5,7 +5,7 @@ import {
 } from '@aws-sdk/client-s3';
 import type { HttpRequest, HttpResponse } from '@aws-sdk/types';
 import { TigrisHeaders } from '@shared/index';
-import { config } from '../config';
+import { getConfig } from '../config';
 import { createTigrisClient } from '../tigris-client';
 import type { TigrisStorageConfig, TigrisStorageResponse } from '../types';
 
@@ -37,6 +37,7 @@ export async function listBucketSnapshots(
   sourceBucketName?: string | ListBucketSnapshotsOptions,
   options?: ListBucketSnapshotsOptions
 ): Promise<TigrisStorageResponse<ListBucketSnapshotsResponse, Error>> {
+  const config = getConfig();
   if (typeof sourceBucketName === 'object') {
     options = sourceBucketName;
     sourceBucketName = undefined;
@@ -116,6 +117,7 @@ export async function createBucketSnapshot(
   sourceBucketName?: string | CreateBucketSnapshotOptions,
   options?: CreateBucketSnapshotOptions
 ): Promise<TigrisStorageResponse<CreateBucketSnapshotResponse, Error>> {
+  const config = getConfig();
   if (typeof sourceBucketName === 'object') {
     options = sourceBucketName;
     sourceBucketName = undefined;

packages/storage/src/lib/config.ts

@@ -1,7 +1,7 @@
 import {
   missingConfigError as baseMissingConfigError,
+  getEnvVar,
   isNode,
-  loadEnv,
 } from '@shared/index';
 import type { TigrisStorageConfig } from './types';
 
@@ -17,24 +17,29 @@ const configMap: Partial<Record<keyof TigrisStorageConfig, string>> = {
 export const missingConfigError = (key: string) =>
   baseMissingConfigError(key, configMap[key as keyof TigrisStorageConfig]);
 
-function loadStorageConfig(): TigrisStorageConfig {
-  loadEnv();
-
+/**
+ * Resolve the Tigris storage configuration from the environment, on demand.
+ *
+ * Reads only `TIGRIS_`-prefixed variables — from `process.env`, falling back to
+ * a private parse of `.env` — and never mutates `process.env`. There is no
+ * module-level config and importing this module has no side effects: each
+ * operation calls `getConfig()` when it needs the current configuration.
+ */
+export function getConfig(): TigrisStorageConfig {
   const config: TigrisStorageConfig = {
     endpoint: 'https://t3.storage.dev',
   };
 
   if (isNode()) {
-    config.bucket = process.env.TIGRIS_STORAGE_BUCKET ?? '';
-    config.accessKeyId = process.env.TIGRIS_STORAGE_ACCESS_KEY_ID ?? '';
-    config.secretAccessKey = process.env.TIGRIS_STORAGE_SECRET_ACCESS_KEY ?? '';
+    config.bucket = getEnvVar('TIGRIS_STORAGE_BUCKET') ?? '';
+    config.accessKeyId = getEnvVar('TIGRIS_STORAGE_ACCESS_KEY_ID') ?? '';
+    config.secretAccessKey =
+      getEnvVar('TIGRIS_STORAGE_SECRET_ACCESS_KEY') ?? '';
     config.endpoint =
-      process.env.TIGRIS_STORAGE_ENDPOINT ?? 'https://t3.storage.dev';
-    config.sessionToken = process.env.TIGRIS_SESSION_TOKEN;
-    config.organizationId = process.env.TIGRIS_ORGANIZATION_ID;
+      getEnvVar('TIGRIS_STORAGE_ENDPOINT') ?? 'https://t3.storage.dev';
+    config.sessionToken = getEnvVar('TIGRIS_SESSION_TOKEN');
+    config.organizationId = getEnvVar('TIGRIS_ORGANIZATION_ID');
   }
 
   return config;
 }
-
-export const config: TigrisStorageConfig = loadStorageConfig();

packages/storage/src/lib/fork/_legacy.ts

@@ -4,7 +4,7 @@
  */
 
 import { fetchBucketListing } from '../bucket/listing';
-import { config } from '../config';
+import { getConfig } from '../config';
 import type { TigrisStorageResponse } from '../types';
 import type { BucketFork, ListForksOptions, ListForksResponse } from './list';
 
@@ -19,6 +19,7 @@ export async function listForksLegacy(
   sourceBucketName?: string | ListForksOptions,
   options?: ListForksOptions
 ): Promise<TigrisStorageResponse<ListForksResponse, Error>> {
+  const config = getConfig();
   if (typeof sourceBucketName === 'object') {
     options = sourceBucketName;
     sourceBucketName = undefined;

packages/storage/src/lib/fork/list.ts

@@ -1,6 +1,6 @@
 import { fetchBucketListing } from '../bucket/listing';
 import type { Bucket } from '../bucket/types';
-import { config } from '../config';
+import { getConfig } from '../config';
 import type { TigrisStorageConfig, TigrisStorageResponse } from '../types';
 import { listForksLegacy } from './_legacy';
 
@@ -46,6 +46,7 @@ export async function listForks(
   sourceBucketName?: string | ListForksOptions,
   options?: ListForksOptions
 ): Promise<TigrisStorageResponse<ListForksResponse, Error>> {
+  const config = getConfig();
   if (typeof sourceBucketName === 'object') {
     options = sourceBucketName;
     sourceBucketName = undefined;

packages/storage/src/lib/http-client.ts

@@ -1,14 +1,15 @@
 import { createTigrisHttpClient, type TigrisHttpClient } from '@shared/index';
-import { config } from './config';
+import { getConfig } from './config';
 import type { TigrisStorageConfig, TigrisStorageResponse } from './types';
 
 function getStorageEndpoint(options?: TigrisStorageConfig): string {
-  return options?.endpoint ?? config.endpoint ?? 'https://t3.storage.dev';
+  return options?.endpoint ?? getConfig().endpoint ?? 'https://t3.storage.dev';
 }
 
 export function createStorageClient(
   options?: TigrisStorageConfig
 ): TigrisStorageResponse<TigrisHttpClient, Error> {
+  const config = getConfig();
   const sessionToken = options?.sessionToken ?? config.sessionToken;
   const organizationId = options?.organizationId ?? config.organizationId;
   const accessKeyId = options?.accessKeyId ?? config.accessKeyId;

packages/storage/src/lib/object/bundle.ts

@@ -1,5 +1,5 @@
 import { TigrisHeaders, toError } from '@shared/index';
-import { config, missingConfigError } from '../config';
+import { getConfig, missingConfigError } from '../config';
 import { createStorageClient } from '../http-client';
 import type { TigrisStorageConfig, TigrisStorageResponse } from '../types';
 
@@ -50,6 +50,7 @@ export async function bundle(
   keys: string[],
   options?: BundleOptions
 ): Promise<TigrisStorageResponse<BundleResponse, Error>> {
+  const config = getConfig();
   const bucket = options?.config?.bucket ?? config.bucket;
 
   if (!bucket) {

packages/storage/src/lib/object/copy.ts

@@ -1,6 +1,6 @@
 import { TigrisHeaders } from '@shared/headers';
 import { encodeObjectKey, handleError } from '@shared/utils';
-import { config, missingConfigError } from '../config';
+import { getConfig, missingConfigError } from '../config';
 import { createStorageClient } from '../http-client';
 import type { TigrisStorageConfig, TigrisStorageResponse } from '../types';
 
@@ -31,6 +31,7 @@ export async function copyOrMove(
   rename: boolean,
   options?: CopyOptions
 ): Promise<TigrisStorageResponse<CopyResponse, Error>> {
+  const config = getConfig();
   if (!src || !dest) {
     return { error: new Error('src and dest are required') };
   }