@stigmer/server 3.14.0-dev.20260910084630

package/dist/encryption/encryption.js

@@ -0,0 +1,418 @@
+/**
+ * Secret encryption facade — the single entry point for sealing and
+ * unsealing secret values, a versioned-codec registry behind the
+ * SecretService identity every domain already holds.
+ *
+ * Provenance: began as a port of pkg/encryption/encryption.go (the
+ * retired Go server, single static-key format); reshaped by the pre-X1
+ * sealing slice (20260830.04 Stage 1, rulings Q1/Q2) into the port of the
+ * cloud edition's SecretEncryptionService + SecretCodecRegistry so the
+ * cloud composition can register the vault-backed enc:v2/v3 codecs
+ * through the `secretCodecs` extension driver point. The v1 crypto lives
+ * in v1-codec.ts; the taxonomy in errors.ts; the scope in scope.ts.
+ *
+ * Architecture (the Java facade's, verbatim): every stored secret is a
+ * versioned string (enc:v<N>:...). READS dispatch on the value's own
+ * version token, so any mix of versions in the store stays readable; a
+ * version with no codec here is refused loudly as
+ * EncryptionUnavailableError — the value may be perfectly valid, the
+ * machinery is missing (never fail open, never mislabel it as a bad
+ * value). WRITES use exactly one codec, chosen by
+ * STIGMER_ENCRYPTION_WRITE_VERSION (name byte-pinned across editions; OSS
+ * default v1) and resolved FAIL-FAST at construction: naming a version
+ * with no registered codec refuses to boot rather than silently writing
+ * something else.
+ *
+ * No silent version upgrades: encrypt returns an already-prefixed value
+ * unchanged, whatever its version (the ***REDACTED*** round-trip copies
+ * stored values back into new state before encryption re-runs, and they
+ * must survive that second pass byte-identically). The ONE deliberate
+ * exception is reencrypt — the explicit, auditable door the
+ * secret-convergence sweep walks through: upward-only and
+ * round-trip-verified.
+ *
+ * Policy lives HERE, never in a codec: a codec never sees an
+ * already-encrypted value, never sees an unprefixed one, and never
+ * decides what "disabled" means (codec.ts records the contract).
+ */
+import { StaticKeySecretCodec, V1_VERSION } from "./v1-codec.js";
+import { EncryptionUnavailableError, InvalidCiphertextError, } from "./errors.js";
+import { getOrCreateNamedKey } from "./key-manager.js";
+// The taxonomy, the v1 wire constants and the scope re-export here so the
+// module keeps its historical import surface (every domain imports from
+// encryption/encryption.js) — one module to import, five to maintain.
+export { DecryptionFailedError, EncryptionDisabledError, EncryptionUnavailableError, InvalidCiphertextError, } from "./errors.js";
+export { ENCRYPTED_PREFIX, GCM_NONCE_SIZE, GCM_TAG_SIZE, StaticKeySecretCodec, } from "./v1-codec.js";
+export { EncryptionScope, PLATFORM_TENANT } from "./scope.js";
+/** Env var configuring the secrets key (Base64 32B) — Go EnvKeyName. */
+export const ENCRYPTION_KEY_ENV_VAR = "STIGMER_ENCRYPTION_KEY";
+/** Key file under ~/.stigmer — Go KeyFileName. */
+export const ENCRYPTION_KEY_FILE_NAME = "encryption.key";
+/**
+ * Env var selecting the write codec — byte-pinned across editions (the
+ * cloud's stigmer.encryption.write-version binds the same name). OSS
+ * default: v1. A blank value normalizes to the default: this is a
+ * rollback lever, and rollback levers must be robust to sloppy unsetting
+ * (the Java EncryptionConfig note).
+ */
+export const ENCRYPTION_WRITE_VERSION_ENV_VAR = "STIGMER_ENCRYPTION_WRITE_VERSION";
+/** The OSS default write version — the built-in static-key codec. */
+export const DEFAULT_WRITE_VERSION = V1_VERSION;
+/**
+ * The sentinel replacing every non-empty secret value at every
+ * resource-returning boundary — Go steps.RedactedMarker, pinned by the
+ * conformance suite and byte-identical in the cloud edition. Lives with
+ * the facade (the Java shape) because reencrypt must refuse it;
+ * domain/environment/constants.ts re-exports it for its historical
+ * importers. A client sending it BACK on a write means "keep the existing
+ * secret" (the round-trip contract; see preserveRedactedSecrets).
+ */
+export const REDACTED_MARKER = "***REDACTED***";
+/**
+ * Matches ciphertext in ANY supported-or-future version of the enc:v<N>:
+ * family, capturing the version digits. Anchored so a value merely
+ * CONTAINING the prefix is not mistaken for ciphertext. Matching all
+ * versions (not just the ones registered here) is load-bearing: an
+ * unmatched version would be treated as plaintext at every dispatch site
+ * and fail open (returned or re-encrypted as if it were a real value).
+ * Mirrors the cloud edition's SecretEncryptionService.VERSIONED_PREFIX.
+ */
+const VERSIONED_PREFIX = /^enc:v(\d+):/;
+/** Registered version tokens are v<digits> — the dispatchable shape. */
+const VERSION_TOKEN = /^v(\d+)$/;
+/**
+ * Go IsCiphertextShaped: whether a value merely has the SHAPE of
+ * ciphertext — the enc:v<N>: prefix — regardless of whether it is genuine.
+ *
+ * This is the request-boundary provenance test (oss#395, the Go twin of
+ * cloud#229): the prefix is a server-reserved sentinel, so client-supplied
+ * values matching it must be rejected with INVALID_ARGUMENT before they
+ * reach encrypt(), whose idempotent pass-through would otherwise persist
+ * them verbatim (letting a client store forged ciphertext that
+ * getSecretValue later decrypts with the deployment key). Module-level,
+ * like the redaction-marker constant, so boundary steps need no service
+ * instance and the rejection stays unconditional on keyless deployments.
+ */
+export function isCiphertextShaped(value) {
+    return VERSIONED_PREFIX.test(value);
+}
+/** The version token a stored value carries ("v2"), or undefined. */
+function versionTokenOf(value) {
+    const match = VERSIONED_PREFIX.exec(value);
+    return match === null ? undefined : `v${match[1]}`;
+}
+/**
+ * Encryption/decryption for environment (and other domain) secrets. Safe
+ * for concurrent use; construct via one of the factories below.
+ */
+export class SecretService {
+    codecs;
+    writeCodec;
+    /** Numeric form of the write version, for reencrypt's upward-only rule. */
+    writeVersionNumber;
+    constructor(codecs, writeCodec, writeVersionNumber) {
+        this.codecs = codecs;
+        this.writeCodec = writeCodec;
+        this.writeVersionNumber = writeVersionNumber;
+    }
+    /**
+     * Go NewSecretService, kept signature-stable across the codec seam: a
+     * v1-only facade writing v1 — the shape of every OSS deployment with no
+     * extension composed, and of every test that constructs the service
+     * directly. nil/empty key → disabled (pass-through) v1; a present key
+     * must be exactly 32 bytes.
+     */
+    static create(key) {
+        return SecretService.withCodecs({
+            codecs: new Map([[V1_VERSION, new StaticKeySecretCodec(key)]]),
+            writeVersion: V1_VERSION,
+        });
+    }
+    /**
+     * Go NewSecretServiceFromEnv: a v1-only facade with the key from the
+     * shared ladder (env var → key file → auto-generate). Throws only on
+     * unusable explicit configuration; the composition root maps that to
+     * the WARN-degrade posture.
+     */
+    static fromEnv(options = {}) {
+        const key = getOrCreateNamedKey(ENCRYPTION_KEY_ENV_VAR, ENCRYPTION_KEY_FILE_NAME, options);
+        return SecretService.create(key);
+    }
+    /**
+     * The parameterized construction path — the composition root's door
+     * (boot/compose.ts assembles built-in v1 + extension codecs and the
+     * resolved write version). Fail-fast on a write version with no codec:
+     * refusing to start beats silently writing a different version (the
+     * Java @PostConstruct contract). Every map key must be a dispatchable
+     * v<digits> token matching its codec's own version — a registration
+     * dispatch could never reach must fail loudly, not sit dark.
+     */
+    static withCodecs(options) {
+        for (const [token, codec] of options.codecs) {
+            if (!VERSION_TOKEN.test(token)) {
+                throw new Error(`secret codec registered under '${token}' — version tokens must match v<digits> (the enc:v<N>: dispatch shape)`);
+            }
+            if (codec.version !== token) {
+                throw new Error(`secret codec registered under '${token}' declares version '${codec.version}' — the registry key must equal the codec's own version`);
+            }
+        }
+        const writeCodec = options.codecs.get(options.writeVersion);
+        if (writeCodec === undefined) {
+            const registered = [...options.codecs.keys()].sort().join(", ");
+            throw new Error(`${ENCRYPTION_WRITE_VERSION_ENV_VAR} is '${options.writeVersion}' but this deployment has no codec for it (registered: ${registered}). Refusing to start rather than silently writing a different version.`);
+        }
+        // The token shape was validated above, so the capture always matches.
+        const writeVersionNumber = Number(VERSION_TOKEN.exec(options.writeVersion)?.[1]);
+        return new SecretService(new Map(options.codecs), writeCodec, writeVersionNumber);
+    }
+    /**
+     * Whether new values can actually be sealed — delegated to the write
+     * codec (absent isEnabled means enabled: registration IS the ability,
+     * the Java posture; only the OSS v1 codec models a keyless state). The
+     * write steps branch on this for the WARN-degrade posture (oss#394).
+     */
+    isEnabled() {
+        return this.writeCodec.isEnabled?.() ?? true;
+    }
+    /**
+     * Go IsEncrypted — dispatch on STORED values (decrypt, preserve,
+     * re-encrypt). For CLIENT-SUPPLIED input at a request boundary use the
+     * module-level isCiphertextShaped — same test, different intent.
+     */
+    isEncrypted(value) {
+        return isCiphertextShaped(value);
+    }
+    /**
+     * The version number a stored value carries (enc:v<N>: → N), or
+     * undefined for anything else (plaintext, markers, empty strings). The
+     * public face of the dispatch parse, for callers that classify stored
+     * values — the convergence sweep's upward-only rule and the
+     * encryption-state gauges key on it.
+     */
+    versionOf(value) {
+        const match = VERSIONED_PREFIX.exec(value);
+        return match === null ? undefined : Number(match[1]);
+    }
+    /**
+     * Encrypts a plaintext secret under the given scope, using the
+     * configured write version.
+     *
+     * Idempotent for already-prefixed input of ANY version — returned
+     * unchanged (no silent upgrades; see the module header). The
+     * pass-through TRUSTS its callers: it exists for store-restored
+     * ciphertext (the ***REDACTED*** round-trip), and it is NOT a safe
+     * place to validate provenance — only the request pipeline knows
+     * whether a prefixed value came from the store or from a client.
+     * Client-supplied enc:v<N>: input is rejected at every write boundary
+     * via isCiphertextShaped (oss#395); do not "fix" smuggling here.
+     */
+    async encrypt(plaintext, scope) {
+        if (this.isEncrypted(plaintext)) {
+            return plaintext;
+        }
+        return this.writeCodec.encrypt(plaintext, scope);
+    }
+    /**
+     * Encrypts many values under one scope in as few key-provider round
+     * trips as the write codec allows (one, for the v2 envelope codec).
+     * Per-entry semantics are identical to encrypt(): already-encrypted
+     * values of any version pass through unchanged. Result keyed as the
+     * input, iteration order preserved; fails as a whole (the batched
+     * write paths fail the whole request on any encryption error).
+     */
+    async encryptAll(plaintexts, scope) {
+        return this.encryptAllWith(this.writeCodec, plaintexts, scope);
+    }
+    /**
+     * Encrypts a batch capped at the v2 envelope format: the write codec
+     * when the write version is v1 or v2, the v2 codec when the write
+     * version is above it. The generalization of the Java facade's
+     * encryptAllV2 pin (vault project DD-005) for a family that includes
+     * v1-only OSS deployments — see the executioncontext rationale:
+     * ephemeral values on a latency-budgeted read path, sealed where v2
+     * costs one batched Transit round trip and v3 (no KV batch endpoint,
+     * located-scope requirement) cannot follow. At write=v1 this is the
+     * write codec (OSS today); at write=v2 it equals Java's pin; at a
+     * future write=v3 flip it keeps these lanes on v2 instead of breaking
+     * them.
+     */
+    async encryptAllAtMostV2(plaintexts, scope) {
+        const codec = this.writeVersionNumber <= 2 ? this.writeCodec : this.codecFor("v2");
+        return this.encryptAllWith(codec, plaintexts, scope);
+    }
+    /**
+     * Decrypts an encrypted secret value, dispatching on the value's own
+     * version token. Unprefixed values pass through unchanged (legacy
+     * plaintext compatibility, pre-oss#405 rows); prefixed values decrypt
+     * or fail with the two-armed taxonomy (errors.ts). A version with no
+     * codec here is EncryptionUnavailableError — before the codec seam
+     * this build failed such values CLOSED as invalid base64 (the literal
+     * v1 prefix never stripped); the refusal stays closed, now with the
+     * honest arm and copy (a deliberate, recorded change — no wire test
+     * observes it).
+     */
+    async decrypt(encrypted) {
+        const token = versionTokenOf(encrypted);
+        if (token === undefined) {
+            return encrypted;
+        }
+        return this.codecFor(token).decrypt(encrypted);
+    }
+    /**
+     * Decrypts many values in as few key-provider round trips as their
+     * codecs allow, grouping by each value's own version token. Per-entry
+     * semantics are identical to decrypt(): non-encrypted values pass
+     * through. Fails as a whole — callers needing per-key skip semantics
+     * (the resolution lanes) loop decrypt() instead.
+     */
+    async decryptAll(encrypted) {
+        const byVersion = new Map();
+        for (const [key, value] of encrypted) {
+            const token = versionTokenOf(value);
+            if (token === undefined) {
+                continue;
+            }
+            let group = byVersion.get(token);
+            if (group === undefined) {
+                group = new Map();
+                byVersion.set(token, group);
+            }
+            group.set(key, value);
+        }
+        const decrypted = new Map();
+        for (const [token, group] of byVersion) {
+            const codec = this.codecFor(token);
+            const groupResult = codec.decryptAll !== undefined
+                ? await codec.decryptAll(group)
+                : await loopDecryptAll(codec, group);
+            for (const [key, value] of groupResult) {
+                decrypted.set(key, value);
+            }
+        }
+        const result = new Map();
+        for (const [key, value] of encrypted) {
+            result.set(key, decrypted.get(key) ?? value);
+        }
+        return result;
+    }
+    /**
+     * Destroys any external state backing a stored value, dispatching on
+     * the value's own version token — the lifecycle counterpart of
+     * decrypt(). Plaintext and marker values are no-ops by construction;
+     * v1/v2 values are no-ops by codec contract (their stored string IS
+     * the value). Call sites are resource-delete and key-removal paths
+     * whose database write already succeeded, so callers treat failures as
+     * best-effort (the Stage 3 wiring owns that posture).
+     */
+    async delete(storedValue) {
+        const token = versionTokenOf(storedValue);
+        if (token === undefined) {
+            return;
+        }
+        await this.codecFor(token).delete?.(storedValue);
+    }
+    /**
+     * Re-encrypts a stored value to the current write version — the ONE
+     * deliberate exception to the no-silent-upgrades doctrine, built for
+     * the secret-convergence sweep and the future v3 migration pass. Three
+     * rules, each load-bearing (the Java facade's, verbatim):
+     *
+     *   - UPWARD-ONLY: a value already at (or above) the write version is
+     *     returned unchanged. Rolling the write-version lever down must
+     *     never trigger a mass downgrade — in a v3 world that would mean
+     *     mass KV destruction on a config change.
+     *   - ROUND-TRIP-VERIFIED: the new ciphertext is decrypted and compared
+     *     to the plaintext before being returned, so a codec bug can never
+     *     hand the caller an unreadable value to persist.
+     *   - NO EXTERNAL-STATE DESTRUCTION: an old value's backing state (v3
+     *     KV entries) is NOT destroyed here — the caller persists the new
+     *     value first and only then cleans up, or a failed persist would
+     *     leave the stored pointer dangling.
+     *
+     * A non-encrypted, non-marker value is treated as plaintext and sealed
+     * — stored plaintext secrets are damage from the fail-open era (the
+     * cloud's #226 lesson; OSS keyless windows leave the same rows) and
+     * sealing them is strictly an improvement. The literal redaction
+     * marker is refused as InvalidCiphertextError: a stored marker is
+     * corruption from a marker-persist bug, and sealing it would hide the
+     * corruption behind valid ciphertext.
+     *
+     * @throws InvalidCiphertextError value-scoped (callers may skip)
+     * @throws EncryptionUnavailableError infrastructure (callers must abort)
+     */
+    async reencrypt(storedValue, scope) {
+        if (storedValue === "") {
+            return storedValue;
+        }
+        if (storedValue === REDACTED_MARKER) {
+            throw new InvalidCiphertextError("stored value is the literal redaction marker — corruption from a marker-persist bug, not a secret; refusing to seal it");
+        }
+        const version = this.versionOf(storedValue);
+        let plaintext;
+        if (version !== undefined) {
+            if (version >= this.writeVersionNumber) {
+                return storedValue;
+            }
+            plaintext = await this.decrypt(storedValue);
+        }
+        else {
+            plaintext = storedValue;
+        }
+        const reencrypted = await this.writeCodec.encrypt(plaintext, scope);
+        // Round-trip proof BEFORE the caller can persist anything: decrypt
+        // the new value through the normal read path, require an exact match.
+        const verification = await this.decrypt(reencrypted);
+        if (verification !== plaintext) {
+            throw new InvalidCiphertextError(`re-encryption round-trip verification failed for a ${version !== undefined ? `v${version}` : "plaintext"} value: the freshly written ${this.writeCodec.version} ciphertext did not decrypt back to the original plaintext — nothing was persisted; this is a codec bug, stop the migration`);
+        }
+        return reencrypted;
+    }
+    /** The batch-encrypt mechanics shared by encryptAll and the v2 cap. */
+    async encryptAllWith(codec, plaintexts, scope) {
+        const toEncrypt = new Map();
+        for (const [key, value] of plaintexts) {
+            if (!this.isEncrypted(value)) {
+                toEncrypt.set(key, value);
+            }
+        }
+        const encrypted = toEncrypt.size === 0
+            ? new Map()
+            : codec.encryptAll !== undefined
+                ? await codec.encryptAll(toEncrypt, scope)
+                : await loopEncryptAll(codec, toEncrypt, scope);
+        const result = new Map();
+        for (const [key, value] of plaintexts) {
+            result.set(key, encrypted.get(key) ?? value);
+        }
+        return result;
+    }
+    /**
+     * The codec for a stored value's version token, or the loud unavailable
+     * refusal — the Java registry's "no codec for this version" contract.
+     */
+    codecFor(token) {
+        const codec = this.codecs.get(token);
+        if (codec === undefined) {
+            const registered = [...this.codecs.keys()].sort().join(", ");
+            throw new EncryptionUnavailableError(`unsupported encrypted-value version '${token}' - this deployment decrypts only [${registered}]. The value was written by a format this deployment has no codec for; fix the deployment before reading it.`);
+        }
+        return codec;
+    }
+}
+/** The facade-owned fallback for codecs without a native batch encrypt. */
+async function loopEncryptAll(codec, plaintexts, scope) {
+    const result = new Map();
+    for (const [key, value] of plaintexts) {
+        result.set(key, await codec.encrypt(value, scope));
+    }
+    return result;
+}
+/** The facade-owned fallback for codecs without a native batch decrypt. */
+async function loopDecryptAll(codec, encrypted) {
+    const result = new Map();
+    for (const [key, value] of encrypted) {
+        result.set(key, await codec.decrypt(value));
+    }
+    return result;
+}
+//# sourceMappingURL=encryption.js.map

