configproof 0.3.0

package/fixtures/child-process/parent.cjs

@@ -0,0 +1,5 @@
+const { spawn, fork } = require('node:child_process');
+const path = require('node:path');
+const child = path.join(__dirname, 'child.cjs');
+spawn(process.execPath, [child], { env: { ...process.env, CONFIGTRACE_FIXTURE: 'synthetic-spawn' }, stdio: 'inherit' });
+fork(child, [], { env: { ...process.env, CONFIGTRACE_FIXTURE: 'synthetic-fork' }, stdio: 'inherit' });

package/fixtures/custom-target/app.cjs

@@ -0,0 +1,4 @@
+const target = {};
+require('dotenv').config({ path: require('node:path').join(__dirname, 'sample.env'), processEnv: target, quiet: true });
+void process.env.DATABASE_URL;
+console.log(Object.hasOwn(target, 'DATABASE_URL') ? 'Custom object loaded.' : 'Custom object not loaded.');

package/fixtures/custom-target/sample.env

@@ -0,0 +1 @@
+DATABASE_URL=postgres://fixture:synthetic-only@localhost/intended

package/fixtures/esm/app.mjs

@@ -0,0 +1,5 @@
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'node:url';
+dotenv.config({ path: fileURLToPath(new URL('../stale-inheritance/sample.env', import.meta.url)), quiet: true });
+void process.env.DATABASE_URL;
+console.log('ESM application read.');

package/fixtures/exit-code/app.cjs

@@ -0,0 +1,4 @@
+void process.env.CONFIGTRACE_FIXTURE;
+process.stdout.write('application-stdout\n');
+process.stderr.write('application-stderr\n');
+process.exit(17);

package/fixtures/failure-boundary/app.cjs

@@ -0,0 +1,7 @@
+const { markFailureBoundary } = require('../../dist/runtime/api.js');
+process.env.CONFIGTRACE_FIXTURE = 'synthetic-before-boundary';
+void process.env.CONFIGTRACE_FIXTURE;
+markFailureBoundary();
+process.env.CONFIGTRACE_FIXTURE = 'synthetic-after-boundary';
+void process.env.CONFIGTRACE_FIXTURE;
+process.exitCode = 17;

package/fixtures/load-order/app.cjs

@@ -0,0 +1,9 @@
+const dotenv = require('dotenv');
+const path = require('node:path');
+const first = path.join(__dirname, 'first.env');
+const second = path.join(__dirname, 'second.env');
+dotenv.config({ path: [first, second], quiet: true });
+void process.env.CONFIGTRACE_FIXTURE;
+dotenv.config({ path: second, override: true, quiet: true });
+void process.env.CONFIGTRACE_FIXTURE;
+console.log('Two loader phases completed.');

package/fixtures/load-order/first.env

@@ -0,0 +1 @@
+CONFIGTRACE_FIXTURE=synthetic-first

package/fixtures/load-order/second.env

@@ -0,0 +1 @@
+CONFIGTRACE_FIXTURE=synthetic-second

package/fixtures/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "configtrace-fixtures/1",
+  "validationStatus": "not-run-in-this-delivery",
+  "fixtures": [
+    { "id": "stale-inheritance", "entry": "stale-inheritance/app.cjs", "watch": ["DATABASE_URL"], "expectation": "Existing preload value; dotenv candidate not applied; read links to startup with inferred confidence" },
+    { "id": "runtime-mutation", "entry": "runtime-mutation/app.cjs", "watch": ["CONFIGTRACE_FIXTURE"], "expectation": "Read, write, delete, missing, empty and defineProperty observations" },
+    { "id": "load-order", "entry": "load-order/app.cjs", "watch": ["CONFIGTRACE_FIXTURE"], "expectation": "Two file reads, first-wins merge, then override; merge provenance is inferred" },
+    { "id": "custom-target", "entry": "custom-target/app.cjs", "watch": ["DATABASE_URL"], "expectation": "Custom target warning; no fictitious process.env assignment" },
+    { "id": "child-process", "entry": "child-process/parent.cjs", "watch": ["CONFIGTRACE_FIXTURE"], "expectation": "With --children, root plus direct spawn and fork; no automatic cross-run process matching" },
+    { "id": "worker", "entry": "worker/parent.cjs", "watch": ["CONFIGTRACE_FIXTURE"], "expectation": "One root stream; worker coverage explicitly unsupported" },
+    { "id": "bypass", "entry": "bypass/app.cjs", "watch": ["CONFIGTRACE_FIXTURE"], "expectation": "Load early.cjs before ConfigTrace; original-object write is invisible; mismatched observed read remains unknown" },
+    { "id": "exit-code", "entry": "exit-code/app.cjs", "watch": ["CONFIGTRACE_FIXTURE"], "expectation": "Application stdout, stderr and exit 17 preserved" },
+    { "id": "esm", "entry": "esm/app.mjs", "watch": ["DATABASE_URL"], "expectation": "ESM default import of the cwd-resolved dotenv export receives the adapter" },
+    { "id": "source-map", "entry": "source-map/input.ts", "watch": ["DATABASE_URL"], "expectation": "After separately compiling this fixture, --source-maps maps the read to input.ts line 3" }
+  ]
+}

