@arki/env 0.0.9 → 0.2.0

package/src/node/codec.ts

@@ -0,0 +1,220 @@
+/**
+ * The dotenvx 2.x file format: parse and edit `.env` text without losing a byte of the lines you
+ * did not touch, and encrypt or decrypt one value.
+ *
+ * A value is encrypted as `encrypted:` + base64 of ECIES over secp256k1 (HKDF-SHA256, AES-256-GCM,
+ * an ephemeral key per value), exactly what `eciesjs` produces with its defaults. The same bytes are
+ * what dotenvx writes, so files move freely between `dot env` and the `dotenvx` CLI.
+ */
+import { Buffer } from 'node:buffer';
+import { decrypt, encrypt, PrivateKey } from 'eciesjs';
+import { Config } from 'eciesjs/config';
+
+import { attempt, isFailure } from '@arki/failure';
+import { ensure } from '@arki/schema';
+
+import type { EnvPrivateKey, EnvPublicKey } from './key-schemas.js';
+import { ENCRYPTED_PREFIX } from '../core/define-env.js';
+import { DecryptionFailed, EncryptionFailed, KeyGenerationFailed, UnrepresentableValue } from './errors.js';
+import { envPrivateKeySchema, envPublicKeySchema } from './key-schemas.js';
+
+export { ENCRYPTED_PREFIX } from '../core/define-env.js';
+
+/** Pinned so a process that changes the global `ECIES_CONFIG` cannot change our bytes. */
+const DOTENVX_ECIES = new Config();
+
+const KEY_PATTERN = /^[ \t]*(?:export[ \t]+)?([\w.-]+)[ \t]*=(.*)$/;
+const QUOTES = ['"', "'", '`'] as const;
+
+/** One `KEY=value` assignment: its decoded value and the lines it spans (`end` exclusive). */
+export type EnvEntry = {
+  readonly key: string;
+  readonly value: string;
+  readonly start: number;
+  readonly end: number;
+};
+
+/** A parsed `.env` file: its lines as written, and every assignment in order. */
+export type EnvDocument = {
+  readonly lines: readonly string[];
+  readonly entries: readonly EnvEntry[];
+};
+
+/** A keypair as dotenvx writes it: a compressed public key (66 hex chars), a private key (64). */
+export type EnvKeypair = { readonly publicKey: EnvPublicKey; readonly privateKey: EnvPrivateKey };
+
+/**
+ * Parse `.env` text the way `dotenv` reads it: `export` prefixes, `#` comments, single, double and
+ * backtick quotes, multi-line quoted values, and `\n` / `\r` expanded inside double quotes. An
+ * unquoted value ends at the first `#`. A key that appears twice keeps both entries; readers take the
+ * last one, as dotenv does.
+ */
+export function parseEnv(text: string): EnvDocument {
+  const lines = text.replaceAll('\r\n', '\n').split('\n');
+  const entries: EnvEntry[] = [];
+  for (let index = 0; index < lines.length; index++) {
+    const match = KEY_PATTERN.exec(lines[index] ?? '');
+    if (match === null) continue;
+    const key = match[1] ?? '';
+    let raw = (match[2] ?? '').trimStart();
+    const start = index;
+    const quote = QUOTES.find(candidate => raw.startsWith(candidate));
+    if (quote !== undefined) {
+      while (closingQuote(raw, quote) === -1 && index + 1 < lines.length) {
+        index++;
+        raw += `\n${lines[index] ?? ''}`;
+      }
+    }
+    entries.push({ key, value: decodeValue(raw, quote), start, end: index + 1 });
+  }
+  return { lines, entries };
+}
+
+/** The last value of `key`, or `undefined`. */
+export function readEnvValue(document: EnvDocument, key: string): string | undefined {
+  return document.entries.findLast(entry => entry.key === key)?.value;
+}
+
+/** Every key with its last value, in first-seen order. */
+export function envValues(document: EnvDocument): Map<string, EnvEntry> {
+  const values = new Map<string, EnvEntry>();
+  for (const entry of document.entries) values.set(entry.key, entry);
+  return values;
+}
+
+/**
+ * The text with `key` set to `value`. An existing assignment (the last one) is rewritten in place;
+ * a new key is appended. Every other line is kept as written.
+ */
+export function setEnvValue(text: string, key: string, value: string) {
+  const document = parseEnv(text);
+  const encoded = encodeValue(value);
+  if (isFailure(encoded)) return encoded;
+  const line = `${key}=${encoded}`;
+  const existing = document.entries.findLast(entry => entry.key === key);
+  if (existing === undefined) {
+    const body = document.lines.join('\n');
+    const separator = body === '' || body.endsWith('\n') ? '' : '\n';
+    return `${body}${separator}${line}\n`;
+  }
+  return [...document.lines.slice(0, existing.start), line, ...document.lines.slice(existing.end)].join('\n');
+}
+
+/** The text without any assignment of `key`. */
+export function removeEnvValue(text: string, key: string): string {
+  const document = parseEnv(text);
+  const dropped = new Set<number>();
+  for (const entry of document.entries) {
+    if (entry.key !== key) continue;
+    for (let line = entry.start; line < entry.end; line++) dropped.add(line);
+  }
+  return document.lines.filter((_, index) => !dropped.has(index)).join('\n');
+}
+
+/** True for a value written by {@link encryptValue} (or by dotenvx). */
+export function isEncrypted(value: string): boolean {
+  return value.startsWith(ENCRYPTED_PREFIX);
+}
+
+/** Encrypt `value` to a compressed or uncompressed secp256k1 public key (hex). */
+export function encryptValue(value: string, publicKey: EnvPublicKey) {
+  return attempt(
+    () => {
+      const sealed = encrypt(publicKey, new TextEncoder().encode(value), DOTENVX_ECIES);
+      return `${ENCRYPTED_PREFIX}${Buffer.from(sealed).toString('base64')}`;
+    },
+    cause => EncryptionFailed({ cause }),
+  );
+}
+
+/** Decrypt authenticated UTF-8, or return DecryptionFailed when the ciphertext/key does not match. */
+export function decryptValue(value: string, privateKey: EnvPrivateKey) {
+  if (!isEncrypted(value)) return DecryptionFailed();
+  return attempt(
+    () => {
+      const sealed = Buffer.from(value.slice(ENCRYPTED_PREFIX.length), 'base64');
+      return new TextDecoder('utf-8', { fatal: true }).decode(decrypt(privateKey, sealed, DOTENVX_ECIES));
+    },
+    cause => DecryptionFailed({ cause }),
+  );
+}
+
+/** A new random keypair. */
+export function generateKeypair() {
+  return attempt(
+    () => {
+      const secret = new PrivateKey(undefined, DOTENVX_ECIES.ellipticCurve);
+      return {
+        publicKey: ensure(secret.publicKey.toHex(true), envPublicKeySchema),
+        privateKey: ensure(secret.toHex(), envPrivateKeySchema),
+      } satisfies EnvKeypair;
+    },
+    cause => KeyGenerationFailed({ cause }),
+  );
+}
+
+/** The compressed public key of an already validated private key. */
+export function publicKeyOf(privateKey: EnvPrivateKey): EnvPublicKey {
+  return ensure(PrivateKey.fromHex(privateKey, DOTENVX_ECIES.ellipticCurve).publicKey.toHex(true), envPublicKeySchema);
+}
+
+/**
+ * The key names dotenvx uses for a file: `.env` → `DOTENV_PUBLIC_KEY` / `DOTENV_PRIVATE_KEY`,
+ * `.env.production` → `..._PRODUCTION`, `.env.ci.local` → `..._CI_LOCAL`.
+ */
+export function keyNamesFor(fileName: string): { readonly publicKey: string; readonly privateKey: string } {
+  const base = fileName.toLowerCase().replace(/\.txt$/, '');
+  const suffix = base.startsWith('.env.')
+    ? `_${base
+        .slice('.env.'.length)
+        .replaceAll(/[^a-z0-9]+/g, '_')
+        .toUpperCase()}`
+    : '';
+  return { publicKey: `DOTENV_PUBLIC_KEY${suffix}`, privateKey: `DOTENV_PRIVATE_KEY${suffix}` };
+}
+
+/** True for the `DOTENV_PUBLIC_KEY*` / `DOTENV_PRIVATE_KEY*` names, which are never app values. */
+export function isKeyName(key: string): boolean {
+  return key.startsWith('DOTENV_PUBLIC_KEY') || key.startsWith('DOTENV_PRIVATE_KEY');
+}
+
+/** The dotenvx header for a file: banner, public key, and a `# <file>` line. */
+export function envHeader(fileName: string, publicKey: EnvPublicKey): string {
+  return [
+    '#/-------------------[DOTENV_PUBLIC_KEY]--------------------/',
+    '#/            public-key encryption for .env files          /',
+    '#/       [how it works](https://dotenvx.com/encryption)     /',
+    '#/----------------------------------------------------------/',
+    `${keyNamesFor(fileName).publicKey}="${publicKey}"`,
+    '',
+    `# ${fileName}`,
+  ].join('\n');
+}
+
+function closingQuote(raw: string, quote: string): number {
+  for (let index = 1; index < raw.length; index++) {
+    if (raw[index] === quote && raw[index - 1] !== '\\') return index;
+  }
+  return -1;
+}
+
+function decodeValue(raw: string, quote: string | undefined): string {
+  if (quote === undefined) return raw.split('#')[0]?.trim() ?? '';
+  const close = closingQuote(raw, quote);
+  const inner = close === -1 ? raw.slice(1) : raw.slice(1, close);
+  return quote === '"' ? inner.replaceAll('\\n', '\n').replaceAll('\\r', '\r') : inner;
+}
+
+/**
+ * The first quoting that reads back as exactly `value`, in one entry: double quotes (newlines as
+ * `\n`), then single, then backticks. A value no quoting can carry (it holds every quote character
+ * and a line break, say) is refused rather than written in a form that could inject other keys.
+ */
+function encodeValue(value: string) {
+  const candidates = [`"${value.replaceAll('\r', '\\r').replaceAll('\n', '\\n')}"`, `'${value}'`, `\`${value}\``];
+  for (const candidate of candidates) {
+    const document = parseEnv(`K=${candidate}`);
+    if (document.entries.length === 1 && document.entries[0]?.value === value) return candidate;
+  }
+  return UnrepresentableValue();
+}

