@arki/env 0.0.9 → 0.2.0

package/docs/upgrades/0.1.0-to-0.2.0.md

@@ -0,0 +1,73 @@
+# Upgrade 0.1.0 to 0.2.0
+
+## The Dot adapter moved to `@arki/dot/env`
+
+`@arki/env/dot` is gone. `@arki/env` no longer lists `@arki/dot` as a peer; `@arki/dot` now depends on `@arki/env`.
+
+Before:
+
+```ts skip="import path removed in 0.2.0"
+import { env } from '@arki/env/dot';
+```
+
+After:
+
+```ts skip="needs a Dot app"
+import { env } from '@arki/dot/env';
+```
+
+`env()`, `ENV_PLUGIN_ERROR_CODES`, `EnvDotOptions` and `EnvServices` are unchanged. `ARKI_ENV_PLUGIN_E001` keeps its code.
+
+## `contracts` is now `presets`
+
+`@arki/env/contracts` is now `@arki/env/presets`. In Arki, `./contract` names the browser-safe entry for oRPC contracts (A-41), and these are ready-made variable validators, so they took a name that says that. The validators themselves are unchanged.
+
+| Before | After |
+| --- | --- |
+| `@arki/env/contracts` | `@arki/env/presets` |
+| `contracts` (also from `@arki/env` and `@arki/env/core`) | `presets` |
+| `commonContracts`, `urlContracts`, `parseContracts` | `commonPresets`, `urlPresets`, `parsePresets` |
+
+Before:
+
+```ts skip="import path removed in 0.2.0"
+import { contracts } from '@arki/env/contracts';
+
+const port = contracts.port(3000);
+```
+
+After:
+
+```ts
+import { presets } from '@arki/env/presets';
+
+const port = presets.port(3000);
+```
+
+## `formatIssues` is public
+
+`@arki/env/core` now exports `formatIssues(name, issues)`, the formatter `defineEnv` uses for its error message, so adapters can build the same message.
+
+## Encrypted env files replace `dotenv-cli`
+
+New `@arki/env/node` loads committed `.env.<environment>` files with encrypted values. Apps load them with `dot env run --` (from `@arki/dot`) or `import '@arki/env/node/register'`.
+
+Before (`package.json`):
+
+```json
+{ "scripts": { "with-env": "dotenv -e ../../../.env -e ../.env --" } }
+```
+
+After:
+
+```json
+{ "scripts": { "with-env": "dot env run --" } }
+```
+
+Remove `dotenv-cli` and add `@arki/dot` as a dev dependency. Turn an old `.env` into an encrypted file with `dot env encrypt --from .env --all`. Then back up `.env.keys` (`dot env keys push --vault <vault>`) and delete the old file.
+
+Behaviour that changes:
+
+- The real environment wins over every file. `dotenv --override` has no equivalent.
+- `defineEnv` now fails on a value that still starts with `encrypted:`. Before, ciphertext passed as a string.
+- Files load from the repository root down to the working directory, by `NODE_ENV`. A bare `.env` is no longer read; `dot env check` warns about one.

package/docs/upgrades/typed-node-outcomes.md

@@ -0,0 +1,13 @@
+# Typed node operations
+
+Node filesystem, crypto and provider operations return canonical failures. Replace exception-only handling with `isFailure(result)` checks and propagate the exact returned failure. `defineEnv` remains a lazy boot declaration whose invalid configuration throws.
+
+`generateKeypair()` returns a keypair or `KeyGenerationFailed`. Parse external public/private strings with `parsePublicKey` / `parsePrivateKey`; their validated domains are distinct. Pass these keys to `encryptValue`, `decryptValue`, `publicKeyOf` and `writePrivateKey`. Encryption/decryption and lossless text edits return typed failures instead of throwing expected rejection.
+
+`loadEnvFiles()` returns its successful report, `EnvFilesFailed`, `EnvCancelled` or `EnvDeadline`. Read `EnvFilesFailed.data.errors`; problem codes are now dotted canonical codes (`env.missing_private_key`, `env.decryption_failed`, `env.reference_failed`, `env.file_read_failed`). Failure applies no file values. Do not serialize successful report values or private failure causes. `formatEnvFilesErrors` accepts `EnvFilesFailed`. Explicit `node/register` converts these outcomes to a boot exception.
+
+`timeoutMs` defaults to one 30-second aggregate budget. Custom synchronous resolvers accept a second options argument with remaining timeout and optional signal, and return a string or canonical provider/cancellation/deadline failure. Thrown custom resolver errors are sanitized at the loader boundary. Abort is checked between synchronous callbacks; native child processes enforce the timeout.
+
+Storage/ciphertext algorithms and bytes remain dotenvx-compatible. Rotation stages the root and every existing candidate local `.env.keys` store before any ciphertext changes. Each variable temporarily stores the existing comma-separated multi-key shape: new key first, followed by previous generations. Each file remains decryptable during partial rotation. Keep that file after `RotationIncomplete`, repair the filesystem and retry with the staged keys. Previous keys retire only after every new file reads back exactly as planned. Atomic temp-file replacement protects against partial writes on process interruption; it is not an fsync/power-loss durability guarantee.
+
+Node load/edit/provider execution emits OpenTelemetry spans and durations without installing an SDK. Configure telemetry in the application; no path, reference, value, key or raw cause is recorded.