package/fixtures/native-env/app.cjs

@@ -0,0 +1,6 @@
+const path = require('node:path');
+const before = process.env.CONFIGTRACE_FIXTURE;
+process.loadEnvFile(path.join(__dirname, 'sample.env'));
+const after = process.env.CONFIGTRACE_FIXTURE;
+// No raw values in fixture output.
+console.log(JSON.stringify({ beforePresent: before !== undefined, afterPresent: after !== undefined }));

package/fixtures/native-env/failure.cjs

@@ -0,0 +1,4 @@
+const path = require('node:path');
+try { process.loadEnvFile(path.join(__dirname, 'does-not-exist.env')); }
+catch (error) { console.log(JSON.stringify({ nativeErrorPreserved: error.code === 'ENOENT' })); }
+void process.env.CONFIGTRACE_FIXTURE;

package/fixtures/native-env/sample.env

@@ -0,0 +1 @@
+CONFIGTRACE_FIXTURE=synthetic-native-env-value

package/fixtures/native-env/startup.cjs

@@ -0,0 +1,2 @@
+const value = process.env.CONFIGTRACE_FIXTURE;
+console.log(JSON.stringify({ present: value !== undefined }));

package/fixtures/runtime-mutation/app.cjs

@@ -0,0 +1,12 @@
+void process.env.CONFIGTRACE_FIXTURE;
+process.env.CONFIGTRACE_FIXTURE = 'synthetic-replacement';
+void process.env.CONFIGTRACE_FIXTURE;
+delete process.env.CONFIGTRACE_FIXTURE;
+void process.env.CONFIGTRACE_FIXTURE;
+process.env.CONFIGTRACE_FIXTURE = '';
+void process.env.CONFIGTRACE_FIXTURE;
+Object.defineProperty(process.env, 'CONFIGTRACE_FIXTURE', {
+  value: 'synthetic-definition', writable: true, configurable: true, enumerable: true,
+});
+void process.env.CONFIGTRACE_FIXTURE;
+console.log('Mutation fixture completed.');

package/fixtures/source-map/input.ts

@@ -0,0 +1,5 @@
+// Compile this fixture separately when validating source-map attribution.
+export function configuredEndpoint(): string | undefined {
+  return process.env.DATABASE_URL;
+}
+console.log(configuredEndpoint() ? 'Configured.' : 'Missing.');

package/fixtures/source-map/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "CommonJS", "strict": true,
+    "outDir": "generated", "sourceMap": true, "types": ["node"], "skipLibCheck": true
+  },
+  "include": ["input.ts"]
+}

package/fixtures/stale-inheritance/app.cjs

@@ -0,0 +1,4 @@
+const path = require('node:path');
+require('dotenv').config({ path: path.join(__dirname, 'sample.env'), quiet: true });
+const endpoint = process.env.DATABASE_URL;
+console.log(endpoint ? 'Database endpoint configured.' : 'No database endpoint.');

package/fixtures/stale-inheritance/sample.env

@@ -0,0 +1 @@
+DATABASE_URL=postgres://fixture:synthetic-only@localhost/intended

package/fixtures/v03-manifest.json

@@ -0,0 +1,32 @@
+{
+  "version": "0.3.0",
+  "validation": "not-run",
+  "fixtures": [
+    {
+      "name": "native-env",
+      "cases": [
+        "runtime apply",
+        "startup option declaration",
+        "existing-key skip inference",
+        "preserved native exception"
+      ]
+    },
+    {
+      "name": "worker-modes",
+      "cases": [
+        "copied",
+        "explicit",
+        "SHARE_ENV",
+        "execArgv override"
+      ]
+    },
+    {
+      "name": "failure-boundary",
+      "cases": [
+        "manual marker",
+        "post-marker reads",
+        "preserved exit 17"
+      ]
+    }
+  ]
+}

package/fixtures/worker/parent.cjs

@@ -0,0 +1,3 @@
+const { Worker } = require('node:worker_threads');
+void process.env.CONFIGTRACE_FIXTURE;
+new Worker(require('node:path').join(__dirname, 'worker.cjs'));

package/fixtures/worker/worker.cjs

@@ -0,0 +1,2 @@
+void process.env.CONFIGTRACE_FIXTURE;
+console.log('Worker read is intentionally outside ConfigTrace coverage.');

package/fixtures/worker-modes/parent.cjs

@@ -0,0 +1,17 @@
+const { Worker, SHARE_ENV } = require('node:worker_threads');
+const path = require('node:path');
+function once(mode, env) {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(path.join(__dirname, 'worker.cjs'), { env, workerData: { mode }, execArgv: [] });
+    worker.once('error', reject);
+    worker.once('exit', code => code === 0 ? resolve() : reject(new Error('Fixture worker failed')));
+  });
+}
+(async () => {
+  process.env.CONFIGTRACE_FIXTURE = 'synthetic-parent-value';
+  await once('copied', undefined);
+  await once('explicit', { CONFIGTRACE_FIXTURE: 'synthetic-explicit-value' });
+  await once('shared', SHARE_ENV);
+  const sharedWriteVisible = process.env.CONFIGTRACE_FIXTURE === 'synthetic-shared-value';
+  console.log(JSON.stringify({ sharedWriteVisible }));
+})().catch(() => { process.exitCode = 1; });

package/fixtures/worker-modes/worker.cjs

@@ -0,0 +1,4 @@
+const { workerData } = require('node:worker_threads');
+const value = process.env.CONFIGTRACE_FIXTURE;
+if (workerData.mode === 'shared') process.env.CONFIGTRACE_FIXTURE = 'synthetic-shared-value';
+void value;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "configproof",
+  "version": "0.3.0",
+  "description": "Local-first configuration provenance, runtime contracts, deterministic diagnosis, and read-only agent evidence for Node.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonusharma26/configtrace.git"
+  },
+  "homepage": "https://github.com/sonusharma26/configtrace#readme",
+  "bugs": {
+    "url": "https://github.com/sonusharma26/configtrace/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "configtrace": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./preload": "./dist/runtime/preload.js",
+    "./adapter-api": {
+      "types": "./dist/runtime/api.d.ts",
+      "default": "./dist/runtime/api.js"
+    }
+  },
+  "files": [
+    "dist",
+    "fixtures",
+    "policies",
+    "README.md",
+    "LICENSE",
+    "docs/ARCHITECTURE.md",
+    "docs/COMPATIBILITY.md",
+    "docs/PRIVACY.md",
+    "docs/VALIDATION.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0 <23 || >=24 <25"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test tests/*.test.cjs",
+    "demo": "node dist/cli.js demo stale-env",
+    "clean": "node scripts/clean.cjs"
+  },
+  "dependencies": {
+    "zod": "^3.25.76",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "dotenv": "17.2.3",
+    "typescript": "^5.9.3"
+  }
+}

package/policies/configtrace-policy.yaml

@@ -0,0 +1,23 @@
+# Configuration verification contract, not an export policy.
+version: 1
+coverage:
+  requireComplete: true
+  maxDroppedEvents: 0
+  requireFeatures:
+    - environment
+rules:
+  DATABASE_URL:
+    required: true
+    read: required
+    immutableAfterFirstRead: true
+    minimumConfidence: inferred
+    allowedOrigins:
+      - startup
+      - "dotenv:.env.production"
+      - "native-env:.env.production"
+  NODE_ENV:
+    required: true
+  "TEMP_*":
+    read: forbidden
+# Replace these example keys/origins with your application's captured identities.
+# A wildcard with no captured matches is inconclusive, not a passing absence check.

package/policies/issue-share.yaml

@@ -0,0 +1,12 @@
+# Less restrictive than the built-in default, which pseudonymizes ALL key names.
+# Review project filenames and the remaining key names before sharing.
+paths: basename
+keys:
+  redact:
+    - "CUSTOMER_*"
+    - "INTERNAL_*"
+include:
+  callSites: true
+  loaders: true
+  comparisons: true
+metadata: minimal

package/policies/minimal.yaml

@@ -0,0 +1,8 @@
+paths: omit
+keys:
+  redact: ["*"]
+include:
+  callSites: false
+  loaders: true
+  comparisons: true
+metadata: minimal