package/src/node/edit.ts

@@ -0,0 +1,279 @@
+/**
+ * File edits behind `dot env init | set | encrypt | decrypt | rotate`. Each write goes to a temp file
+ * first and is renamed into place, so an interrupted command never leaves half a file.
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { InvalidInput, isFailure } from '@arki/failure';
+
+import type { EnvPrivateKey, EnvPublicKey } from './key-schemas.js';
+import {
+  decryptValue,
+  encryptValue,
+  envHeader,
+  envValues,
+  generateKeypair,
+  isEncrypted,
+  isKeyName,
+  keyNamesFor,
+  parseEnv,
+  publicKeyOf,
+  readEnvValue,
+  setEnvValue,
+} from './codec.js';
+import {
+  DecryptionFailed,
+  FileWriteFailed,
+  MissingPrivateKey,
+  MissingPublicKey,
+  RotationIncomplete,
+} from './errors.js';
+import { readEnvText, writeEnvText } from './files.js';
+import { parsePublicKey } from './key-schemas.js';
+import { findPrivateKey, KEYS_FILE, keysFileCandidates, writePrivateKey } from './keys.js';
+import { nodeOperation } from './operation-telemetry.js';
+
+/** The public key in a file's header, or `undefined` when it has none. */
+export function publicKeyIn(file: string) {
+  if (!existsSync(file)) return;
+  const text = readEnvText(file);
+  if (isFailure(text)) return text;
+  const key = readEnvValue(parseEnv(text), keyNamesFor(path.basename(file)).publicKey);
+  if (key === undefined) return;
+  return parsePublicKey(key);
+}
+
+/** What `initEnvFile` did. */
+export type InitResult = {
+  readonly file: string;
+  readonly publicKey: EnvPublicKey;
+  /** `false` when the file already had a header. */
+  readonly headerAdded: boolean;
+  /** Where a new private key was written; `undefined` when an existing key was reused. */
+  readonly keysWritten?: string;
+};
+
+/**
+ * Give `file` a dotenvx header, creating the file if needed. Reuses the private key of the same
+ * environment when one is already reachable (so every `.env.development` in a repo shares one key);
+ * otherwise generates a keypair and stores the private key in `<root>/.env.keys`.
+ */
+export function initEnvFile(
+  file: string,
+  options: { readonly root: string; readonly env?: Readonly<Record<string, string | undefined>> },
+) {
+  return nodeOperation('init', () => {
+    const existing = publicKeyIn(file);
+    if (isFailure(existing)) return existing;
+    if (existing !== undefined) return { file, publicKey: existing, headerAdded: false } satisfies InitResult;
+    const names = keyNamesFor(path.basename(file));
+    const found = findPrivateKey(file, { root: options.root, env: options.env ?? process.env });
+    if (isFailure(found)) return found;
+    const reused = found?.keys[0];
+    let publicKey: EnvPublicKey;
+    let keysWritten: string | undefined;
+    if (reused === undefined) {
+      const pair = generateKeypair();
+      if (isFailure(pair)) return pair;
+      keysWritten = path.join(options.root, KEYS_FILE);
+      const written = writePrivateKey(keysWritten, names.privateKey, pair.privateKey, path.basename(file));
+      if (isFailure(written)) return written;
+      publicKey = pair.publicKey;
+    } else {
+      publicKey = publicKeyOf(reused);
+    }
+    const body = existsSync(file) ? readEnvText(file) : '';
+    if (isFailure(body)) return body;
+    const written = writeEnvText(file, `${envHeader(path.basename(file), publicKey)}\n${body}`);
+    if (isFailure(written)) return written;
+    return keysWritten === undefined
+      ? { file, publicKey, headerAdded: true }
+      : { file, publicKey, headerAdded: true, keysWritten };
+  });
+}
+
+/**
+ * Set `key` in `file`, encrypted to the file's public key unless `plain`. Returns `false` when the
+ * file already held exactly this plaintext value (an encrypted value is always rewritten, because
+ * the same plaintext never encrypts to the same bytes).
+ */
+export function setEnvFileValue(file: string, key: string, value: string, options: { readonly plain: boolean }) {
+  return nodeOperation('set', () => {
+    const text = existsSync(file) ? readEnvText(file) : '';
+    if (isFailure(text)) return text;
+    let stored = value;
+    if (!options.plain) {
+      const publicKey = readEnvValue(parseEnv(text), keyNamesFor(path.basename(file)).publicKey);
+      if (publicKey === undefined) return MissingPublicKey({ file });
+      const parsedKey = parsePublicKey(publicKey);
+      if (isFailure(parsedKey)) return parsedKey;
+      const encrypted = encryptValue(value, parsedKey);
+      if (isFailure(encrypted)) return encrypted;
+      stored = encrypted;
+    }
+    const next = setEnvValue(text, key, stored);
+    if (isFailure(next)) return next;
+    if (next === text) return false;
+    const written = writeEnvText(file, next);
+    return isFailure(written) ? written : true;
+  });
+}
+
+/** Encrypt plaintext values in place: the listed keys, or every value. Returns the keys encrypted. */
+export function encryptEnvFile(file: string, keys?: readonly string[]) {
+  return nodeOperation('encrypt_file', () => {
+    const text = readEnvText(file);
+    if (isFailure(text)) return text;
+    const publicKey = readEnvValue(parseEnv(text), keyNamesFor(path.basename(file)).publicKey);
+    if (publicKey === undefined) return MissingPublicKey({ file });
+    const parsedKey = parsePublicKey(publicKey);
+    if (isFailure(parsedKey)) return parsedKey;
+    let next = text;
+    const done: string[] = [];
+    for (const [key, entry] of envValues(parseEnv(text))) {
+      if (isKeyName(key) || isEncrypted(entry.value) || (keys !== undefined && !keys.includes(key))) continue;
+      const encrypted = encryptValue(entry.value, parsedKey);
+      if (isFailure(encrypted)) return encrypted;
+      const updated = setEnvValue(next, key, encrypted);
+      if (isFailure(updated)) return updated;
+      next = updated;
+      done.push(key);
+    }
+    if (done.length > 0) {
+      const written = writeEnvText(file, next);
+      if (isFailure(written)) return written;
+    }
+    return done;
+  });
+}
+
+/** Decrypt values in place with `privateKeys`: the listed keys, or every value. Returns the keys decrypted. */
+export function decryptEnvFile(file: string, privateKeys: readonly EnvPrivateKey[], keys?: readonly string[]) {
+  return nodeOperation('decrypt_file', () => {
+    const text = readEnvText(file);
+    if (isFailure(text)) return text;
+    let next = text;
+    const done: string[] = [];
+    for (const [key, entry] of envValues(parseEnv(text))) {
+      if (!isEncrypted(entry.value) || (keys !== undefined && !keys.includes(key))) continue;
+      const decrypted = decryptWithAny(entry.value, privateKeys);
+      if (isFailure(decrypted)) return decrypted;
+      const updated = setEnvValue(next, key, decrypted);
+      if (isFailure(updated)) return updated;
+      next = updated;
+      done.push(key);
+    }
+    if (done.length > 0) {
+      const written = writeEnvText(file, next);
+      if (isFailure(written)) return written;
+    }
+    return done;
+  });
+}
+
+/** What `rotateEnvFiles` did. */
+export type RotateResult = {
+  readonly privateKeyName: string;
+  readonly files: readonly { readonly file: string; readonly values: number }[];
+  /** Where the new private key was written. */
+  readonly keysFile: string;
+};
+
+/**
+ * Re-encrypt every file of one environment to a new keypair, in one step: decrypt everything first
+ * (so a wrong key changes nothing), then write each file, then the new private key. All `files` must
+ * share a file name (`.env.production`), because they share a key name.
+ */
+export function rotateEnvFiles(
+  files: readonly string[],
+  options: { readonly root: string; readonly env?: Readonly<Record<string, string | undefined>> },
+) {
+  const first = files[0];
+  if (first === undefined) return InvalidInput({ issues: [{ message: 'No files to rotate.' }] });
+  const names = keyNamesFor(path.basename(first));
+  if (files.some(file => keyNamesFor(path.basename(file)).privateKey !== names.privateKey)) {
+    return InvalidInput({ issues: [{ message: 'Rotate takes files of one environment at a time.' }] });
+  }
+  return nodeOperation('rotate', () => {
+    const pair = generateKeypair();
+    if (isFailure(pair)) return pair;
+    const previousKeys = new Set<EnvPrivateKey>();
+    const keysFile = path.join(options.root, KEYS_FILE);
+    const keyStores = new Set([keysFile]);
+    const plans: { file: string; next: string; values: number }[] = [];
+    for (const file of files) {
+      for (const candidate of keysFileCandidates(file, options.root)) {
+        if (existsSync(candidate)) keyStores.add(candidate);
+      }
+      const text = readEnvText(file);
+      if (isFailure(text)) return text;
+      const found = findPrivateKey(file, { root: options.root, env: options.env ?? process.env });
+      if (isFailure(found)) return found;
+      for (const key of found?.keys ?? []) previousKeys.add(key);
+      let next = text;
+      let values = 0;
+      for (const [key, entry] of envValues(parseEnv(text))) {
+        let value: string;
+        if (key === names.publicKey) value = pair.publicKey;
+        else if (isEncrypted(entry.value)) {
+          if (found === undefined) return MissingPrivateKey({ file });
+          const decrypted = decryptWithAny(entry.value, found.keys);
+          if (isFailure(decrypted)) return decrypted;
+          const encrypted = encryptValue(decrypted, pair.publicKey);
+          if (isFailure(encrypted)) return encrypted;
+          value = encrypted;
+          values++;
+        } else continue;
+        const updated = setEnvValue(next, key, value);
+        if (isFailure(updated)) return updated;
+        next = updated;
+      }
+      if (readEnvValue(parseEnv(text), names.publicKey) === undefined)
+        next = `${envHeader(path.basename(file), pair.publicKey)}\n${next}`;
+      plans.push({ file, next, values });
+    }
+    // Persist both generations BEFORE any ciphertext changes. An interruption at any later point
+    // leaves every old/new file recoverable from this key store, including a partial rotation.
+    for (const store of keyStores) {
+      const staged = writePrivateKey(store, names.privateKey, pair.privateKey, path.basename(first), {
+        preserve: [...previousKeys],
+      });
+      if (isFailure(staged)) return staged;
+    }
+    let completedFiles = 0;
+    for (const plan of plans) {
+      const written = writeEnvText(plan.file, plan.next);
+      if (isFailure(written))
+        return RotationIncomplete({ keysFile, completedFiles, totalFiles: plans.length }, { cause: written });
+      completedFiles++;
+    }
+    // Do not retire the old generation until every committed file reads back exactly as planned.
+    for (const plan of plans) {
+      const confirmed = readEnvText(plan.file);
+      if (isFailure(confirmed) || confirmed !== plan.next)
+        return RotationIncomplete(
+          { keysFile, completedFiles, totalFiles: plans.length },
+          { cause: isFailure(confirmed) ? confirmed : FileWriteFailed({ file: plan.file }) },
+        );
+    }
+    for (const store of keyStores) {
+      const finalized = writePrivateKey(store, names.privateKey, pair.privateKey, path.basename(first));
+      if (isFailure(finalized))
+        return RotationIncomplete({ keysFile, completedFiles, totalFiles: plans.length }, { cause: finalized });
+    }
+    return {
+      privateKeyName: names.privateKey,
+      files: plans.map(({ file, values }) => ({ file, values })),
+      keysFile,
+    } satisfies RotateResult;
+  });
+}
+
+function decryptWithAny(value: string, privateKeys: readonly EnvPrivateKey[]) {
+  for (const privateKey of privateKeys) {
+    const decrypted = decryptValue(value, privateKey);
+    if (!isFailure(decrypted)) return decrypted;
+  }
+  return DecryptionFailed();
+}