package/llms.txt

@@ -0,0 +1,30 @@
+# @arki/env
+
+> Typed environment validation and explicit Node file/key operations. `defineEnv()` validates lazily with any Standard Schema, `secret()` keeps values out of logs, and `@arki/dot/env` validates at Dot boot.
+
+## Import paths
+
+<!-- llms:start -->
+- `@arki/env`: The `presets` namespace of ready-made variable shapes, for `defineEnv()`. `presets`.
+- `@arki/env/core`: `defineEnv()` plus `secret()`, `reveal()` and `Redacted` for typed, lazily validated environments. `Redacted`, `SECRET_SCHEMA`, `defineEnv`, `describeEnv`, `formatIssues`, `isSecretSchema`, `presets`, `reveal`, `secret`; types `EnvDescription`, `EnvKeyDescription`.
+- `@arki/env/presets`: Ready-made Zod presets for ports, URLs, lists, JSON and other common variable shapes. `commonPresets`, `parsePresets`, `presets`, `urlPresets`.
+- `@arki/env/node`: Encrypted env files in the dotenvx 2.x format, for Node, Bun and Deno: load them into the environment (`loadEnvFiles`), edit them (`initEnvFile`, `setEnvFileValue`, ...), and the codec underneath. `DEFAULT_RESOLVERS`, `DecryptionFailed`, `ENCRYPTED_PREFIX`, `ENV_FILES_ERROR_CODES`, `EncryptionFailed`, `EnvCancelled`, `EnvDeadline`, `EnvFilesFailed`, `FileReadFailed`, `FileWriteFailed`, `KEYS_FILE`, `KeyGenerationFailed`; and 53 more.
+- `@arki/env/node/register`: Side-effect entry: load the env files into `process.env` as this module is imported.
+<!-- llms:end -->
+
+## Start here
+- [Agent guide](docs/agent-guide.md): read first.
+- [Verify](docs/agent-guide.md#verify): the commands to run after a change.
+- [README](README.md): the long overview.
+
+## By task
+- [Define the environment of an app](docs/agent-guide.md#define-the-environment-of-an-app)
+- [Keep a secret out of logs](docs/agent-guide.md#keep-a-secret-out-of-logs)
+- [Build a Docker image without secrets](docs/agent-guide.md#build-a-docker-image-without-secrets)
+- [Validate at boot in a Dot app](docs/agent-guide.md#validate-at-boot-in-a-dot-app)
+
+## Rules that bite
+- Validation runs everywhere. Only `SKIP_ENV_VALIDATION=1` (exactly `1`) skips it.
+- Read a secret with `reveal(env.KEY)`. It prints as `[redacted]` otherwise.
+- Pass `runtimeEnv` on engines with no `process`.
+- Schemas validate synchronously; the first read validates, not the import.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arki/env",
-  "version": "0.0.9",
-  "description": "Type-safe environment variable parsing for ARKI — defineEnv() built on @t3-oss/env-core with Zod contracts for common variable shapes.",
+  "version": "0.2.0",
+  "description": "Type-safe environment variable parsing for ARKI — defineEnv() built on @t3-oss/env-core with Zod presets for common variable shapes.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,7 +21,10 @@
     "config"
   ],
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/node/register.js",
+    "./src/node/register.ts"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -33,15 +36,20 @@
       "import": "./dist/core/index.js",
       "default": "./dist/core/index.js"
     },
-    "./contracts": {
-      "types": "./dist/contracts/index.d.ts",
-      "import": "./dist/contracts/index.js",
-      "default": "./dist/contracts/index.js"
+    "./presets": {
+      "types": "./dist/presets/index.d.ts",
+      "import": "./dist/presets/index.js",
+      "default": "./dist/presets/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js",
+      "default": "./dist/node/index.js"
     },
-    "./dot": {
-      "types": "./dist/dot.d.ts",
-      "import": "./dist/dot.js",
-      "default": "./dist/dot.js"
+    "./node/register": {
+      "types": "./dist/node/register.d.ts",
+      "import": "./dist/node/register.js",
+      "default": "./dist/node/register.js"
     },
     "./package.json": "./package.json"
   },
@@ -55,21 +63,20 @@
     "!src/**/__tests__/**",
     "README.md",
     "LICENSE",
+    "CHANGELOG.md",
+    "llms.txt",
+    "docs/agent-guide.md",
+    "docs/upgrades/**",
     "package.json"
   ],
   "dependencies": {
-    "@arki/ts": "0.0.3",
+    "@arki/failure": "0.3.0",
+    "@arki/schema": "0.3.0",
+    "@opentelemetry/api": "^1.9.1",
     "@t3-oss/env-core": "^0.13.11",
+    "eciesjs": "^0.5.0",
     "zod": "4.6.5"
   },
-  "peerDependencies": {
-    "@arki/dot": "^0.5.0"
-  },
-  "peerDependenciesMeta": {
-    "@arki/dot": {
-      "optional": true
-    }
-  },
   "publishConfig": {
     "access": "public"
   }

package/src/core/define-env.ts

@@ -1,7 +1,30 @@
 import type { CreateEnv, DefaultCombinedSchema } from '@t3-oss/env-core';
-import type { ZodType } from 'zod';
 import { createEnv } from '@t3-oss/env-core';
 
+import type { StandardSchemaV1 } from '@arki/schema';
+import { InvalidInput, orThrow, UnexpectedFailure } from '@arki/failure';
+import { parse, pathOf } from '@arki/schema';
+
+import { registerEnvDescription } from './describe.js';
+import { InvalidEnvironment } from './errors.js';
+
+/**
+ * The process environment, or `undefined` on engines with no `process` (Hermes, browsers, Deno without
+ * Node compat). Reads through `globalThis` so a missing global is not a ReferenceError. Called only when
+ * the env is first read, never at import.
+ */
+export function processEnv(): Record<string, string | undefined> | undefined {
+  // Typed as optional on purpose: the Node typings say `process` always exists, Hermes says otherwise.
+  const scope: { process?: { env: Record<string, string | undefined> } } = globalThis;
+  return scope.process?.env;
+}
+
+/** The prefix of a value encrypted in a dotenvx-format env file (`@arki/env/node`). */
+export const ENCRYPTED_PREFIX = 'encrypted:';
+
+const STILL_ENCRYPTED_MESSAGE =
+  'still encrypted: start the process with `dot env run -- <cmd>`, or import `@arki/env/node/register` first';
+
 /** The issue shape t3-oss hands to `onValidationError`, derived so it stays in sync with the lib. */
 type ValidationIssues = Parameters<NonNullable<Parameters<typeof createEnv>[0]['onValidationError']>>[0];
 
@@ -10,12 +33,10 @@ type ValidationIssues = Parameters<NonNullable<Parameters<typeof createEnv>[0]['
  * logs `issues` as a raw object, which platforms like Coolify collapse to `[Object]` — so the var
  * that actually failed never reaches the logs. A flat `  path: message` list survives transport.
  */
-function formatIssues(name: string | undefined, issues: ValidationIssues): string {
+export function formatIssues(name: string | undefined, issues: ValidationIssues): string {
   const label = name ? `[${name}] ` : '';
   const lines = issues.map(issue => {
-    const path = (issue.path ?? [])
-      .map(seg => (typeof seg === 'object' && seg !== null && 'key' in seg ? String(seg.key) : String(seg)))
-      .join('.');
+    const path = pathOf(issue).map(String).join('.');
     return `  ${path || '(root)'}: ${issue.message}`;
   });
   return `❌ ${label}Invalid environment variables:\n${lines.join('\n')}`;
@@ -24,17 +45,22 @@ function formatIssues(name: string | undefined, issues: ValidationIssues): strin
 /**
  * Thin, type-preserving wrapper over `@t3-oss/env-core`'s `createEnv`. Generic over the server,
  * client, shared and composed schemas so the parsed env keeps its exact inferred types — the wrapper
- * adds the ARKI defaults (auto `runtimeEnv`, prod-safe `skipValidation`, a legible labelled error
- * handler) without widening any value to `unknown`.
+ * adds the ARKI defaults (auto `runtimeEnv`, validation on in every environment, a legible labelled
+ * error handler) without widening any value to `unknown`.
+ *
+ * Every schema is a Standard Schema (Zod, Valibot, ArkType, or a hand-written `~standard` object); each
+ * value's type is the schema's OUTPUT, so defaults and coercions in the caller's schemas still apply.
+ * Validation is synchronous: a schema whose `validate` returns a Promise or throws makes the first read
+ * throw `UnexpectedFailure` with the canonical schema failure, never a validation error.
  *
  * `TPrefix` is kept as a string-literal generic on purpose: `createEnv` uses it to enforce that
  * client keys (and only client keys) carry the prefix. Widening it to `string` would make every
  * server key collapse to a type-level `ErrorMessage`, so the prefix must stay a literal.
  */
 export function defineEnv<
-  TServer extends Record<string, ZodType>,
-  TClient extends Record<string, ZodType> = NonNullable<unknown>,
-  TShared extends Record<string, ZodType> = NonNullable<unknown>,
+  TServer extends Record<string, StandardSchemaV1>,
+  TClient extends Record<string, StandardSchemaV1> = NonNullable<unknown>,
+  TShared extends Record<string, StandardSchemaV1> = NonNullable<unknown>,
   const TPrefix extends string = '',
   const TExtends extends Record<string, unknown>[] = [],
 >(config: {
@@ -64,6 +90,12 @@ export function defineEnv<
    */
   runtimeEnv?: Record<string, string | boolean | number | undefined>;
   options?: {
+    /**
+     * `true` skips schema validation: values pass through raw. Default: validate on the first read,
+     * in every environment, unless the process sets `SKIP_ENV_VALIDATION=1` (exactly `1`). That
+     * variable is the only implicit opt-out, meant for Docker build stages that prerender without
+     * secrets. `CI`, lint and `NODE_ENV` never skip.
+     */
     skipValidation?: boolean;
     /**
      * Treat empty-string env values as `undefined` so defaults apply (e.g. `PORT=` in `.env`, or a
@@ -84,8 +116,11 @@ export function defineEnv<
   // consumed (boot, a request, a job). This is the same import/observe split
   // drizzle tables have: define everywhere, observe only at use.
   const build = (): Built<Result> => {
-    const skipValidation =
-      config.options?.skipValidation ?? (!!process.env.CI || process.env.NODE_ENV !== 'development');
+    // Validate everywhere the app runs, production included. The only implicit opt-out is the
+    // purpose-named SKIP_ENV_VALIDATION=1 (Docker build stages without secrets). Ambient variables
+    // like CI or the npm script name must never turn validation off: that would boot production on
+    // an unchecked config.
+    const skipValidation = config.options?.skipValidation ?? processEnv()?.SKIP_ENV_VALIDATION === '1';
 
     // Use the caller's explicit runtimeEnv when supplied (Vite client vars via import.meta.env, or
     // fallback aliases). Otherwise auto-build from every declared key (server + client + shared);
@@ -95,14 +130,15 @@ export function defineEnv<
       runtimeEnv = config.runtimeEnv;
     } else {
       runtimeEnv = {};
+      const source = processEnv();
       for (const key of Object.keys(config.server)) {
-        runtimeEnv[key] = process.env[key];
+        runtimeEnv[key] = source?.[key];
       }
       for (const key of Object.keys(config.client ?? {})) {
-        runtimeEnv[key] = process.env[key];
+        runtimeEnv[key] = source?.[key];
       }
       for (const key of Object.keys(config.shared ?? {})) {
-        runtimeEnv[key] = process.env[key];
+        runtimeEnv[key] = source?.[key];
       }
     }
 
@@ -111,9 +147,20 @@ export function defineEnv<
       ((issues: ValidationIssues): never => {
         const message = formatIssues(config.name, issues);
         console.error(message);
-        throw new Error(message);
+        // A configuration fault at boot: a typed failure, so a catcher can match on the code.
+        throw new UnexpectedFailure(InvalidEnvironment({ report: message }));
       });
 
+    // A value that is still `encrypted:` means the env files were not loaded (Bun auto-loads them
+    // as they are, ciphertext included). A string schema would accept it, so refuse it here, by name.
+    if (!skipValidation) {
+      const stillEncrypted = Object.keys(runtimeEnv).filter(key => {
+        const value = runtimeEnv[key];
+        return typeof value === 'string' && value.startsWith(ENCRYPTED_PREFIX);
+      });
+      if (stillEncrypted.length > 0) onValidationError(stillEncrypted.map(key => ({ message: STILL_ENCRYPTED_MESSAGE, path: [key] })));
+    }
+
     // `createEnv`'s `server`/`client` params are conditional on `clientPrefix` being a *concrete*
     // string literal; inside a generic wrapper `TPrefix` is abstract, so the body cannot be verified
     // for all prefixes and the call argument must be asserted once. The PUBLIC contract stays exact:
@@ -121,10 +168,10 @@ export function defineEnv<
     // caller's `server`/`client`/`extends` are fully type-checked against `TServer`/`TClient`/`TExtends`
     // at the call site. This is the only seam where types are asserted — value types are never widened.
     const options = {
-      shared: config.shared ?? {},
+      shared: syncSchemas(config.shared),
       extends: config.extends,
-      server: config.server,
-      client: config.client ?? {},
+      server: syncSchemas(config.server),
+      client: syncSchemas(config.client),
       clientPrefix: config.clientPrefix ?? '',
       runtimeEnv,
       skipValidation,
@@ -142,7 +189,41 @@ export function defineEnv<
     return { env, isPrivate };
   };
 
-  return lazyEnv(build);
+  const env = lazyEnv(build);
+  registerEnvDescription(env, {
+    ...(config.name === undefined ? {} : { name: config.name }),
+    server: config.server,
+    ...(config.client === undefined ? {} : { client: config.client }),
+    ...(config.shared === undefined ? {} : { shared: config.shared }),
+    ...(config.extends === undefined ? {} : { extends: config.extends }),
+  });
+  return env;
+}
+
+/**
+ * The caller's schemas, each run through `parse` before t3 sees it. t3 would let a throwing validator's
+ * raw error escape and report an async one with its own error (leaving a rejection unhandled). Here both
+ * fail as `UnexpectedFailure` (canonical validator defect with its private cause, or async mismatch), and bad values still reach t3 as issues.
+ */
+function syncSchemas(schemas: Record<string, StandardSchemaV1> | undefined): Record<string, StandardSchemaV1> {
+  const wrapped: Record<string, StandardSchemaV1> = {};
+  for (const [key, schema] of Object.entries(schemas ?? {})) wrapped[key] = syncSchema(schema);
+  return wrapped;
+}
+
+/** Same `version`, `vendor` and `types` as `schema`; only `validate` changes. */
+function syncSchema<Input, Output>(schema: StandardSchemaV1<Input, Output>): StandardSchemaV1<Input, Output> {
+  return {
+    '~standard': {
+      ...schema['~standard'],
+      validate: value => {
+        const result = parse(schema, value);
+        if (InvalidInput.is(result)) return { issues: result.data.issues };
+        // env-core expects validator defects to throw; bridge that foreign contract explicitly.
+        return { value: orThrow(result) };
+      },
+    },
+  };
 }
 
 /** The built env, and whether its reads may be copied (it is private and returns stored values). */

package/src/core/describe.ts

@@ -0,0 +1,52 @@
+/**
+ * `describeEnv(env)`: the keys an env built by `defineEnv` declares, which of them are `secret()`,
+ * and where they live. It reads the declaration only, never a value, so tools (`dot env check`) can
+ * use it on a bare checkout.
+ */
+import type { StandardSchemaV1 } from '@arki/schema';
+
+import { isSecretSchema } from './secret.js';
+
+/** One declared key. */
+export type EnvKeyDescription = {
+  readonly key: string;
+  /** Declared with `secret()`: must never be plaintext in a tracked file. */
+  readonly secret: boolean;
+  readonly scope: 'server' | 'client' | 'shared';
+};
+
+/** What an env declares, its `extends` included. */
+export type EnvDescription = { readonly name?: string; readonly keys: readonly EnvKeyDescription[] };
+
+const descriptions = new WeakMap<object, EnvDescription>();
+
+/** The description of an env built by `defineEnv`, or `undefined` for any other object. */
+export function describeEnv(env: object): EnvDescription | undefined {
+  return descriptions.get(env);
+}
+
+/** Called by `defineEnv` once per env. Later scopes and the env's own keys win over `extends`. */
+export function registerEnvDescription(
+  env: object,
+  declaration: {
+    readonly name?: string;
+    readonly server: Record<string, StandardSchemaV1>;
+    readonly client?: Record<string, StandardSchemaV1>;
+    readonly shared?: Record<string, StandardSchemaV1>;
+    readonly extends?: readonly object[];
+  },
+): void {
+  const keys = new Map<string, EnvKeyDescription>();
+  for (const base of declaration.extends ?? []) {
+    for (const key of describeEnv(base)?.keys ?? []) keys.set(key.key, key);
+  }
+  const scopes = [
+    ['shared', declaration.shared],
+    ['client', declaration.client],
+    ['server', declaration.server],
+  ] as const;
+  for (const [scope, schemas] of scopes) {
+    for (const [key, schema] of Object.entries(schemas ?? {})) keys.set(key, { key, secret: isSecretSchema(schema), scope });
+  }
+  descriptions.set(env, declaration.name === undefined ? { keys: [...keys.values()] } : { name: declaration.name, keys: [...keys.values()] });
+}

package/src/core/errors.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+import { defineFailure } from '@arki/failure';
+
+/** The process environment does not match the schema, so the app must not boot.
+ * @fix Set or correct the variables listed in the report, then start the app again.
+ * @verify bun run test -- src/core/define-env.test.ts
+ */
+export const InvalidEnvironment = /* @__PURE__ */ defineFailure('env.invalid_environment', {
+  status: 500,
+  data: z.object({ report: z.string() }),
+  message: data => data.report,
+  remediation: 'Set or correct the variables listed in the report, then start the app again.',
+});

package/src/core/index.ts

@@ -1,2 +1,7 @@
-export { defineEnv } from './define-env.js';
-export { contracts } from '../contracts/index.js';
+/** `defineEnv()` plus `secret()`, `reveal()` and `Redacted` for typed, lazily validated environments. */
+export { defineEnv, formatIssues } from './define-env.js';
+export { InvalidEnvironment } from './errors.js';
+export { isSecretSchema, Redacted, reveal, secret, SECRET_SCHEMA } from './secret.js';
+export { describeEnv } from './describe.js';
+export type { EnvDescription, EnvKeyDescription } from './describe.js';
+export { presets } from '../presets/index.js';

package/src/core/secret.ts

@@ -0,0 +1,127 @@
+/**
+ * Secrets that cannot leak by accident.
+ *
+ * `secret(schema)` parses a variable as usual and wraps the result in a
+ * {@link Redacted}. Printing it, logging it, serialising it or putting it in a
+ * template string all show `[redacted]`. Reading the value takes a deliberate,
+ * greppable `reveal(env.KEY)` call at the one place that needs it.
+ *
+ * Redaction guards against accidents (a logged config object, an error
+ * message with the env in it). It is not encryption: code that calls
+ * `reveal` gets the plain value.
+ */
+import type { SchemaInput, SchemaOutput, StandardSchemaV1 } from '@arki/schema';
+
+/** What a redacted value prints as, everywhere. */
+const REDACTED_TEXT = '[redacted]';
+
+/** Node's `util.inspect` hook, so `console.log(env)` shows `[redacted]` too. */
+const inspect: unique symbol = Symbol.for('nodejs.util.inspect.custom');
+
+/** Reads the private value. Assigned in the class's static block, so only this module can read it. */
+let read: <Value>(redacted: Redacted<Value>) => Value;
+
+/** A value that prints as `[redacted]`. Read it with {@link reveal}. */
+export class Redacted<Value = string> {
+  // A private field: invisible to JSON, `Object.keys`, spreading and `util.inspect`.
+  readonly #value: Value;
+
+  static {
+    read = redacted => redacted.#value;
+  }
+
+  constructor(value: Value) {
+    this.#value = value;
+  }
+
+  toString(): string {
+    return REDACTED_TEXT;
+  }
+
+  toJSON(): string {
+    return REDACTED_TEXT;
+  }
+
+  [inspect](): string {
+    return REDACTED_TEXT;
+  }
+}
+
+/** What {@link secret} returns: a Standard Schema whose output is redacted, with an `.optional()` variant. */
+export type SecretSchema<Schema extends StandardSchemaV1> = StandardSchemaV1<
+  SchemaInput<Schema>,
+  Redacted<SchemaOutput<Schema>>
+> & {
+  readonly [SECRET_SCHEMA]: true;
+  /** Accepts a missing variable. `undefined` passes through as `undefined`, never redacted. */
+  optional(): StandardSchemaV1<SchemaInput<Schema> | undefined, Redacted<SchemaOutput<Schema>> | undefined> & {
+    readonly [SECRET_SCHEMA]: true;
+  };
+};
+
+/** Marks a schema built by {@link secret}, so `describeEnv` can tell secrets apart. */
+export const SECRET_SCHEMA: unique symbol = Symbol.for('arki.env.secret');
+
+/** True for a schema built by {@link secret} (or its `.optional()`). */
+export function isSecretSchema(schema: StandardSchemaV1): boolean {
+  return SECRET_SCHEMA in schema;
+}
+
+/**
+ * What every issue of a rejected secret says. Vendors such as valibot put the received value in
+ * their messages (`Received "sk_live_…"`), and `defineEnv` logs and throws issues, so a secret's
+ * issues keep only their path.
+ */
+const HIDDEN_ISSUE_MESSAGE = 'Invalid secret (details hidden so the value cannot leak)';
+
+/**
+ * Validate with `schema` (any Standard Schema), then wrap the value in a {@link Redacted}. For an
+ * optional secret, call `.optional()`: `secret(z.string()).optional()`. The inner result passes
+ * straight through: an async inner schema yields a promise, so `defineEnv`'s synchronous check
+ * fails with the same `UnexpectedFailure` it would give without `secret`, and a throwing validator
+ * still throws.
+ *
+ * @example
+ * const env = defineEnv({ server: { STRIPE_KEY: secret(z.string().min(1)) } });
+ * console.log(env.STRIPE_KEY);          // [redacted]
+ * stripe(reveal(env.STRIPE_KEY));       // the key
+ */
+export function secret<Schema extends StandardSchemaV1>(schema: Schema): SecretSchema<Schema> {
+  const { version, vendor } = schema['~standard'];
+  type Sealed = StandardSchemaV1.Result<Redacted<SchemaOutput<Schema>>>;
+  const seal = (result: StandardSchemaV1.Result<SchemaOutput<Schema>>): Sealed =>
+    result.issues === undefined
+      ? { value: new Redacted(result.value) }
+      : {
+          issues: result.issues.map(issue =>
+            issue.path === undefined
+              ? { message: HIDDEN_ISSUE_MESSAGE }
+              : { message: HIDDEN_ISSUE_MESSAGE, path: issue.path },
+          ),
+        };
+  const redact = (value: unknown): Sealed | Promise<Sealed> => {
+    const result = schema['~standard'].validate(value);
+    return result instanceof Promise ? result.then(seal) : seal(result);
+  };
+  return {
+    [SECRET_SCHEMA]: true,
+    '~standard': { version, vendor, validate: redact },
+    optional: () => ({
+      [SECRET_SCHEMA]: true,
+      '~standard': {
+        version,
+        vendor,
+        validate: value => (value === undefined ? { value: undefined } : redact(value)),
+      },
+    }),
+  };
+}
+
+/**
+ * The plain value of a secret. Also takes the raw value, because when
+ * validation is skipped (`skipValidation`, or `CI` builds) schemas do not run
+ * and the variable is still a plain string.
+ */
+export function reveal<Value>(value: Redacted<Value> | Value): Value {
+  return value instanceof Redacted ? read(value) : value;
+}

package/src/index.ts

@@ -1,2 +1,3 @@
-// Re-export contracts for convenience
-export { contracts } from './contracts/index.js';
+/** The `presets` namespace of ready-made variable shapes, for `defineEnv()`. */
+// Re-export presets for convenience
+export { presets } from './presets/index.js';