package/dist/encryption/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../src/encryption/encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGjE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD,0EAA0E;AAC1E,wEAAwE;AACxE,sEAAsE;AACtE,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9D,wEAAwE;AACxE,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,kDAAkD;AAClD,MAAM,CAAC,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAC3C,kCAAkC,CAAC;AAErC,qEAAqE;AACrE,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAExC,wEAAwE;AACxE,MAAM,aAAa,GAAG,UAAU,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED,qEAAqE;AACrE,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IACP,MAAM,CAAmC;IACzC,UAAU,CAAc;IACzC,2EAA2E;IAC1D,kBAAkB,CAAS;IAE5C,YACE,MAAwC,EACxC,UAAuB,EACvB,kBAA0B;QAE1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,GAAuB;QACnC,OAAO,aAAa,CAAC,UAAU,CAAC;YAC9B,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9D,YAAY,EAAE,UAAU;SACzB,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,UAA4B,EAAE;QAC3C,MAAM,GAAG,GAAG,mBAAmB,CAC7B,sBAAsB,EACtB,wBAAwB,EACxB,OAAO,CACR,CAAC;QACF,OAAO,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,OAGjB;QACC,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAC5C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,KAAK,CACb,kCAAkC,KAAK,wEAAwE,CAChH,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,kCAAkC,KAAK,uBAAuB,KAAK,CAAC,OAAO,yDAAyD,CACrI,CAAC;YACJ,CAAC;QACH,CAAC;QACD,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC5D,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,UAAU,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChE,MAAM,IAAI,KAAK,CACb,GAAG,gCAAgC,QAAQ,OAAO,CAAC,YAAY,0DAA0D,UAAU,wEAAwE,CAC5M,CAAC;QACJ,CAAC;QACD,sEAAsE;QACtE,MAAM,kBAAkB,GAAG,MAAM,CAC/B,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAC9C,CAAC;QACF,OAAO,IAAI,aAAa,CACtB,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EACvB,UAAU,EACV,kBAAkB,CACnB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,EAAE,IAAI,IAAI,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,KAAa;QACvB,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,KAAa;QACrB,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3C,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,KAAsB;QACrD,IAAI,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CACd,UAAuC,EACvC,KAAsB;QAEtB,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,kBAAkB,CACtB,UAAuC,EACvC,KAAsB;QAEtB,MAAM,KAAK,GACT,IAAI,CAAC,kBAAkB,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB;QAC7B,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CACd,SAAsC;QAEtC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA+B,CAAC;QACzD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,IAAI,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;gBAClC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC9B,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC5C,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,WAAW,GACf,KAAK,CAAC,UAAU,KAAK,SAAS;gBAC5B,CAAC,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC;gBAC/B,CAAC,CAAC,MAAM,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;gBACvC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;YACrC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CAAC,WAAmB;QAC9B,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QACD,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,SAAS,CACb,WAAmB,EACnB,KAAsB;QAEtB,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;YACvB,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,IAAI,WAAW,KAAK,eAAe,EAAE,CAAC;YACpC,MAAM,IAAI,sBAAsB,CAC9B,wHAAwH,CACzH,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAC5C,IAAI,SAAiB,CAAC;QACtB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,OAAO,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBACvC,OAAO,WAAW,CAAC;YACrB,CAAC;YACD,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,WAAW,CAAC;QAC1B,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACpE,mEAAmE;QACnE,sEAAsE;QACtE,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACrD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,sBAAsB,CAC9B,sDACE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,WAC1C,+BAA+B,IAAI,CAAC,UAAU,CAAC,OAAO,6HAA6H,CACpL,CAAC;QACJ,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,uEAAuE;IAC/D,KAAK,CAAC,cAAc,CAC1B,KAAkB,EAClB,UAAuC,EACvC,KAAsB;QAEtB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC5C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,EAAE,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,MAAM,SAAS,GACb,SAAS,CAAC,IAAI,KAAK,CAAC;YAClB,CAAC,CAAC,IAAI,GAAG,EAAkB;YAC3B,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS;gBAC9B,CAAC,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC;gBAC1C,CAAC,CAAC,MAAM,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QAEtD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,QAAQ,CAAC,KAAa;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7D,MAAM,IAAI,0BAA0B,CAClC,wCAAwC,KAAK,sCAAsC,UAAU,8GAA8G,CAC5M,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAED,2EAA2E;AAC3E,KAAK,UAAU,cAAc,CAC3B,KAAkB,EAClB,UAAuC,EACvC,KAAsB;IAEtB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2EAA2E;AAC3E,KAAK,UAAU,cAAc,CAC3B,KAAkB,EAClB,SAAsC;IAEtC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/encryption/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The secret-encryption error taxonomy — two arms, mirroring the cloud
+ * edition's SecretEncryptionService exception pair (EncryptionException →
+ * InvalidCiphertext / EncryptionUnavailable), because "skip this one
+ * value" is safe for exactly one of them:
+ *
+ *   - InvalidCiphertextError (and its wrong-key/tampered specialization
+ *     DecryptionFailedError): the VALUE is bad — tampered, truncated,
+ *     malformed Base64, or sealed under a different key. Retrying cannot
+ *     help and the failure is scoped to that one value, so per-key skip
+ *     policies (the environment/executioncontext resolution lanes) may
+ *     drop it and continue.
+ *
+ *   - EncryptionUnavailableError (and its keyless specialization
+ *     EncryptionDisabledError): the MACHINERY is missing — the value's
+ *     version has no codec in this deployment, no key is configured, or a
+ *     codec's external key provider is unreachable. The stored value may
+ *     be perfectly valid, so skipping would silently drop a credential on
+ *     a transient infrastructure failure; callers must let this arm
+ *     propagate (the resolution lanes fail the request on it).
+ *
+ * The four concrete classes predate the arms (they are blessed exports the
+ * cloud composition catches); the arms were introduced by re-parenting
+ * (20260830.04 Stage 1) so every existing `instanceof` keeps its meaning
+ * and every `.name` and message byte stays exactly as shipped.
+ */
+/**
+ * Go ErrInvalidCiphertext — the value itself is bad (bad base64, too
+ * short, or — via the DecryptionFailedError subclass — wrong key or
+ * tampered bytes). The value-scoped arm: per-key skip policies may skip
+ * it and continue.
+ */
+export declare class InvalidCiphertextError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Go ErrDecryptionFailed — wrong key or tampered data. A specialization
+ * of InvalidCiphertextError (the cloud edition folds this case into
+ * InvalidCiphertext outright): the failure is still scoped to the one
+ * value, so it rides the value-scoped arm.
+ */
+export declare class DecryptionFailedError extends InvalidCiphertextError {
+    constructor(cause: unknown);
+}
+/**
+ * The machinery needed to process an otherwise-plausible value is
+ * unavailable: the value carries a format version this deployment has no
+ * codec for, or a codec's key machinery cannot be reached. The stored
+ * value may be perfectly valid — treating this like InvalidCiphertextError
+ * and skipping would silently drop a credential, so callers must let it
+ * propagate. Ports the cloud edition's EncryptionUnavailableException.
+ */
+export declare class EncryptionUnavailableError extends Error {
+    constructor(message: string);
+}
+/**
+ * Go ErrEncryptionDisabled — decrypting a prefixed value with no key
+ * configured. A specialization of EncryptionUnavailableError: keyless is
+ * one instance of "machinery missing" (the stored ciphertext may be
+ * perfectly valid — e.g. the key file was lost), so it rides the
+ * infrastructure arm the resolution lanes propagate.
+ */
+export declare class EncryptionDisabledError extends EncryptionUnavailableError {
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/encryption/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/encryption/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,MAAM,EAAE,MAAM;CAI3B;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,sBAAsB;gBACnD,KAAK,EAAE,OAAO;CAS3B;AAED;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,0BAA0B;;CAKtE"}

package/dist/encryption/errors.js

@@ -0,0 +1,83 @@
+/**
+ * The secret-encryption error taxonomy — two arms, mirroring the cloud
+ * edition's SecretEncryptionService exception pair (EncryptionException →
+ * InvalidCiphertext / EncryptionUnavailable), because "skip this one
+ * value" is safe for exactly one of them:
+ *
+ *   - InvalidCiphertextError (and its wrong-key/tampered specialization
+ *     DecryptionFailedError): the VALUE is bad — tampered, truncated,
+ *     malformed Base64, or sealed under a different key. Retrying cannot
+ *     help and the failure is scoped to that one value, so per-key skip
+ *     policies (the environment/executioncontext resolution lanes) may
+ *     drop it and continue.
+ *
+ *   - EncryptionUnavailableError (and its keyless specialization
+ *     EncryptionDisabledError): the MACHINERY is missing — the value's
+ *     version has no codec in this deployment, no key is configured, or a
+ *     codec's external key provider is unreachable. The stored value may
+ *     be perfectly valid, so skipping would silently drop a credential on
+ *     a transient infrastructure failure; callers must let this arm
+ *     propagate (the resolution lanes fail the request on it).
+ *
+ * The four concrete classes predate the arms (they are blessed exports the
+ * cloud composition catches); the arms were introduced by re-parenting
+ * (20260830.04 Stage 1) so every existing `instanceof` keeps its meaning
+ * and every `.name` and message byte stays exactly as shipped.
+ */
+/**
+ * Go ErrInvalidCiphertext — the value itself is bad (bad base64, too
+ * short, or — via the DecryptionFailedError subclass — wrong key or
+ * tampered bytes). The value-scoped arm: per-key skip policies may skip
+ * it and continue.
+ */
+export class InvalidCiphertextError extends Error {
+    constructor(detail) {
+        super(`invalid ciphertext format: ${detail}`);
+        this.name = "InvalidCiphertextError";
+    }
+}
+/**
+ * Go ErrDecryptionFailed — wrong key or tampered data. A specialization
+ * of InvalidCiphertextError (the cloud edition folds this case into
+ * InvalidCiphertext outright): the failure is still scoped to the one
+ * value, so it rides the value-scoped arm.
+ */
+export class DecryptionFailedError extends InvalidCiphertextError {
+    constructor(cause) {
+        super("wrong key or tampered data");
+        // This class shipped before the taxonomy fold, so its copy does not
+        // carry the parent's "invalid ciphertext format:" prefix — preserved
+        // byte-for-byte (the message reaches logs at the resolution lanes).
+        this.message = "decryption failed - wrong key or tampered data";
+        this.name = "DecryptionFailedError";
+        this.cause = cause;
+    }
+}
+/**
+ * The machinery needed to process an otherwise-plausible value is
+ * unavailable: the value carries a format version this deployment has no
+ * codec for, or a codec's key machinery cannot be reached. The stored
+ * value may be perfectly valid — treating this like InvalidCiphertextError
+ * and skipping would silently drop a credential, so callers must let it
+ * propagate. Ports the cloud edition's EncryptionUnavailableException.
+ */
+export class EncryptionUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EncryptionUnavailableError";
+    }
+}
+/**
+ * Go ErrEncryptionDisabled — decrypting a prefixed value with no key
+ * configured. A specialization of EncryptionUnavailableError: keyless is
+ * one instance of "machinery missing" (the stored ciphertext may be
+ * perfectly valid — e.g. the key file was lost), so it rides the
+ * infrastructure arm the resolution lanes propagate.
+ */
+export class EncryptionDisabledError extends EncryptionUnavailableError {
+    constructor() {
+        super("encryption is not enabled - no key configured");
+        this.name = "EncryptionDisabledError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/encryption/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/encryption/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,MAAc;QACxB,KAAK,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,qBAAsB,SAAQ,sBAAsB;IAC/D,YAAY,KAAc;QACxB,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACpC,oEAAoE;QACpE,qEAAqE;QACrE,oEAAoE;QACpE,IAAI,CAAC,OAAO,GAAG,gDAAgD,CAAC;QAChE,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,uBAAwB,SAAQ,0BAA0B;IACrE;QACE,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/encryption/key-manager.d.ts

@@ -0,0 +1,23 @@
+/** AES-256 / HMAC-SHA256 key size (32 bytes = 256 bits) — Go KeySize. */
+export declare const KEY_SIZE = 32;
+/** Directory under home for key files — Go KeyFileDir. */
+export declare const KEY_FILE_DIR = ".stigmer";
+/** Key file permissions (owner read/write only) — Go KeyFilePermissions. */
+export declare const KEY_FILE_PERMISSIONS = 384;
+/** Key directory permissions — Go KeyDirPermissions. */
+export declare const KEY_DIR_PERMISSIONS = 448;
+export interface KeyLoaderOptions {
+    /** Environment map; defaults to the live process env. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Home directory for ~/.stigmer; defaults to os.homedir(). */
+    readonly homeDir?: string;
+}
+/**
+ * Go GetOrCreateNamedKey: env var → key file → auto-generate. Throws only
+ * on unusable EXPLICIT configuration (bad env value) or when no key can be
+ * produced at all.
+ */
+export declare function getOrCreateNamedKey(envVar: string, fileName: string, options?: KeyLoaderOptions): Buffer;
+/** Path to a named key file under <home>/.stigmer. */
+export declare function namedKeyFilePath(fileName: string, options?: KeyLoaderOptions): string;
+//# sourceMappingURL=key-manager.d.ts.map

package/dist/encryption/key-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-manager.d.ts","sourceRoot":"","sources":["../../src/encryption/key-manager.ts"],"names":[],"mappings":"AAgCA,yEAAyE;AACzE,eAAO,MAAM,QAAQ,KAAK,CAAC;AAE3B,0DAA0D;AAC1D,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,MAAQ,CAAC;AAE1C,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,MAAQ,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CA2BR;AAoBD,sDAAsD;AACtD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CAGR"}