package/src/node/errors.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+
+import { defineFailure } from '@arki/failure';
+
+/** A dotenv value has no lossless quoting.
+ * @fix Use encryption or a value supported by dotenv quoting.
+ * @verify bun run test
+ */
+export const UnrepresentableValue = defineFailure('env.unrepresentable_value', {
+  message: 'The value cannot be stored losslessly in dotenv text',
+  status: 422,
+  remediation: 'Encrypt the value or remove the unsupported combination of quotes and line breaks.',
+});
+/** Cryptographic encryption failed.
+ * @fix Verify the public key and runtime crypto support.
+ * @verify bun run test
+ */
+export const EncryptionFailed = defineFailure('env.encryption_failed', {
+  message: 'Cannot encrypt the env value',
+  status: 500,
+  remediation: 'Verify the public key and runtime crypto support.',
+});
+/** Ciphertext authentication or decoding failed.
+ * @fix Restore the correct private key or reset the damaged value.
+ * @verify bun run test
+ */
+export const DecryptionFailed = defineFailure('env.decryption_failed', {
+  message: 'Cannot decrypt the env value',
+  status: 422,
+  remediation: 'Restore the correct private key or reset the damaged encrypted value.',
+});
+/** The runtime could not generate a keypair.
+ * @fix Restore runtime crypto support.
+ * @verify bun run test
+ */
+export const KeyGenerationFailed = defineFailure('env.key_generation_failed', {
+  message: 'Cannot generate an env keypair',
+  status: 500,
+  remediation: 'Restore runtime crypto support before retrying.',
+});
+/** An env file could not be read.
+ * @fix Check the path, file type and access permissions.
+ * @verify bun run test
+ */
+export const FileReadFailed = defineFailure('env.file_read_failed', {
+  data: z.object({ file: z.string() }),
+  message: 'Cannot read env file {file}',
+  status: 500,
+  remediation: 'Check the file path, type and access permissions.',
+});
+/** An env file could not be replaced.
+ * @fix Check disk space and parent-directory permissions.
+ * @verify bun run test
+ */
+export const FileWriteFailed = defineFailure('env.file_write_failed', {
+  data: z.object({ file: z.string() }),
+  message: 'Cannot write env file {file}',
+  status: 500,
+  remediation: 'Check disk space and parent-directory permissions before retrying.',
+});
+/** The target file has no public key.
+ * @fix Initialize the file before encrypting values.
+ * @verify bun run test
+ */
+export const MissingPublicKey = defineFailure('env.missing_public_key', {
+  data: z.object({ file: z.string() }),
+  message: 'Env file {file} has no public key header',
+  remediation: 'Initialize the file before encrypting values.',
+});
+/** No private key is available.
+ * @fix Restore the environment key from its backup.
+ * @verify bun run test
+ */
+export const MissingPrivateKey = defineFailure('env.missing_private_key', {
+  data: z.object({ file: z.string() }),
+  message: 'No private key is available for {file}',
+  remediation: 'Restore the environment private key from its backup or shell variable.',
+});
+/** Rotation stopped after its recovery keys were saved.
+ * @fix Keep the staged key file and retry rotation.
+ * @verify bun run test
+ */
+export const RotationIncomplete = defineFailure('env.rotation_incomplete', {
+  data: z.object({
+    keysFile: z.string(),
+    completedFiles: z.number().int().nonnegative(),
+    totalFiles: z.number().int().nonnegative(),
+  }),
+  message: 'Env rotation stopped; recovery keys are saved in {keysFile}',
+  status: 500,
+  remediation:
+    'Keep the staged key file: it contains keys for both old and new ciphertext. Repair the filesystem and retry rotation.',
+});
+/** A secret provider rejected a read.
+ * @fix Check the provider CLI installation, login and reference.
+ * @verify bun run test
+ */
+export const ReferenceFailed = defineFailure('env.reference_failed', {
+  data: z.object({ scheme: z.string() }),
+  message: 'Cannot resolve the {scheme} secret reference',
+  status: 502,
+  remediation: 'Check the provider CLI installation, login and reference; inspect the local cause privately.',
+});
+/** Loading was cancelled.
+ * @fix Handle cancellation at the calling boundary.
+ * @verify bun run test
+ */
+export const EnvCancelled = defineFailure('env.cancelled', {
+  message: 'Env loading was cancelled',
+  status: 499,
+  remediation: 'Honor cancellation at the calling boundary.',
+});
+/** The aggregate load deadline elapsed.
+ * @fix Increase the budget or restore provider responsiveness.
+ * @verify bun run test
+ */
+export const EnvDeadline = defineFailure('env.deadline', {
+  message: 'The env loading deadline elapsed',
+  status: 504,
+  remediation: 'Increase the load budget or restore provider responsiveness.',
+});
+
+/** Loader problem codes are derived from their canonical definitions. */
+export const ENV_FILES_ERROR_CODES = {
+  missingPrivateKey: MissingPrivateKey.code,
+  cannotDecrypt: DecryptionFailed.code,
+  unresolvedReference: ReferenceFailed.code,
+  cannotRead: FileReadFailed.code,
+  cancelled: EnvCancelled.code,
+  deadline: EnvDeadline.code,
+} as const;
+const problem = z.object({
+  code: z.enum(Object.values(ENV_FILES_ERROR_CODES)),
+  message: z.string(),
+  file: z.string(),
+  key: z.string().optional(),
+});
+/** One or more env entries could not be loaded. Public data excludes values and raw causes.
+ * @fix Address each named problem before starting the app.
+ * @verify bun run test
+ */
+export const EnvFilesFailed = defineFailure('env.files_failed', {
+  data: z.object({ environment: z.string(), errors: z.array(problem) }),
+  message: 'Cannot load the env files',
+  status: 500,
+  remediation: 'Address each named file/key problem before starting the application.',
+});

