@effected/config-file 0.18.0 → 0.19.1

package/ConfigEvent.js

@@ -30,6 +30,13 @@ const ConfigSourceRef = Schema.Struct({
 * `reason` string, so every field a subscriber might branch on survives; a
 * subscriber that wants prose can read `error.message`.
 *
+* `error` is typed `unknown` (`Schema.Defect()`) on purpose. `ParseFailed` and
+* `StringifyFailed` carry whatever the service's codec failed with, and under
+* a decorated codec that is not always a `ConfigCodecError`: an
+* `EncryptedCodec` failure arrives as `ConfigEncryptionError`, a migration
+* failure as `ConfigMigrationError`. Narrow by `_tag` or `instanceof`, never
+* by assuming the codec error.
+*
 * @public
 */
 const ConfigEventPayload = Schema.Union([

package/ConfigFile.js

@@ -292,8 +292,13 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	* `target` is the file this text is destined for, when there is one. It is
 	* only ever used to NAME the file in an error — `encode` passes `none` and
 	* its errors honestly carry no path.
+	*
+	* `onCodecFailure` observes a failure of the codec's `stringify` step and
+	* nothing else. The codec's error type is the caller's `CE`, which may be a
+	* decorator's widened union, so a codec failure cannot be recognized by tag
+	* after the fact — it is observed where it happens.
 	*/
-	const encodeTo = (value, target, encodeOptions) => Effect.gen(function* () {
+	const encodeTo = (value, target, encodeOptions, onCodecFailure) => Effect.gen(function* () {
 		const encoded = yield* Schema.encodeEffect(options.schema)(value).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
 			path: target,
 			issue: error.issue
@@ -301,7 +306,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		const serialized = yield* options.codec.stringify(encoded).pipe(Effect.mapError((error) => Option.match(target, {
 			onNone: () => error,
 			onSome: (file) => withCodecPath(error, file)
-		})));
+		})), Effect.tapError(onCodecFailure));
 		return prependHeader(serialized, encodeOptions?.header);
 	});
 	/**
@@ -312,18 +317,18 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	* failed writes must not see a dry run's codec failure.
 	*/
 	const encodeAndWrite = (value, target, encodeOptions) => Effect.gen(function* () {
-		const serialized = yield* encodeTo(value, Option.some(target), encodeOptions).pipe(Effect.tapError((error) => error._tag === "ConfigCodecError" ? emit({
+		const serialized = yield* encodeTo(value, Option.some(target), encodeOptions, (error) => emit({
 			_tag: "StringifyFailed",
 			codec: options.codec.name,
 			error
-		}) : Effect.void));
+		}));
 		yield* fs.writeFileString(target, serialized).pipe(Effect.mapError((cause) => new ConfigFileWriteError({
 			path: target,
 			cause
 		})));
 	});
 	const encode = Effect.fn("ConfigFile.encode")(function* (value, encodeOptions) {
-		return yield* encodeTo(value, Option.none(), encodeOptions);
+		return yield* encodeTo(value, Option.none(), encodeOptions, () => Effect.void);
 	});
 	/**
 	* Resolve `defaultPath`, `mkdir -p` its parent and write. Shared by `save`
@@ -447,9 +452,23 @@ var ConfigFile = class {
 	/**
 	* Create a uniquely-keyed service class for one config schema.
 	*
+	* @remarks
+	* The optional third type argument is the codec's error channel. Omit it
+	* for the built-in codecs. A service over a decorated codec names the
+	* decorator's widened error, because the key is declared before the codec
+	* is chosen and cannot infer it: wiring `EncryptedCodec(JsonCodec, key)`
+	* into a key declared without it is a compile error, since that service's
+	* methods would fail with a `ConfigEncryptionError` its type never mentions.
+	*
 	* @example
 	* ```ts
 	* class AppConfig extends ConfigFile.Service<AppConfig, AppShape>()("app/Config") {}
+	*
+	* class Secrets extends ConfigFile.Service<
+	* 	Secrets,
+	* 	SecretsShape,
+	* 	ConfigCodecError | ConfigEncryptionError
+	* >()("app/Secrets") {}
 	* ```
 	*/
 	static Service = Service;

package/ConfigMigration.js

@@ -88,7 +88,11 @@ var ConfigMigration = class {
 	* The returned codec's error channel **widens** to include
 	* {@link ConfigMigrationError} rather than flattening migration failures into
 	* the inner codec's error — the reason the {@link (ConfigCodec:interface)} seam is generic
-	* in its error type.
+	* in its error type. The inner codec's own error type is kept as-is, so
+	* wrapping an `EncryptedCodec` yields
+	* `ConfigCodec<ConfigCodecError | ConfigEncryptionError | ConfigMigrationError>`,
+	* and the result goes straight into `ConfigFile.layer`, `testLayer` or
+	* `read`.
 	*
 	* @example
 	* ```ts

package/ConfigProvider.js

@@ -42,6 +42,9 @@ import { ConfigProvider, Effect } from "effect";
 * Descent by own property is also why a prototype getter and `__proto__` are
 * both unreachable through the returned provider.
 *
+* `CE` is the service's codec error, so a service over a decorated codec
+* keeps its widened failure in this effect's error channel.
+*
 * @example
 * ```ts
 * import { asConfigProvider } from "@effected/config-file";
@@ -73,7 +76,8 @@ const asConfigProvider = (service) => Effect.map(service.load, (value) => Config
 *
 * The load happens when the layer is built, and a {@link ConfigFileNotFoundError}
 * surfaces in the layer's error channel rather than degrading to an empty
-* provider — the same honesty {@link asConfigProvider} keeps.
+* provider — the same honesty {@link asConfigProvider} keeps. A service over a
+* decorated codec carries its widened codec error `CE` there too.
 *
 * @example
 * ```ts

package/ConfigResolver.js

@@ -1,4 +1,4 @@
-import { Effect, FileSystem, Option, Path } from "effect";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { Walker } from "@effected/walker";
 
 // src/ConfigResolver.ts
@@ -104,18 +104,25 @@ const isGitRoot = (dir) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	return yield* fs.exists(path.join(dir, ".git"));
 });
+/**
+* Decode a `package.json` text to `Some` exactly when it is a JSON object
+* carrying a `workspaces` key, whatever that key's value (`null` included).
+*
+* @remarks
+* Field presence is all a root check needs, so the struct is
+* `{ workspaces: Unknown }` rather than a `package-json` dependency. It is
+* built once at module scope; `decodeUnknownOption` never throws, which is
+* what keeps a malformed manifest from leaking a defect through a predicate
+* whose error channel is `PlatformError`.
+*/
+const decodeWorkspacesManifest = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Struct({ workspaces: Schema.Unknown })));
 /** A workspace root is marked by `pnpm-workspace.yaml`, or a `package.json` with a `workspaces` field. */
 const isWorkspaceRoot = (dir) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	if (yield* fs.exists(path.join(dir, "pnpm-workspace.yaml"))) return true;
 	const pkgPath = path.join(dir, "package.json");
-	if (yield* fs.exists(pkgPath)) {
-		const content = yield* fs.readFileString(pkgPath);
-		try {
-			if ("workspaces" in JSON.parse(content)) return true;
-		} catch {}
-	}
+	if (yield* fs.exists(pkgPath)) return Option.isSome(decodeWorkspacesManifest(yield* fs.readFileString(pkgPath)));
 	return false;
 });
 const gitRoot = (options) => rootAnchored("git", isGitRoot, options);

package/EncryptedCodec.js

@@ -83,9 +83,17 @@ const keyEffect = (keySource) => keySource._tag === "CryptoKey" ? keySource.key
 * the remainder is the ciphertext, and the plaintext is handed to the inner
 * codec's `parse`.
 *
+* The envelope is decoded with core's `effect/encoding/Base64`. Whitespace
+* around it (a trailing newline, a BOM) is tolerated; whitespace inside it, or
+* missing padding, fails with phase `"encoding"`. `stringify` never produces
+* either.
+*
 * The error channel **widens** to `E | ConfigEncryptionError` rather than
 * flattening — the inner codec's failures stay distinguishable from
-* cryptographic ones.
+* cryptographic ones. The result plugs straight into `ConfigFile.layer`,
+* `ConfigFile.testLayer` and `ConfigFile.read`, whose error unions widen with
+* it; a `ConfigFile.Service` key names the widened error as its third type
+* argument.
 *
 * @example
 * ```ts
@@ -99,8 +107,7 @@ const keyEffect = (keySource) => keySource._tag === "CryptoKey" ? keySource.key
 */
 function EncryptedCodec(inner, keySource) {
 	const name = `encrypted(${inner.name})`;
-	const [resolveKey, invalidateKey] = Effect.runSync(Effect.cachedInvalidateWithTTL(keyEffect(keySource), Duration.infinity));
-	const getKey = Effect.onExit(resolveKey, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidateKey);
+	const getKey = Effect.runSync(Effect.cachedWithTTL(keyEffect(keySource), (exit) => Exit.isSuccess(exit) ? Duration.infinity : Duration.zero));
 	return {
 		name,
 		parse: (raw) => Effect.gen(function* () {
@@ -119,9 +126,9 @@ function EncryptedCodec(inner, keySource) {
 			const key = yield* getKey;
 			const serialized = yield* inner.stringify(value);
 			const encoded = new TextEncoder().encode(serialized);
-			const iv = randomIv();
+			const iv = yield* Effect.mapError(randomIv, toPublic);
 			const ciphertext = yield* Effect.mapError(encrypt(key, iv, encoded), toPublic);
-			return yield* Effect.mapError(toBase64(iv, ciphertext), toPublic);
+			return toBase64(iv, ciphertext);
 		})
 	};
 }

package/README.md

@@ -187,11 +187,20 @@ Four codecs ship in the package, each a free-standing named export:
 
 One install covers every format, and you still pay only for the parser you name. The codecs are free-standing exports rather than properties of a namespace object, so importing `TomlCodec` never references the YAML or JSONC bindings, their parsing engines are unreachable from your entrypoint and a bundler drops them. A JSON-only application ships no parser at all.
 
-Codecs compose. `EncryptedCodec` wraps any codec with AES-GCM, and `ConfigMigration.make` wraps any codec so parsed content is brought up to the latest version. Each *widens* the error channel rather than flattening its failures into the inner codec's error:
+Codecs compose. `EncryptedCodec` wraps any codec with AES-GCM, and `ConfigMigration.make` wraps any codec so parsed content is brought up to the latest version. Each *widens* the error channel rather than flattening its failures into the inner codec's error, and a decorated codec plugs into `ConfigFile.layer`, `ConfigFile.testLayer` and `ConfigFile.read` like any other: their error unions widen with it. A service key names the widened error as its third type argument:
 
 ```ts
-import { ConfigMigration, EncryptedCodec, EncryptedCodecKey, JsonCodec } from "@effected/config-file";
-import { Effect } from "effect";
+import type { ConfigCodec } from "@effected/config-file";
+import {
+  ConfigFile,
+  ConfigMigration,
+  ConfigResolver,
+  EncryptedCodec,
+  EncryptedCodecKey,
+  JsonCodec,
+  MergeStrategy,
+} from "@effected/config-file";
+import { Effect, Schema } from "effect";
 
 const migrating = ConfigMigration.make({
   codec: JsonCodec,
@@ -206,8 +215,25 @@ const migrating = ConfigMigration.make({
 
 // `parse` now fails with ConfigCodecError | ConfigMigrationError | ConfigEncryptionError.
 export const secret = EncryptedCodec(migrating, EncryptedCodecKey.fromPassphrase("hunter2", new Uint8Array(16)));
+
+const Settings = Schema.Struct({ port: Schema.Number });
+// Read back from the codec value: ConfigCodecError | ConfigMigrationError | ConfigEncryptionError.
+type SecretError = ConfigCodec.ErrorOf<typeof secret>;
+
+class SecretSettings extends ConfigFile.Service<SecretSettings, typeof Settings.Type, SecretError>()(
+  "app/SecretSettings",
+) {}
+
+export const SecretSettingsLive = ConfigFile.layer(SecretSettings, {
+  schema: Settings,
+  codec: secret,
+  resolvers: [ConfigResolver.explicitPath("./settings.enc")],
+  strategy: MergeStrategy.firstMatch(),
+});
 ```
 
+Leave the third type argument off and the `ConfigFile.layer` call is a compile error: that service's methods would fail with a `ConfigEncryptionError` its type never names. The envelope's base64 is decoded by core's `effect/encoding/Base64`, so whitespace around it is tolerated while whitespace inside it, or missing padding, fails with `ConfigEncryptionError` phase `"encoding"`.
+
 ## Features
 
 - `ConfigFile.Service` / `ConfigFile.layer` / `ConfigFile.testLayer` — a per-schema service class and its layers. `testLayer` seeds files into a temp directory and wires the *real* implementation over them, so tests exercise the actual pipeline rather than a stub that can drift from it.

package/index.d.ts

@@ -66,6 +66,43 @@ interface ConfigCodec<E = ConfigCodecError> {
   /** Turn a document back into file content. */
   readonly stringify: (value: unknown) => Effect.Effect<string, E>;
 }
+/**
+ * Type-level helpers over the `ConfigCodec` interface.
+ *
+ * @public
+ */
+declare namespace ConfigCodec {
+  /**
+   * The error channel of a codec value, read back from its type.
+   *
+   * @remarks
+   * A decorated codec's error union is already on the value —
+   * `EncryptedCodec(...)` over `ConfigMigration.make(...)` is a
+   * `ConfigCodec<ConfigCodecError | ConfigEncryptionError | ConfigMigrationError>`
+   * — and a `ConfigFile.Service` key has to name the same union as its third
+   * type argument. Spelling it out by hand drifts the moment the codec
+   * changes; `ConfigCodec.ErrorOf<typeof codec>` cannot.
+   *
+   * Anything that is not a `ConfigCodec` resolves to `never`.
+   *
+   * @example
+   * ```ts
+   * import type { ConfigCodec } from "@effected/config-file";
+   * import { ConfigFile, ConfigMigration, EncryptedCodec, EncryptedCodecKey, JsonCodec } from "@effected/config-file";
+   *
+   * const codec = EncryptedCodec(
+   * 	ConfigMigration.make({ codec: JsonCodec, migrations: [] }),
+   * 	EncryptedCodecKey.fromPassphrase("hunter2", new Uint8Array(16)),
+   * );
+   *
+   * // Stays in sync with the codec: ConfigCodecError | ConfigMigrationError | ConfigEncryptionError.
+   * class Secrets extends ConfigFile.Service<Secrets, { port: number }, ConfigCodec.ErrorOf<typeof codec>>()(
+   * 	"app/Secrets",
+   * ) {}
+   * ```
+   */
+  type ErrorOf<C> = C extends ConfigCodec<infer E> ? E : never;
+}
 /**
  * A reference to one configuration source that contributed to a load.
  *
@@ -95,6 +132,13 @@ export declare const ConfigSourceRef: Schema.Struct<{
  * `reason` string, so every field a subscriber might branch on survives; a
  * subscriber that wants prose can read `error.message`.
  *
+ * `error` is typed `unknown` (`Schema.Defect()`) on purpose. `ParseFailed` and
+ * `StringifyFailed` carry whatever the service's codec failed with, and under
+ * a decorated codec that is not always a `ConfigCodecError`: an
+ * `EncryptedCodec` failure arrives as `ConfigEncryptionError`, a migration
+ * failure as `ConfigMigrationError`. Narrow by `_tag` or `instanceof`, never
+ * by assuming the codec error.
+ *
  * @public
  */
 export declare const ConfigEventPayload: Schema.Union<readonly [Schema.TaggedStruct<"Discovered", {
@@ -637,30 +681,39 @@ export declare class ConfigValidationError extends ConfigValidationError_base {
 /**
  * The failure modes of the full discovery-and-load path.
  *
+ * @remarks
+ * `CE` is the codec's error channel. It defaults to {@link ConfigCodecError},
+ * the error of the four built-in codecs; a decorated codec widens it. Under
+ * `EncryptedCodec(JsonCodec, key)` it is
+ * `ConfigCodecError | ConfigEncryptionError`, and the union widens with it
+ * rather than flattening the decorator's failure into a codec error.
+ *
  * @public
  */
-type ConfigLoadError = ConfigFileNotFoundError | ConfigFileReadError | ConfigCodecError | ConfigValidationError;
+type ConfigLoadError<CE = ConfigCodecError> = ConfigFileNotFoundError | ConfigFileReadError | CE | ConfigValidationError;
 /**
  * The failure modes of reading one known path.
  *
  * @remarks
  * Deliberately excludes {@link ConfigFileNotFoundError}: every method typed with
  * this union either takes an explicit path or treats "nothing found" as success.
+ * `CE` is the codec's error channel, as on {@link ConfigLoadError}.
  *
  * @public
  */
-type ConfigReadError = ConfigFileReadError | ConfigCodecError | ConfigValidationError;
+type ConfigReadError<CE = ConfigCodecError> = ConfigFileReadError | CE | ConfigValidationError;
 /**
  * The failure modes of encoding and writing one known path.
  *
  * @remarks
  * Deliberately excludes {@link ConfigFileNotFoundError} — the path is explicit,
  * so there is nothing to discover — and {@link ConfigDefaultPathMissingError},
- * because no default path is consulted.
+ * because no default path is consulted. `CE` is the codec's error channel, as
+ * on {@link ConfigLoadError}.
  *
  * @public
  */
-type ConfigWriteError = ConfigFileWriteError | ConfigCodecError | ConfigValidationError;
+type ConfigWriteError<CE = ConfigCodecError> = ConfigFileWriteError | CE | ConfigValidationError;
 /**
  * The failure modes of {@link ConfigFileShape.encode}: everything on the write
  * path except the write itself.
@@ -668,10 +721,11 @@ type ConfigWriteError = ConfigFileWriteError | ConfigCodecError | ConfigValidati
  * @remarks
  * Deliberately excludes {@link ConfigFileWriteError} — nothing touches the
  * filesystem — so a `--dry-run` caller's error channel is honest about that.
+ * `CE` is the codec's error channel, as on {@link ConfigLoadError}.
  *
  * @public
  */
-type ConfigEncodeError = ConfigCodecError | ConfigValidationError;
+type ConfigEncodeError<CE = ConfigCodecError> = CE | ConfigValidationError;
 /**
  * Options shared by {@link ConfigFileShape.encode} and {@link ConfigFileShape.write}.
  *
@@ -694,32 +748,40 @@ interface ConfigEncodeOptions {
   readonly header?: string;
 }
 /**
- * The failure modes of {@link ConfigFileShape.save}.
+ * The failure modes of {@link ConfigFileShape.save}. `CE` is the codec's error
+ * channel, as on {@link ConfigLoadError}.
  *
  * @public
  */
-type ConfigSaveError = ConfigWriteError | ConfigDefaultPathMissingError;
+type ConfigSaveError<CE = ConfigCodecError> = ConfigWriteError<CE> | ConfigDefaultPathMissingError;
 /**
- * The failure modes of {@link ConfigFileShape.update}, which loads and then saves.
+ * The failure modes of {@link ConfigFileShape.update}, which loads and then
+ * saves. `CE` is the codec's error channel, as on {@link ConfigLoadError}.
  *
  * @public
  */
-type ConfigUpdateError = ConfigLoadError | ConfigFileWriteError | ConfigDefaultPathMissingError;
+type ConfigUpdateError<CE = ConfigCodecError> = ConfigLoadError<CE> | ConfigFileWriteError | ConfigDefaultPathMissingError;
 /**
- * The config file service, generic over the decoded config type `A`.
+ * The config file service, generic over the decoded config type `A` and the
+ * codec's error channel `CE`.
  *
  * @remarks
  * Error unions are narrowed per method: `loadOrDefault` cannot fail with
  * {@link ConfigFileNotFoundError} because that is the branch it handles, and
  * `discover` treats an empty result as success.
  *
+ * `CE` defaults to {@link ConfigCodecError}, so a service over a built-in
+ * codec never names it. A service over a decorated codec —
+ * `EncryptedCodec(...)`, `ConfigMigration.make(...)` — names the decorator's
+ * widened error here, and every codec-facing method carries it.
+ *
  * @public
  */
-interface ConfigFileShape<A> {
+interface ConfigFileShape<A, CE = ConfigCodecError> {
   /** Discover, decode and merge the highest-priority config source. */
-  readonly load: Effect.Effect<A, ConfigLoadError>;
+  readonly load: Effect.Effect<A, ConfigLoadError<CE>>;
   /** Read, decode and validate one explicit path. */
-  readonly loadFrom: (path: string) => Effect.Effect<A, ConfigReadError>;
+  readonly loadFrom: (path: string) => Effect.Effect<A, ConfigReadError<CE>>;
   /**
    * Every source the resolver chain found, in priority order. Empty is success.
    *
@@ -728,7 +790,7 @@ interface ConfigFileShape<A> {
    * being silently skipped: silently skipping a corrupt file would mean running
    * on the wrong config. This is deliberate.
    */
-  readonly discover: Effect.Effect<ReadonlyArray<ConfigSource<A>>, ConfigReadError>;
+  readonly discover: Effect.Effect<ReadonlyArray<ConfigSource<A>>, ConfigReadError<CE>>;
   /**
    * Like {@link ConfigFileShape.load}, but yields `defaultValue` when nothing is found.
    *
@@ -736,7 +798,7 @@ interface ConfigFileShape<A> {
    * `defaultValue` is returned as-is: neither the schema nor `options.validate`
    * is applied to it. It is trusted caller input, not a discovered document.
    */
-  readonly loadOrDefault: (defaultValue: A) => Effect.Effect<A, ConfigReadError>;
+  readonly loadOrDefault: (defaultValue: A) => Effect.Effect<A, ConfigReadError<CE>>;
   /** Decode and validate an in-memory value. */
   readonly validate: (value: unknown) => Effect.Effect<A, ConfigValidationError>;
   /**
@@ -749,7 +811,7 @@ interface ConfigFileShape<A> {
    * `path`, and a validation failure's `path` is `Option.none()`: there is no
    * file to name.
    */
-  readonly encode: (value: A, options?: ConfigEncodeOptions) => Effect.Effect<string, ConfigEncodeError>;
+  readonly encode: (value: A, options?: ConfigEncodeOptions) => Effect.Effect<string, ConfigEncodeError<CE>>;
   /**
    * Encode `value` and write it to an explicit `path`.
    *
@@ -759,12 +821,12 @@ interface ConfigFileShape<A> {
    * `write` targets a path the caller already vouched for. `options` are the
    * same as {@link ConfigFileShape.encode}'s, so the two stay in lockstep.
    */
-  readonly write: (value: A, path: string, options?: ConfigEncodeOptions) => Effect.Effect<void, ConfigWriteError>;
+  readonly write: (value: A, path: string, options?: ConfigEncodeOptions) => Effect.Effect<void, ConfigWriteError<CE>>;
   /**
    * Resolve `defaultPath`, `mkdir -p` its parent, encode `value` into it, and
    * return the path written.
    */
-  readonly save: (value: A) => Effect.Effect<string, ConfigSaveError>;
+  readonly save: (value: A) => Effect.Effect<string, ConfigSaveError<CE>>;
   /**
    * Load the current value, apply `fn`, {@link ConfigFileShape.save} the result
    * and return it.
@@ -773,7 +835,7 @@ interface ConfigFileShape<A> {
    * With `defaultValue` the load cannot fail with
    * {@link ConfigFileNotFoundError}; without it, it can.
    */
-  readonly update: (fn: (current: A) => A, defaultValue?: A) => Effect.Effect<A, ConfigUpdateError>;
+  readonly update: (fn: (current: A) => A, defaultValue?: A) => Effect.Effect<A, ConfigUpdateError<CE>>;
 }
 /**
  * Options for {@link ConfigFile.layer}.
@@ -782,9 +844,13 @@ interface ConfigFileShape<A> {
  * `RR` is the union of the resolvers' requirements. It flows into the layer's
  * `R` rather than being cast away.
  *
+ * `CE` is the codec's error channel, inferred from `codec`. It defaults to
+ * {@link ConfigCodecError}; a decorated codec widens it, and the service's
+ * error unions widen with it.
+ *
  * @public
  */
-interface ConfigFileOptions<A, I, RR> {
+interface ConfigFileOptions<A, I, RR, CE = ConfigCodecError> {
   /**
    * The schema every discovered document is decoded through.
    *
@@ -795,8 +861,15 @@ interface ConfigFileOptions<A, I, RR> {
    * requirements.
    */
   readonly schema: Schema.Codec<A, I>;
-  /** How file content becomes an unknown document, and back. */
-  readonly codec: ConfigCodec;
+  /**
+   * How file content becomes an unknown document, and back.
+   *
+   * @remarks
+   * Any `ConfigCodec<CE>`, decorated ones included: an
+   * `EncryptedCodec(JsonCodec, key)` or a `ConfigMigration.make(...)` codec
+   * goes here directly.
+   */
+  readonly codec: ConfigCodec<CE>;
   /** The resolver chain, in priority order. */
   readonly resolvers: ReadonlyArray<ConfigResolver<RR>>;
   /** How several discovered sources become one value. */
@@ -863,13 +936,21 @@ interface ConfigFileOptions<A, I, RR> {
  * {@link ConfigDefaultPathMissingError} under this layer — the honest answer.
  * Exercise the write path with {@link ConfigFile.layer} instead.
  *
+ * `CE` is the codec's error channel, as on {@link ConfigFileOptions}.
+ *
  * @public
  */
-interface ConfigFileTestOptions<A, I> {
+interface ConfigFileTestOptions<A, I, CE = ConfigCodecError> {
   /** The schema every seeded document is decoded through. */
   readonly schema: Schema.Codec<A, I>;
-  /** How file content becomes an unknown document, and back. */
-  readonly codec: ConfigCodec;
+  /**
+   * How file content becomes an unknown document, and back.
+   *
+   * @remarks
+   * Any `ConfigCodec<CE>`, decorated ones included, exactly as on
+   * {@link ConfigFileOptions.codec}.
+   */
+  readonly codec: ConfigCodec<CE>;
   /** How several discovered sources become one value. */
   readonly strategy: MergeStrategy<A>;
   /**
@@ -886,9 +967,13 @@ interface ConfigFileTestOptions<A, I> {
 /**
  * Options for {@link ConfigFile.read}.
  *
+ * @remarks
+ * `CE` is the codec's error channel, inferred from `codec`, as on
+ * {@link ConfigFileOptions}.
+ *
  * @public
  */
-interface ConfigReadOptions<A, I> {
+interface ConfigReadOptions<A, I, CE = ConfigCodecError> {
   /** The schema the document is decoded through. */
   readonly schema: Schema.Codec<A, I>;
   /**
@@ -900,8 +985,11 @@ interface ConfigReadOptions<A, I> {
    * free-standing-codec tree-shaking guarantee: a consumer that only ever
    * passes `JsonCodec` never references the JSONC, YAML or TOML modules, so
    * their engines stay out of the bundle.
+   *
+   * A decorated codec (`EncryptedCodec`, `ConfigMigration.make`) is accepted,
+   * and `read`'s error channel widens to its error.
    */
-  readonly codec: ConfigCodec;
+  readonly codec: ConfigCodec<CE>;
   /**
    * Parse options for the decode, chiefly `onExcessProperty`.
    *
@@ -922,12 +1010,26 @@ export declare class ConfigFile {
   /**
    * Create a uniquely-keyed service class for one config schema.
    *
+   * @remarks
+   * The optional third type argument is the codec's error channel. Omit it
+   * for the built-in codecs. A service over a decorated codec names the
+   * decorator's widened error, because the key is declared before the codec
+   * is chosen and cannot infer it: wiring `EncryptedCodec(JsonCodec, key)`
+   * into a key declared without it is a compile error, since that service's
+   * methods would fail with a `ConfigEncryptionError` its type never mentions.
+   *
    * @example
    * ```ts
    * class AppConfig extends ConfigFile.Service<AppConfig, AppShape>()("app/Config") {}
+   *
+   * class Secrets extends ConfigFile.Service<
+   * 	Secrets,
+   * 	SecretsShape,
+   * 	ConfigCodecError | ConfigEncryptionError
+   * >()("app/Secrets") {}
    * ```
    */
-  static readonly Service: <Self, A>() => <const Id extends string>(id: Id) => Context.ServiceClass<Self, Id, ConfigFileShape<A>>;
+  static readonly Service: <Self, A, CE = ConfigCodecError>() => <const Id extends string>(id: Id) => Context.ServiceClass<Self, Id, ConfigFileShape<A, CE>>;
   /**
    * Build the live layer for a config service class.
    *
@@ -965,7 +1067,7 @@ export declare class ConfigFile {
    * });
    * ```
    */
-  static readonly layer: <Self, A, I, RR = never, S extends ConfigFileShape<A> = ConfigFileShape<A>>(tag: Context.Key<Self, S> & Context.Key<Self, ConfigFileShape<A>> & ([ConfigFileShape<NoInfer<A>>] extends [S] ? unknown : never), options: ConfigFileOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | RR>;
+  static readonly layer: <Self, A, I, RR = never, CE = ConfigCodecError, S extends ConfigFileShape<A, CE> = ConfigFileShape<A, CE>>(tag: Context.Key<Self, S> & Context.Key<Self, ConfigFileShape<A, CE>> & ([ConfigFileShape<NoInfer<A>, NoInfer<CE>>] extends [S] ? unknown : never), options: ConfigFileOptions<A, I, RR, CE>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | RR>;
   /**
    * A scoped layer that seeds `files` into a temp directory, wires the **real**
    * live implementation over them, and removes the directory when the scope
@@ -999,7 +1101,7 @@ export declare class ConfigFile {
    * }).pipe(Layer.provide(NodeServices.layer));
    * ```
    */
-  static readonly testLayer: <Self, A, I, S extends ConfigFileShape<A> = ConfigFileShape<A>>(tag: Context.Key<Self, S> & Context.Key<Self, ConfigFileShape<A>> & ([ConfigFileShape<NoInfer<A>>] extends [S] ? unknown : never), options: ConfigFileTestOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path>;
+  static readonly testLayer: <Self, A, I, CE = ConfigCodecError, S extends ConfigFileShape<A, CE> = ConfigFileShape<A, CE>>(tag: Context.Key<Self, S> & Context.Key<Self, ConfigFileShape<A, CE>> & ([ConfigFileShape<NoInfer<A>, NoInfer<CE>>] extends [S] ? unknown : never), options: ConfigFileTestOptions<A, I, CE>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path>;
   /**
    * Read, decode and validate one explicit path — no service, no layer, no tag.
    *
@@ -1037,7 +1139,7 @@ export declare class ConfigFile {
    * });
    * ```
    */
-  static readonly read: <A, I>(path: string, options: ConfigReadOptions<A, I>) => Effect.Effect<A, ConfigReadError, FileSystem.FileSystem>;
+  static readonly read: <A, I, CE = ConfigCodecError>(path: string, options: ConfigReadOptions<A, I, CE>) => Effect.Effect<A, ConfigReadError<CE>, FileSystem.FileSystem>;
 }
 declare const ConfigMigrationError_base: Schema.Class<ConfigMigrationError, Schema.TaggedStruct<"ConfigMigrationError", {
   /** The target version of the step that failed. `0` when reading the version failed. */
@@ -1092,10 +1194,19 @@ export interface VersionAccess {
 export declare const VersionAccess: {
   readonly default: VersionAccess;
 };
-/** Options for {@link ConfigMigration.make}. @public */
-interface ConfigMigrationOptions {
-  /** The codec being wrapped. */
-  readonly codec: ConfigCodec;
+/**
+ * Options for {@link ConfigMigration.make}.
+ *
+ * @remarks
+ * `CE` is the wrapped codec's error channel, inferred from `codec`. It
+ * defaults to `ConfigCodecError`; wrapping an already-decorated codec carries
+ * its widened error through.
+ *
+ * @public
+ */
+interface ConfigMigrationOptions<CE = ConfigCodecError> {
+  /** The codec being wrapped — any `ConfigCodec<CE>`, decorated ones included. */
+  readonly codec: ConfigCodec<CE>;
   /** The migration steps; they run in ascending `version` order. */
   readonly migrations: ReadonlyArray<ConfigFileMigration>;
   /** How the version is read and written; defaults to {@link (VersionAccess:variable).default}, a top-level `version` field. */
@@ -1111,7 +1222,11 @@ export declare class ConfigMigration {
    * The returned codec's error channel **widens** to include
    * {@link ConfigMigrationError} rather than flattening migration failures into
    * the inner codec's error — the reason the {@link (ConfigCodec:interface)} seam is generic
-   * in its error type.
+   * in its error type. The inner codec's own error type is kept as-is, so
+   * wrapping an `EncryptedCodec` yields
+   * `ConfigCodec<ConfigCodecError | ConfigEncryptionError | ConfigMigrationError>`,
+   * and the result goes straight into `ConfigFile.layer`, `testLayer` or
+   * `read`.
    *
    * @example
    * ```ts
@@ -1130,7 +1245,7 @@ export declare class ConfigMigration {
    * });
    * ```
    */
-  static readonly make: (options: ConfigMigrationOptions) => ConfigCodec<ConfigCodecError | ConfigMigrationError>;
+  static readonly make: <CE = ConfigCodecError>(options: ConfigMigrationOptions<CE>) => ConfigCodec<CE | ConfigMigrationError>;
 }
 /**
  * Expose a loaded, merged, schema-validated document as a `ConfigProvider`,
@@ -1173,6 +1288,9 @@ export declare class ConfigMigration {
  * Descent by own property is also why a prototype getter and `__proto__` are
  * both unreachable through the returned provider.
  *
+ * `CE` is the service's codec error, so a service over a decorated codec
+ * keeps its widened failure in this effect's error channel.
+ *
  * @example
  * ```ts
  * import { asConfigProvider } from "@effected/config-file";
@@ -1187,7 +1305,7 @@ export declare class ConfigMigration {
  *
  * @public
  */
-export declare const asConfigProvider: <A>(service: ConfigFileShape<A>) => Effect.Effect<ConfigProvider.ConfigProvider, ConfigLoadError>;
+export declare const asConfigProvider: <A, CE = ConfigCodecError>(service: ConfigFileShape<A, CE>) => Effect.Effect<ConfigProvider.ConfigProvider, ConfigLoadError<CE>>;
 /**
  * Options for {@link layerConfigProvider}.
  *
@@ -1220,7 +1338,8 @@ interface LayerConfigProviderOptions {
  *
  * The load happens when the layer is built, and a {@link ConfigFileNotFoundError}
  * surfaces in the layer's error channel rather than degrading to an empty
- * provider — the same honesty {@link asConfigProvider} keeps.
+ * provider — the same honesty {@link asConfigProvider} keeps. A service over a
+ * decorated codec carries its widened codec error `CE` there too.
  *
  * @example
  * ```ts
@@ -1229,7 +1348,7 @@ interface LayerConfigProviderOptions {
  *
  * @public
  */
-export declare const layerConfigProvider: <Self, A>(tag: Context.Key<Self, ConfigFileShape<A>>, options?: LayerConfigProviderOptions) => Layer.Layer<never, ConfigLoadError, Self>;
+export declare const layerConfigProvider: <Self, A, CE = ConfigCodecError>(tag: Context.Key<Self, ConfigFileShape<A, CE>>, options?: LayerConfigProviderOptions) => Layer.Layer<never, ConfigLoadError<CE>, Self>;
 declare const ConfigEncryptionError_base: Schema.Class<ConfigEncryptionError, Schema.TaggedStruct<"ConfigEncryptionError", {
   /** Which cryptographic stage failed. */
   readonly phase: Schema.Literals<readonly ["key-derivation", "encrypt", "decrypt", "encoding"]>;
@@ -1309,9 +1428,17 @@ export declare const EncryptedCodecKey: {
  * the remainder is the ciphertext, and the plaintext is handed to the inner
  * codec's `parse`.
  *
+ * The envelope is decoded with core's `effect/encoding/Base64`. Whitespace
+ * around it (a trailing newline, a BOM) is tolerated; whitespace inside it, or
+ * missing padding, fails with phase `"encoding"`. `stringify` never produces
+ * either.
+ *
  * The error channel **widens** to `E | ConfigEncryptionError` rather than
  * flattening — the inner codec's failures stay distinguishable from
- * cryptographic ones.
+ * cryptographic ones. The result plugs straight into `ConfigFile.layer`,
+ * `ConfigFile.testLayer` and `ConfigFile.read`, whose error unions widen with
+ * it; a `ConfigFile.Service` key names the widened error as its third type
+ * argument.
  *
  * @example
  * ```ts

package/internal/crypto.js

@@ -1,8 +1,10 @@
 import { Effect } from "effect";
+import * as Base64 from "effect/encoding/Base64";
 
 // src/internal/crypto.ts
 /**
-* AES-GCM primitives over WebCrypto.
+* AES-GCM primitives over WebCrypto, with base64 from core's
+* `effect/encoding/Base64`.
 *
 * @remarks
 * This module imports nothing from the rest of the package. `EncryptedCodec.ts`
@@ -59,39 +61,57 @@ const deriveKey = (passphrase, salt) => Effect.tryPromise({
 	catch: fail("key-derivation")
 });
 /**
-* Decode base64 into bytes.
+* Decode the base64 envelope into bytes.
 *
 * @remarks
-* `atob` is available in all modern environments (Node 20+, Bun, Deno).
+* Delegates to core's `effect/encoding/Base64` rather than hand-rolling
+* `atob` and a char-code loop. Core is stricter than `atob`: it strips only
+* CR and LF, so an embedded space or tab, or missing padding, fails here with
+* phase `"encoding"`. The text is trimmed first, so whitespace AROUND the
+* envelope — the realistic residue of a hand edit or an editor's trailing
+* newline — is still tolerated, and `trim` also drops a leading BOM or NBSP,
+* which `atob` rejected. `EncryptedCodec` itself always writes padded,
+* whitespace-free output, so being strict inside the text costs nothing.
+*
+* The decoded view is backed by a plain `ArrayBuffer`; callers that hand a
+* slice of it to WebCrypto get an `ArrayBuffer`-backed view from `slice`.
 *
 * @internal
 */
-const fromBase64 = (raw) => Effect.try({
-	try: () => {
-		const binary = atob(raw);
-		const buf = new ArrayBuffer(binary.length);
-		const bytes = new Uint8Array(buf);
-		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-		return bytes;
-	},
-	catch: fail("encoding")
-});
+const fromBase64 = (raw) => Effect.mapError(Effect.fromResult(Base64.decode(raw.trim())), (error) => fail("encoding")(withoutInput(error)));
+/**
+* Rebuild core's `EncodingError` as a plain `Error` that keeps only its message.
+*
+* @remarks
+* Core's `EncodingError` stores the whole stripped input as `input`, and the
+* public `ConfigEncryptionError` keeps its cause by identity. Passed through
+* as is, a PLAINTEXT config handed to an encrypted codec (a file that was
+* never encrypted, or a resolver pointing at the wrong file) would carry
+* every secret in it into the typed error, the `ParseFailed` event payload,
+* and any log that inspects or serializes the error. Core's messages name at
+* most one offending character, never the input.
+*/
+const withoutInput = (error) => {
+	const cause = new Error(error.message);
+	cause.name = error._tag;
+	return cause;
+};
 /**
 * Prepend the IV to the ciphertext and base64-encode the envelope.
 *
+* @remarks
+* Synchronous and total: encoding bytes to base64 cannot fail, so there is no
+* error channel to carry.
+*
 * @internal
 */
-const toBase64 = (iv, ciphertext) => Effect.try({
-	try: () => {
-		const ciphertextBytes = new Uint8Array(ciphertext);
-		const resultBuf = new ArrayBuffer(12 + ciphertextBytes.length);
-		const result = new Uint8Array(resultBuf);
-		result.set(iv, 0);
-		result.set(ciphertextBytes, 12);
-		return btoa(Array.from(result, (b) => String.fromCharCode(b)).join(""));
-	},
-	catch: fail("encoding")
-});
+const toBase64 = (iv, ciphertext) => {
+	const ciphertextBytes = new Uint8Array(ciphertext);
+	const result = new Uint8Array(12 + ciphertextBytes.length);
+	result.set(iv, 0);
+	result.set(ciphertextBytes, 12);
+	return Base64.encode(result);
+};
 /** Decrypt AES-GCM ciphertext under `iv`. @internal */
 const decrypt = (key, iv, ciphertext) => Effect.tryPromise({
 	try: () => globalThis.crypto.subtle.decrypt({
@@ -108,7 +128,28 @@ const encrypt = (key, iv, plaintext) => Effect.tryPromise({
 	}, key, plaintext),
 	catch: fail("encrypt")
 });
-/** A fresh cryptographically random 12-byte IV. @internal */
-const randomIv = () => globalThis.crypto.getRandomValues(new Uint8Array(/* @__PURE__ */ new ArrayBuffer(12)));
+/**
+* A fresh cryptographically random 12-byte IV, drawn from WebCrypto.
+*
+* @remarks
+* Deliberately NOT core's `Crypto.randomBytes` in `R`, which is otherwise the
+* kit's rule for any contract core declares. The IV is an AES-GCM nonce:
+* repeating one under the same key destroys GCM's confidentiality and
+* integrity. A swappable random source makes that a wiring accident away —
+* `Crypto.make`'s own documentation example returns zero-filled bytes, and a
+* seeded `TestCrypto` layer that reached production would repeat IVs. The
+* `ConfigCodec` seam also has no `R` channel to carry the service. This is a
+* recorded, security-motivated exception, not a precedent for other
+* randomness.
+*
+* A runtime without `globalThis.crypto` fails typed with phase `"encrypt"`,
+* like the neighbouring WebCrypto steps, rather than escaping as a defect.
+*
+* @internal
+*/
+const randomIv = Effect.try({
+	try: () => globalThis.crypto.getRandomValues(new Uint8Array(/* @__PURE__ */ new ArrayBuffer(12))),
+	catch: fail("encrypt")
+});
 
 export { decrypt, deriveKey, encrypt, fromBase64, randomIv, toArrayBufferView, toBase64 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.18.0",
+	"version": "0.19.1",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -44,10 +44,10 @@
 	},
 	"peerDependencies": {
 		"@effected/glob": "^0.14.0",
-		"@effected/jsonc": "^0.19.0",
-		"@effected/toml": "^0.15.0",
+		"@effected/jsonc": "^0.20.0",
+		"@effected/toml": "^0.16.0",
 		"@effected/walker": "^0.19.0",
-		"@effected/yaml": "^0.23.0",
+		"@effected/yaml": "^0.25.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {