Detect .env source file edits in injected-env blob reuse (#1029)

* Detect .env source file edits in injected-env blob reuse

Record a content fingerprint for each file-based source into the serialized
env graph, and re-verify it in the automatic reuse path so a blob captured
before an env file edit falls back to CLI re-resolution. Explicit trust mode
(_VARLOCK_USE_INJECTED_ENV=1) still skips the check since sandbox blobs have
no local files.

* Verify disabled sources in injected-env reuse too

@disable lives in the source's own content, so an edit to a disabled file
can re-enable it. An edit that leaves it disabled just costs one harmless
re-resolution.

* Correct the non-regular-file rationale in the reuse source check

Fresh resolution does read FIFO env sources (1Password Environments), so
the fallback is right because a pipe's content can't be verified without
a side-effectful read, not because the loader would skip it.

Author: theoephraim

.bumpy/injected-env-source-fingerprint.md

@@ -0,0 +1,5 @@
+---
+varlock: patch
+---
+
+Injected env blob reuse now detects .env source file edits: auto-load and varlock run re-resolve instead of serving stale values when a source file changed since the blob was created

packages/varlock-website/src/content/docs/integrations/javascript.mdx

@@ -74,6 +74,7 @@ Reuse only happens when a fresh resolution would produce the same result:
 
 - the blob was resolved in the same directory the app would resolve in (a root-level `varlock run` in a monorepo does not stop per-package resolution)
 - it resolved without errors
+- the `.env` files it was resolved from are unchanged on disk (editing an env file and restarting the app inside the same `varlock run` re-resolves and picks up the edit)
 - no env override recorded in the blob has changed since (`varlock run -- sh -c 'FOO=x node app.js'` re-resolves, so the new `FOO` wins)
 
 If any check fails, auto-load falls back to the CLI. Control it explicitly with [`_VARLOCK_USE_INJECTED_ENV`](/reference/reserved-variables/#_varlock_use_injected_env): `0` always re-resolves, `1` always trusts the blob, skipping the directory check. `varlock run` applies the same rules when it finds a blob, which covers non-Node workloads. Trust mode is how you hand an env into an environment with no `.env` files at all, like a remote sandbox; see the [E2B](/sandboxes/e2b/#passing-resolved-values) and [Fly.io](/sandboxes/flyio/#passing-resolved-values) guides.

packages/varlock/src/env-graph/lib/env-graph.ts

@@ -38,6 +38,7 @@ import {
   type ProxyApprovalEach, type ProxyEgressMode, type ProxyManagedItem, type ProxyRule,
 } from '../../proxy/types';
 import { parseDuration } from '../../lib/duration';
+import { hashEnvSourceContents } from '../../lib/env-source-fingerprint';
 
 const processExists = !!globalThis.process;
 const originalProcessEnv = { ...processExists && process.env };
@@ -64,6 +65,13 @@ export type SerializedEnvGraph = {
     label: string;
     enabled: boolean;
     path?: string;
+    /**
+     * Fingerprint of the file contents this resolution actually parsed (see
+     * `hashEnvSourceContents`). The automatic injected-env reuse path re-hashes the file on
+     * disk and re-resolves on mismatch, so a blob captured before an env file edit is never
+     * served after it. Only present for file-based sources.
+     */
+    contentHash?: string;
   }>,
   settings: {
     redactLogs?: boolean;
@@ -917,6 +925,10 @@ export class EnvGraph {
         label: source.label,
         enabled: !source.disabled,
         path: source instanceof FileBasedDataSource ? path.relative(this.basePath ?? '', source.fullPath) : undefined,
+        // fingerprint what was actually parsed (not a re-read from disk, which could
+        // already have changed) so injected-env reuse can detect later file edits
+        ...(source instanceof FileBasedDataSource && source.rawContents !== undefined)
+          ? { contentHash: hashEnvSourceContents(source.rawContents) } : {},
       });
     }
     for (const itemKey of this.sortedConfigKeys) {

packages/varlock/src/env-graph/test/source-fingerprint-serialization.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import outdent from 'outdent';
+import { EnvGraph } from '../index';
+import { DotEnvFileDataSource } from '../lib/data-source';
+import { hashEnvSourceContents } from '../../lib/env-source-fingerprint';
+
+describe('getSerializedGraph source fingerprints', () => {
+  it('records a contentHash of the parsed contents for file-based sources', async () => {
+    const contents = outdent`
+      FOO=bar
+    `;
+    const g = new EnvGraph();
+    await g.setRootDataSource(new DotEnvFileDataSource('.env.schema', { overrideContents: contents }));
+    await g.finishLoad();
+    await g.resolveEnvValues();
+
+    const blob = g.getSerializedGraph();
+    expect(blob.sources).toHaveLength(1);
+    expect(blob.sources[0].contentHash).toBe(hashEnvSourceContents(contents));
+  });
+});

packages/varlock/src/lib/env-source-fingerprint.ts

@@ -0,0 +1,13 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Content fingerprint for a file-based env source, recorded into the serialized graph
+ * (`SerializedEnvGraph.sources[].contentHash`) at resolution time and re-checked by the
+ * automatic injected-env reuse path to detect source file edits since the blob was made.
+ *
+ * Truncated sha256 - this is drift detection, not an integrity/security boundary, and the
+ * blob travels in an env var so we keep it short.
+ */
+export function hashEnvSourceContents(contents: string): string {
+  return createHash('sha256').update(contents, 'utf8').digest('hex').slice(0, 16);
+}

packages/varlock/src/lib/injected-env-reuse.ts

@@ -4,6 +4,7 @@ import type { SerializedEnvGraph } from '../env-graph';
 import { isEncryptedBlob, decryptEnvBlobSync } from '../runtime/crypto';
 import { readVarlockPackageJsonConfig } from './package-json-config';
 import { envValueMatchesBlobItem } from './injected-env-provenance';
+import { hashEnvSourceContents } from './env-source-fingerprint';
 
 /**
  * Decides whether a consumer (`varlock/auto-load`, or a `varlock run` that finds a blob
@@ -200,6 +201,43 @@ export function evaluateInjectedEnvReuse(opts: {
     };
   }
 
+  // Source drift: the producer fingerprints the contents of each file source it actually
+  // parsed (see getSerializedGraph). If a source has been edited or removed since the blob
+  // was made (e.g. an env file edit followed by a dev-server restart inside the same
+  // `varlock run`), reuse could serve pre-edit values - re-resolve instead. Disabled
+  // sources are verified too: `@disable` lives in the source's own content, so an edit can
+  // re-enable it (an edit that leaves it disabled just costs one harmless re-resolution).
+  // Known gap: a matching env file *created* after the blob won't appear in its sources
+  // list and isn't detected here.
+  if (!Array.isArray(parsedEnv.sources)) {
+    return { reuse: false, reason: 'blob has no sources recorded' };
+  }
+  for (const source of parsedEnv.sources) {
+    if (source.path === undefined) continue;
+    // older producers didn't record fingerprints - we can't verify, so re-resolve
+    if (!source.contentHash) {
+      return { reuse: false, reason: `blob has no content fingerprint for source ${source.path}` };
+    }
+    const sourceFullPath = path.resolve(parsedEnv.basePath, source.path);
+    let currentContents: string;
+    try {
+      // stat-gate before reading - env sources can legitimately be FIFOs (e.g. 1Password
+      // Environments serves .env files as pipes), and reading one here would have side
+      // effects (the serving process rewrites it) or block forever on a writerless pipe.
+      // A non-regular file's content can't be verified without reading it, so fall back
+      // to a fresh resolution, which reads it once the same way any normal load does.
+      if (!fs.statSync(sourceFullPath).isFile()) {
+        return { reuse: false, reason: `source ${source.path} is not a regular file` };
+      }
+      currentContents = fs.readFileSync(sourceFullPath, 'utf8');
+    } catch {
+      return { reuse: false, reason: `source file ${source.path} is missing or unreadable` };
+    }
+    if (hashEnvSourceContents(currentContents) !== source.contentHash) {
+      return { reuse: false, reason: `source file ${source.path} changed since the blob was created` };
+    }
+  }
+
   // Env drift: if ANY blob config key's ambient value differs from what the parent
   // injected (e.g. `varlock run -- sh -c 'FOO=x node app.js'`, whether or not FOO was
   // already an override at the parent), reusing the blob would clobber FOO back to the

packages/varlock/src/lib/test/injected-env-reuse.test.ts

@@ -6,6 +6,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { evaluateInjectedEnvReuse, USE_INJECTED_ENV_VAR } from '../injected-env-reuse';
 import { encryptEnvBlobSync, generateEncryptionKeyHex } from '../../runtime/crypto';
+import { hashEnvSourceContents } from '../env-source-fingerprint';
 
 let tempDir: string;
 
@@ -157,6 +158,113 @@ describe('evaluateInjectedEnvReuse', () => {
       });
     });
 
+    describe('source file drift', () => {
+      // writes a real env file into tempDir and returns the blob source entry describing it
+      function writeSourceFile(fileName: string, contents: string) {
+        fs.writeFileSync(path.join(tempDir, fileName), contents);
+        return {
+          type: 'dotenv', label: fileName, enabled: true, path: fileName, contentHash: hashEnvSourceContents(contents),
+        };
+      }
+
+      test('reuses when all enabled source files are unchanged', () => {
+        const source = writeSourceFile('.env', 'FOO=foo-val\n');
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }) },
+          cwd: tempDir,
+        });
+        expect(decision.reuse).toBe(true);
+      });
+
+      test('does not reuse when a source file was edited after the blob was created', () => {
+        const source = writeSourceFile('.env', 'FOO=foo-val\n');
+        fs.writeFileSync(path.join(tempDir, '.env'), 'FOO=edited-val\n');
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }) },
+          cwd: tempDir,
+        });
+        expect(decision).toMatchObject({ reuse: false, reason: expect.stringContaining('changed since') });
+      });
+
+      test('does not reuse when a source file is missing', () => {
+        const source = writeSourceFile('.env', 'FOO=foo-val\n');
+        fs.unlinkSync(path.join(tempDir, '.env'));
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }) },
+          cwd: tempDir,
+        });
+        expect(decision).toMatchObject({ reuse: false, reason: expect.stringContaining('missing') });
+      });
+
+      test('does not reuse when a source path is no longer a regular file', () => {
+        const source = writeSourceFile('.env', 'FOO=foo-val\n');
+        fs.unlinkSync(path.join(tempDir, '.env'));
+        fs.mkdirSync(path.join(tempDir, '.env'));
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }) },
+          cwd: tempDir,
+        });
+        expect(decision.reuse).toBe(false);
+      });
+
+      test('does not reuse when an enabled file source has no fingerprint (older producer)', () => {
+        const source = writeSourceFile('.env', 'FOO=foo-val\n');
+        delete (source as any).contentHash;
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }) },
+          cwd: tempDir,
+        });
+        expect(decision).toMatchObject({ reuse: false, reason: expect.stringContaining('fingerprint') });
+      });
+
+      test('an unchanged disabled source does not block reuse', () => {
+        const source = writeSourceFile('.env.production', '# @disable\nFOO=prod-val\n');
+        source.enabled = false;
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }) },
+          cwd: tempDir,
+        });
+        expect(decision.reuse).toBe(true);
+      });
+
+      test('a changed disabled source blocks reuse (editing can remove @disable)', () => {
+        const source = writeSourceFile('.env.production', '# @disable\nFOO=prod-val\n');
+        source.enabled = false;
+        fs.writeFileSync(path.join(tempDir, '.env.production'), 'FOO=prod-val\n');
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }) },
+          cwd: tempDir,
+        });
+        expect(decision).toMatchObject({ reuse: false, reason: expect.stringContaining('changed since') });
+      });
+
+      test('non-file sources (no path) are skipped', () => {
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [{ type: 'processEnv', label: 'process env', enabled: true }] }) },
+          cwd: tempDir,
+        });
+        expect(decision.reuse).toBe(true);
+      });
+
+      test('does not reuse a blob with no sources array recorded', () => {
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: undefined }) },
+          cwd: tempDir,
+        });
+        expect(decision).toMatchObject({ reuse: false, reason: expect.stringContaining('sources') });
+      });
+
+      test('forced mode ignores source drift (sandbox blobs have no local files)', () => {
+        const source = writeSourceFile('.env', 'FOO=foo-val\n');
+        fs.writeFileSync(path.join(tempDir, '.env'), 'FOO=edited-val\n');
+        const decision = evaluateInjectedEnvReuse({
+          env: { __VARLOCK_ENV: makeBlob({ sources: [source] }), [USE_INJECTED_ENV_VAR]: '1' },
+          cwd: tempDir,
+        });
+        expect(decision.reuse).toBe(true);
+      });
+    });
+
     describe('override drift', () => {
       test('reuses when override values still match', () => {
         const decision = evaluateInjectedEnvReuse({