package/src/node/files.ts

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { attempt } from '@arki/failure';
+
+import { FileReadFailed, FileWriteFailed } from './errors.js';
+import { nodeOperation } from './operation-telemetry.js';
+
+/** Foreign filesystem errors stay private; public outcomes identify only the file. */
+export function readEnvText(file: string) {
+  return nodeOperation('file.read', () =>
+    attempt(
+      () => readFileSync(file, 'utf8'),
+      error => FileReadFailed({ file }, { cause: error }),
+    ),
+  );
+}
+
+/** Each replacement is atomic; owner-only new files and key stores never follow a planted temp symlink. */
+export function writeEnvText(file: string, text: string, privateFile = false) {
+  return nodeOperation('file.write', () => {
+    let temp: string | undefined;
+    try {
+      const mode = privateFile ? 0o600 : existsSync(file) ? statSync(file).mode & 0o777 : 0o600;
+      temp = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}.tmp`);
+      writeFileSync(temp, text, { flag: 'wx', mode });
+      renameSync(temp, file);
+      return;
+    } catch (error) {
+      if (temp !== undefined) {
+        try {
+          unlinkSync(temp);
+        } catch {
+          /* The failed write may not have created a file. */
+        }
+      }
+      return FileWriteFailed({ file }, { cause: error });
+    }
+  });
+}