@btravstack/keys 0.0.0-stage → 0.45.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @btravstack/keys
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> An `EnvelopeKeys` port for [`@btravstack/core`](../core): a root key per
+> owner, in generations, wrapped by an AWS KMS key of that owner — unwrapped in
+> memory and cached for a TTL, erased with one key deletion — and an HKDF
+> helper giving each purpose its own key.
+
+📖 **[Documentation](https://btravstack.github.io/btravstack/reference/keys)** ·
+[API Reference](https://btravstack.github.io/btravstack/api/keys/)
+
+```sh
+pnpm add @btravstack/keys @btravstack/core @btravstack/config @btravstack/di unthrown
+pnpm add @aws-sdk/client-kms # for @btravstack/keys/kms
+```
+
+Every dependency is a peer, and `@aws-sdk/client-kms` an optional one: only
+`@btravstack/keys/kms` imports it.
+
+## A worked example
+
+<!-- doctest: prelude
+import { Module, Port, Provider } from "@btravstack/di";
+import type { AsyncResult } from "unthrown";
+-->
+
+A port that seals a tenant's payloads under a key of that tenant's own, and
+the composition that provides the keys:
+
+```ts
+import {
+  EnvelopeKeys,
+  deriveKey,
+  type InvalidKeyPurpose,
+  type KeyErased,
+  type KeyGeneration,
+  type KeysUnavailable,
+} from "@btravstack/keys";
+import { kmsKeys } from "@btravstack/keys/kms";
+
+class PayloadKeys extends Port("ReadmePayloadKeys")<{
+  readonly key: (
+    generation: KeyGeneration,
+  ) => AsyncResult<CryptoKey, KeyErased | KeysUnavailable | InvalidKeyPurpose>;
+}> {}
+
+export const payloadKeys = Provider(PayloadKeys)({
+  inject: { keys: EnvelopeKeys },
+  sync: ({ keys }) => ({
+    key: (generation) =>
+      keys.rootKey(generation).flatMap((root) =>
+        deriveKey(root, { namespace: "payloads", purpose: "seal", version: 1 }, {
+          algorithm: { name: "AES-GCM", length: 256 },
+          usages: ["encrypt", "decrypt"],
+        }),
+      ),
+  }),
+});
+
+export const Sealing = Module("ReadmeSealing")({
+  imports: [kmsKeys()],
+  provides: [payloadKeys],
+  exports: [PayloadKeys],
+});
+```
+
+Provisioning a generation, rotating, erasing a tenant in one call and sizing
+the cache are
+[Keep envelope keys per owner](https://btravstack.github.io/btravstack/how-to/keep-envelope-keys-per-owner).
+
+## Options
+
+| Option                         | Where                                      | What it is                                                |
+| ------------------------------ | ------------------------------------------ | --------------------------------------------------------- |
+| `KEYS_KMS_REGION`              | environment                                | the region of the owners' KMS keys — required             |
+| `KEYS_KMS_ALIAS_PREFIX`        | environment                                | an owner's KMS key is `<prefix><owner>` — required        |
+| `KEYS_KMS_ENDPOINT`            | environment, pinned by `endpoint`          | an emulator or a VPC endpoint (default: AWS's own)        |
+| `KEYS_CACHE_TTL_MS`            | environment, pinned by `cacheTtlMs`        | how long an unwrapped root is kept (default five minutes) |
+| `KEYS_KMS_PENDING_WINDOW_DAYS` | environment, pinned by `pendingWindowDays` | the days an erasure can be cancelled (default `30`)       |
+| `clock`                        | `kmsKeys({ … })`                           | what the cache's TTL is measured against                  |
+
+The full table — defaults, semantics and the reasoning — lives on
+[the reference page](https://btravstack.github.io/btravstack/reference/keys),
+which is this list's one detailed home.
+
+## What it decides, and what it does not
+
+**It decides** that a generation is a KMS data key bound by the encryption
+context `{ owner, keyId }`, so a blob presented for another owner or key id is
+refused rather than unwrapped; that a disabled, deleted, missing or refusing
+key is a typed `KeyErased` and anything else KMS says a typed
+`KeysUnavailable`; that erasing an owner is one scheduled key deletion; that
+every KMS request is reported to `Observers`; and that a derived key is
+HKDF-SHA-256 with `info = <namespace>/<purpose>/v<version>`.
+
+**It does not decide** where the wrapped generations are kept, which one
+encrypts next, or how the owners' KMS keys are created: those are the
+application's and the platform's. The reasoning is in
+[`AGENTS.md`](./AGENTS.md).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,42 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_keys = require("./keys-DtMnWJHq.cjs");
+let unthrown = require("unthrown");
+//#region src/derive.ts
+/** A purpose whose `info` would be ambiguous: a segment outside the alphabet, or a version that is not a positive integer. */
+var InvalidKeyPurpose = class extends (0, unthrown.TaggedError)("InvalidKeyPurpose") {
+	message = "the key purpose is not a valid HKDF info";
+};
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+/**
+* A key for one purpose, derived from a root key with HKDF-SHA-256, an empty
+* salt and `info = <namespace>/<purpose>/v<version>`.
+*
+* ```ts
+* keys.rootKey(generation).flatMap((root) =>
+*   deriveKey(root, { namespace: "payloads", purpose: "seal", version: 1 }, {
+*     algorithm: { name: "AES-GCM", length: 256 },
+*     usages: ["encrypt", "decrypt"],
+*   }),
+* );
+* ```
+*
+* Every purpose gets its own key, and so its own nonce budget: two uses of
+* random 96-bit AES-GCM nonces never draw from one key. The salt is empty
+* because the root is already uniformly random (RFC 5869, section 3.1).
+*/
+const deriveKey = (root, purpose, derived) => SEGMENT.test(purpose.namespace) && SEGMENT.test(purpose.purpose) && Number.isSafeInteger(purpose.version) && purpose.version > 0 ? (0, unthrown.fromSafePromise)(crypto.subtle.deriveKey({
+	name: "HKDF",
+	hash: "SHA-256",
+	salt: /* @__PURE__ */ new Uint8Array(0),
+	info: new TextEncoder().encode(`${purpose.namespace}/${purpose.purpose}/v${purpose.version}`)
+}, root, derived.algorithm, false, [...derived.usages])) : (0, unthrown.ErrAsync)(new InvalidKeyPurpose({
+	namespace: purpose.namespace,
+	purpose: purpose.purpose,
+	version: purpose.version
+}));
+//#endregion
+exports.EnvelopeKeys = require_keys.EnvelopeKeys;
+exports.InvalidKeyPurpose = InvalidKeyPurpose;
+exports.KeyErased = require_keys.KeyErased;
+exports.KeysUnavailable = require_keys.KeysUnavailable;
+exports.deriveKey = deriveKey;

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+import { a as KeysUnavailable, i as KeyGeneration, n as EnvelopeKeysService, r as KeyErased, t as EnvelopeKeys } from "./keys-DpvmIcWy.cjs";
+import { webcrypto } from "node:crypto";
+import { AsyncResult } from "unthrown";
+//#region src/derive.d.ts
+/**
+ * What a derived key is for, spelled into HKDF's `info` as
+ * `<namespace>/<purpose>/v<version>`. Each segment is ASCII letters, digits,
+ * `.`, `_` or `-`, so no two purposes spell the same `info`; `version` is a
+ * positive integer, raised to retire a derived key without a new root.
+ */
+type KeyPurpose = {
+  readonly namespace: string;
+  readonly purpose: string;
+  readonly version: number;
+};
+/** What the derived key is, as WebCrypto's `deriveKey` takes it. It is never extractable. */
+type DerivedKey = {
+  readonly algorithm: webcrypto.AesDerivedKeyParams | webcrypto.HmacImportParams;
+  readonly usages: readonly webcrypto.KeyUsage[];
+};
+declare const InvalidKeyPurpose_base: import("unthrown").TaggedErrorConstructor<"InvalidKeyPurpose">;
+/** A purpose whose `info` would be ambiguous: a segment outside the alphabet, or a version that is not a positive integer. */
+export declare class InvalidKeyPurpose extends InvalidKeyPurpose_base<{
+  readonly namespace: string;
+  readonly purpose: string;
+  readonly version: number;
+}> {
+  message: string;
+}
+/**
+ * A key for one purpose, derived from a root key with HKDF-SHA-256, an empty
+ * salt and `info = <namespace>/<purpose>/v<version>`.
+ *
+ * ```ts
+ * keys.rootKey(generation).flatMap((root) =>
+ *   deriveKey(root, { namespace: "payloads", purpose: "seal", version: 1 }, {
+ *     algorithm: { name: "AES-GCM", length: 256 },
+ *     usages: ["encrypt", "decrypt"],
+ *   }),
+ * );
+ * ```
+ *
+ * Every purpose gets its own key, and so its own nonce budget: two uses of
+ * random 96-bit AES-GCM nonces never draw from one key. The salt is empty
+ * because the root is already uniformly random (RFC 5869, section 3.1).
+ */
+export declare const deriveKey: (root: CryptoKey, purpose: KeyPurpose, derived: DerivedKey) => AsyncResult<CryptoKey, InvalidKeyPurpose>;
+//#endregion
+export { type DerivedKey, EnvelopeKeys, type EnvelopeKeysService, KeyErased, type KeyGeneration, type KeyPurpose, KeysUnavailable };

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+import { a as KeysUnavailable, i as KeyGeneration, n as EnvelopeKeysService, r as KeyErased, t as EnvelopeKeys } from "./keys-DpvmIcWy.mjs";
+import { AsyncResult } from "unthrown";
+import { webcrypto } from "node:crypto";
+//#region src/derive.d.ts
+/**
+ * What a derived key is for, spelled into HKDF's `info` as
+ * `<namespace>/<purpose>/v<version>`. Each segment is ASCII letters, digits,
+ * `.`, `_` or `-`, so no two purposes spell the same `info`; `version` is a
+ * positive integer, raised to retire a derived key without a new root.
+ */
+type KeyPurpose = {
+  readonly namespace: string;
+  readonly purpose: string;
+  readonly version: number;
+};
+/** What the derived key is, as WebCrypto's `deriveKey` takes it. It is never extractable. */
+type DerivedKey = {
+  readonly algorithm: webcrypto.AesDerivedKeyParams | webcrypto.HmacImportParams;
+  readonly usages: readonly webcrypto.KeyUsage[];
+};
+declare const InvalidKeyPurpose_base: import("unthrown").TaggedErrorConstructor<"InvalidKeyPurpose">;
+/** A purpose whose `info` would be ambiguous: a segment outside the alphabet, or a version that is not a positive integer. */
+export declare class InvalidKeyPurpose extends InvalidKeyPurpose_base<{
+  readonly namespace: string;
+  readonly purpose: string;
+  readonly version: number;
+}> {
+  message: string;
+}
+/**
+ * A key for one purpose, derived from a root key with HKDF-SHA-256, an empty
+ * salt and `info = <namespace>/<purpose>/v<version>`.
+ *
+ * ```ts
+ * keys.rootKey(generation).flatMap((root) =>
+ *   deriveKey(root, { namespace: "payloads", purpose: "seal", version: 1 }, {
+ *     algorithm: { name: "AES-GCM", length: 256 },
+ *     usages: ["encrypt", "decrypt"],
+ *   }),
+ * );
+ * ```
+ *
+ * Every purpose gets its own key, and so its own nonce budget: two uses of
+ * random 96-bit AES-GCM nonces never draw from one key. The salt is empty
+ * because the root is already uniformly random (RFC 5869, section 3.1).
+ */
+export declare const deriveKey: (root: CryptoKey, purpose: KeyPurpose, derived: DerivedKey) => AsyncResult<CryptoKey, InvalidKeyPurpose>;
+//#endregion
+export { type DerivedKey, EnvelopeKeys, type EnvelopeKeysService, KeyErased, type KeyGeneration, type KeyPurpose, KeysUnavailable };

package/dist/index.mjs

@@ -0,0 +1,37 @@
+import { n as KeyErased, r as KeysUnavailable, t as EnvelopeKeys } from "./keys-CGbVjuu3.mjs";
+import { ErrAsync, TaggedError, fromSafePromise } from "unthrown";
+//#region src/derive.ts
+/** A purpose whose `info` would be ambiguous: a segment outside the alphabet, or a version that is not a positive integer. */
+var InvalidKeyPurpose = class extends TaggedError("InvalidKeyPurpose") {
+	message = "the key purpose is not a valid HKDF info";
+};
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+/**
+* A key for one purpose, derived from a root key with HKDF-SHA-256, an empty
+* salt and `info = <namespace>/<purpose>/v<version>`.
+*
+* ```ts
+* keys.rootKey(generation).flatMap((root) =>
+*   deriveKey(root, { namespace: "payloads", purpose: "seal", version: 1 }, {
+*     algorithm: { name: "AES-GCM", length: 256 },
+*     usages: ["encrypt", "decrypt"],
+*   }),
+* );
+* ```
+*
+* Every purpose gets its own key, and so its own nonce budget: two uses of
+* random 96-bit AES-GCM nonces never draw from one key. The salt is empty
+* because the root is already uniformly random (RFC 5869, section 3.1).
+*/
+const deriveKey = (root, purpose, derived) => SEGMENT.test(purpose.namespace) && SEGMENT.test(purpose.purpose) && Number.isSafeInteger(purpose.version) && purpose.version > 0 ? fromSafePromise(crypto.subtle.deriveKey({
+	name: "HKDF",
+	hash: "SHA-256",
+	salt: /* @__PURE__ */ new Uint8Array(0),
+	info: new TextEncoder().encode(`${purpose.namespace}/${purpose.purpose}/v${purpose.version}`)
+}, root, derived.algorithm, false, [...derived.usages])) : ErrAsync(new InvalidKeyPurpose({
+	namespace: purpose.namespace,
+	purpose: purpose.purpose,
+	version: purpose.version
+}));
+//#endregion
+export { EnvelopeKeys, InvalidKeyPurpose, KeyErased, KeysUnavailable, deriveKey };

package/dist/keys-CGbVjuu3.mjs

@@ -0,0 +1,29 @@
+import { TaggedError } from "unthrown";
+import { Port } from "@btravstack/di";
+//#region src/keys.ts
+/**
+* The generation can no longer be unwrapped, and never will be again: the
+* owner's key is disabled (`disabled`), scheduled for deletion
+* (`pending_deletion`), gone (`not_found`), or refused this ciphertext under
+* this owner and key id (`refused`). An answer, not an outage: whatever the
+* generation protected is erased.
+*/
+var KeyErased = class extends TaggedError("KeyErased") {
+	message = "the key generation is erased";
+};
+/**
+* The key-management service could not be asked: throttling, the network, a
+* credential or permission it refused, a server error. Transient or a
+* deployment mistake, never an erasure, so a later call asks again: a failure
+* is never cached.
+*/
+var KeysUnavailable = class extends TaggedError("KeysUnavailable") {
+	message = "the key-management service could not be asked";
+};
+/**
+* The port an application depends on for per-owner envelope keys.
+* `kmsKeys()` from `@btravstack/keys/kms` provides it over AWS KMS.
+*/
+var EnvelopeKeys = class extends Port("EnvelopeKeys") {};
+//#endregion
+export { KeyErased as n, KeysUnavailable as r, EnvelopeKeys as t };

package/dist/keys-DpvmIcWy.d.cts

@@ -0,0 +1,74 @@
+import { AsyncResult } from "unthrown";
+//#region src/keys.d.ts
+/**
+ * One generation of an owner's root key, as it is kept: wrapped by the
+ * owner's key-management key, under an encryption context that binds `owner`
+ * and `keyId`.
+ *
+ * `wrapped` is not secret — only the key-management service can unwrap it, and
+ * only for this owner and this key id — so it may live wherever the
+ * application keeps configuration: a mounted Secret, a file, an object store,
+ * a database row.
+ */
+type KeyGeneration = {
+  readonly owner: string;
+  readonly keyId: string;
+  readonly wrapped: Uint8Array;
+};
+declare const KeyErased_base: import("unthrown").TaggedErrorConstructor<"KeyErased">;
+/**
+ * The generation can no longer be unwrapped, and never will be again: the
+ * owner's key is disabled (`disabled`), scheduled for deletion
+ * (`pending_deletion`), gone (`not_found`), or refused this ciphertext under
+ * this owner and key id (`refused`). An answer, not an outage: whatever the
+ * generation protected is erased.
+ */
+declare class KeyErased extends KeyErased_base<{
+  readonly owner: string;
+  readonly keyId: string;
+  readonly reason: "disabled" | "pending_deletion" | "not_found" | "refused";
+}> {
+  message: string;
+}
+declare const KeysUnavailable_base: import("unthrown").TaggedErrorConstructor<"KeysUnavailable">;
+/**
+ * The key-management service could not be asked: throttling, the network, a
+ * credential or permission it refused, a server error. Transient or a
+ * deployment mistake, never an erasure, so a later call asks again: a failure
+ * is never cached.
+ */
+declare class KeysUnavailable extends KeysUnavailable_base<{
+  readonly operation: "unwrap" | "provision" | "erase";
+  readonly owner: string;
+  readonly cause: unknown;
+}> {
+  message: string;
+}
+type EnvelopeKeysService = {
+  /**
+   * The generation's root key, unwrapped in memory: a non-extractable HKDF
+   * key, to derive a key per purpose from with `deriveKey`. Kept for the
+   * cache's TTL; callers asking while it is being unwrapped share one request.
+   */
+  readonly rootKey: (generation: KeyGeneration) => AsyncResult<CryptoKey, KeyErased | KeysUnavailable>;
+  /**
+   * A new generation under the owner's key, for the application to keep.
+   * Rotation is provisioning another key id; the old generations stay
+   * readable until the owner is erased.
+   */
+  readonly provision: (owner: string, keyId: string) => AsyncResult<KeyGeneration, KeyErased | KeysUnavailable>;
+  /**
+   * Every generation of the owner, erased at once: the owner's key is
+   * scheduled for deletion, so from then on each generation answers
+   * `KeyErased`. Erasing an owner already erased answers `Ok`.
+   */
+  readonly erase: (owner: string) => AsyncResult<void, KeysUnavailable>;
+};
+declare const EnvelopeKeys_base: import("@btravstack/di").PortClass<"EnvelopeKeys">;
+/**
+ * The port an application depends on for per-owner envelope keys.
+ * `kmsKeys()` from `@btravstack/keys/kms` provides it over AWS KMS.
+ */
+declare class EnvelopeKeys extends EnvelopeKeys_base<EnvelopeKeysService> {}
+//#endregion
+export { KeysUnavailable as a, KeyGeneration as i, EnvelopeKeysService as n, KeyErased as r, EnvelopeKeys as t };

package/dist/keys-DpvmIcWy.d.mts

@@ -0,0 +1,74 @@
+import { AsyncResult } from "unthrown";
+//#region src/keys.d.ts
+/**
+ * One generation of an owner's root key, as it is kept: wrapped by the
+ * owner's key-management key, under an encryption context that binds `owner`
+ * and `keyId`.
+ *
+ * `wrapped` is not secret — only the key-management service can unwrap it, and
+ * only for this owner and this key id — so it may live wherever the
+ * application keeps configuration: a mounted Secret, a file, an object store,
+ * a database row.
+ */
+type KeyGeneration = {
+  readonly owner: string;
+  readonly keyId: string;
+  readonly wrapped: Uint8Array;
+};
+declare const KeyErased_base: import("unthrown").TaggedErrorConstructor<"KeyErased">;
+/**
+ * The generation can no longer be unwrapped, and never will be again: the
+ * owner's key is disabled (`disabled`), scheduled for deletion
+ * (`pending_deletion`), gone (`not_found`), or refused this ciphertext under
+ * this owner and key id (`refused`). An answer, not an outage: whatever the
+ * generation protected is erased.
+ */
+declare class KeyErased extends KeyErased_base<{
+  readonly owner: string;
+  readonly keyId: string;
+  readonly reason: "disabled" | "pending_deletion" | "not_found" | "refused";
+}> {
+  message: string;
+}
+declare const KeysUnavailable_base: import("unthrown").TaggedErrorConstructor<"KeysUnavailable">;
+/**
+ * The key-management service could not be asked: throttling, the network, a
+ * credential or permission it refused, a server error. Transient or a
+ * deployment mistake, never an erasure, so a later call asks again: a failure
+ * is never cached.
+ */
+declare class KeysUnavailable extends KeysUnavailable_base<{
+  readonly operation: "unwrap" | "provision" | "erase";
+  readonly owner: string;
+  readonly cause: unknown;
+}> {
+  message: string;
+}
+type EnvelopeKeysService = {
+  /**
+   * The generation's root key, unwrapped in memory: a non-extractable HKDF
+   * key, to derive a key per purpose from with `deriveKey`. Kept for the
+   * cache's TTL; callers asking while it is being unwrapped share one request.
+   */
+  readonly rootKey: (generation: KeyGeneration) => AsyncResult<CryptoKey, KeyErased | KeysUnavailable>;
+  /**
+   * A new generation under the owner's key, for the application to keep.
+   * Rotation is provisioning another key id; the old generations stay
+   * readable until the owner is erased.
+   */
+  readonly provision: (owner: string, keyId: string) => AsyncResult<KeyGeneration, KeyErased | KeysUnavailable>;
+  /**
+   * Every generation of the owner, erased at once: the owner's key is
+   * scheduled for deletion, so from then on each generation answers
+   * `KeyErased`. Erasing an owner already erased answers `Ok`.
+   */
+  readonly erase: (owner: string) => AsyncResult<void, KeysUnavailable>;
+};
+declare const EnvelopeKeys_base: import("@btravstack/di").PortClass<"EnvelopeKeys">;
+/**
+ * The port an application depends on for per-owner envelope keys.
+ * `kmsKeys()` from `@btravstack/keys/kms` provides it over AWS KMS.
+ */
+declare class EnvelopeKeys extends EnvelopeKeys_base<EnvelopeKeysService> {}
+//#endregion
+export { KeysUnavailable as a, KeyGeneration as i, EnvelopeKeysService as n, KeyErased as r, EnvelopeKeys as t };

package/dist/keys-DtMnWJHq.cjs

@@ -0,0 +1,46 @@
+let unthrown = require("unthrown");
+let _btravstack_di = require("@btravstack/di");
+//#region src/keys.ts
+/**
+* The generation can no longer be unwrapped, and never will be again: the
+* owner's key is disabled (`disabled`), scheduled for deletion
+* (`pending_deletion`), gone (`not_found`), or refused this ciphertext under
+* this owner and key id (`refused`). An answer, not an outage: whatever the
+* generation protected is erased.
+*/
+var KeyErased = class extends (0, unthrown.TaggedError)("KeyErased") {
+	message = "the key generation is erased";
+};
+/**
+* The key-management service could not be asked: throttling, the network, a
+* credential or permission it refused, a server error. Transient or a
+* deployment mistake, never an erasure, so a later call asks again: a failure
+* is never cached.
+*/
+var KeysUnavailable = class extends (0, unthrown.TaggedError)("KeysUnavailable") {
+	message = "the key-management service could not be asked";
+};
+/**
+* The port an application depends on for per-owner envelope keys.
+* `kmsKeys()` from `@btravstack/keys/kms` provides it over AWS KMS.
+*/
+var EnvelopeKeys = class extends (0, _btravstack_di.Port)("EnvelopeKeys") {};
+//#endregion
+Object.defineProperty(exports, "EnvelopeKeys", {
+	enumerable: true,
+	get: function() {
+		return EnvelopeKeys;
+	}
+});
+Object.defineProperty(exports, "KeyErased", {
+	enumerable: true,
+	get: function() {
+		return KeyErased;
+	}
+});
+Object.defineProperty(exports, "KeysUnavailable", {
+	enumerable: true,
+	get: function() {
+		return KeysUnavailable;
+	}
+});

package/dist/kms.cjs

@@ -0,0 +1,211 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_keys = require("./keys-DtMnWJHq.cjs");
+let unthrown = require("unthrown");
+let _btravstack_di = require("@btravstack/di");
+let _aws_sdk_client_kms = require("@aws-sdk/client-kms");
+let _btravstack_config = require("@btravstack/config");
+let _btravstack_core = require("@btravstack/core");
+//#region src/kms.ts
+/** What the graph bound from the environment for the KMS adapter. */
+var KeysConfig = class extends (0, _btravstack_di.Port)("KeysConfig") {};
+/** The client, as a port of its own, so the scope closing destroys it. */
+var KmsConnection = class extends (0, _btravstack_di.Port)("KmsConnection") {};
+const optionalUrl = (variable) => {
+	const url = _btravstack_config.Config.url(variable);
+	return {
+		variable,
+		parse: (raw) => raw === void 0 ? (0, unthrown.Ok)(void 0) : url.parse(raw),
+		check: (value) => url.parse(String(value))
+	};
+};
+/**
+* `EnvelopeKeys` over AWS KMS, with one KMS key per owner, named by the alias
+* `<KEYS_KMS_ALIAS_PREFIX><owner>`.
+*
+* ```ts
+* Module("Documents")({ imports: [kmsKeys()], provides: [sealer] });
+* ```
+*
+* - **Configured from `KEYS_KMS_REGION` and `KEYS_KMS_ALIAS_PREFIX`** (an
+*   alias prefix, `alias/tenant-` say), and the pinnable variables of
+*   {@link KmsKeysOptions}. Credentials are the AWS SDK's default chain: a
+*   workload identity, an instance profile, or `AWS_*` variables.
+* - **A generation is a KMS data key**: `provision` asks
+*   `GenerateDataKeyWithoutPlaintext` for an AES-256 key under the owner's
+*   KMS key, and `rootKey` unwraps it with `Decrypt`, both with the encryption
+*   context `{ owner, keyId }` and the owner's alias as the key, so a blob
+*   handed in for another owner or key id is refused rather than unwrapped.
+* - **Erasure is one key deletion**: `erase` resolves the owner's alias and
+*   schedules its key's deletion, after which KMS refuses every generation of
+*   the owner. This process forgets the keys it kept at once; another
+*   process keeps serving its own until they expire, which is what
+*   `KEYS_CACHE_TTL_MS` bounds.
+* - **Refusals are answers**: a disabled, deleted, missing or refusing key is
+*   `KeyErased`; anything else KMS says is `KeysUnavailable`, never cached.
+* - **Every KMS request is reported to `Observers`** (`component: "keys"`); a
+*   key served from memory reports nothing.
+*/
+const kmsKeys = (options = {}) => (0, _btravstack_di.Module)("KmsKeys")({
+	needs: [_btravstack_config.Env],
+	provides: [
+		_btravstack_core.noObserverMember,
+		_btravstack_config.Config.provider(KeysConfig)(_btravstack_config.Config.object({
+			region: _btravstack_config.Config.string("KEYS_KMS_REGION"),
+			aliasPrefix: _btravstack_config.Config.string("KEYS_KMS_ALIAS_PREFIX"),
+			endpoint: _btravstack_config.Config.pinned(options.endpoint, optionalUrl("KEYS_KMS_ENDPOINT")),
+			cacheTtlMs: _btravstack_config.Config.pinned(options.cacheTtlMs, _btravstack_config.Config.integer("KEYS_CACHE_TTL_MS", {
+				default: 3e5,
+				min: 0
+			})),
+			pendingWindowDays: _btravstack_config.Config.pinned(options.pendingWindowDays, _btravstack_config.Config.integer("KEYS_KMS_PENDING_WINDOW_DAYS", {
+				default: 30,
+				min: 7,
+				max: 30
+			}))
+		})),
+		(0, _btravstack_di.Provider)(KmsConnection)({
+			inject: { config: KeysConfig },
+			acquire: ({ config }) => (0, unthrown.Ok)(new _aws_sdk_client_kms.KMSClient({
+				region: config.region,
+				...config.endpoint === void 0 ? {} : { endpoint: config.endpoint }
+			})),
+			release: (client) => client.destroy()
+		}),
+		(0, _btravstack_di.Provider)(require_keys.EnvelopeKeys)({
+			inject: {
+				config: KeysConfig,
+				client: KmsConnection,
+				observers: _btravstack_core.Observers
+			},
+			sync: ({ config, client, observers }) => kmsEnvelopeKeys(client, config, observers, options.clock ?? _btravstack_core.systemClock)
+		})
+	],
+	exports: [require_keys.EnvelopeKeys]
+});
+/** The KMS errors that mean the generation will never be unwrapped again, and the reason each one gives. */
+const ERASED = /* @__PURE__ */ new Map([
+	["DisabledException", "disabled"],
+	["KMSInvalidStateException", "pending_deletion"],
+	["NotFoundException", "not_found"],
+	["InvalidCiphertextException", "refused"],
+	["IncorrectKeyException", "refused"]
+]);
+const GONE = /* @__PURE__ */ new Set(["NotFoundException", "KMSInvalidStateException"]);
+const nameOf = (cause) => Object(cause).name;
+const kmsEnvelopeKeys = (client, config, observers, clock) => {
+	const cached = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	const aliasOf = (owner) => `${config.aliasPrefix}${owner}`;
+	const through = (name, owner, keyId, call) => (0, _btravstack_core.observed)(observers, {
+		component: "keys",
+		name,
+		attributes: { operation: name },
+		details: {
+			"btravstack.keys.owner": owner,
+			...keyId === void 0 ? {} : { "btravstack.keys.key_id": keyId }
+		}
+	}, call, {
+		ok: () => ({
+			outcome: "ok",
+			attributes: { result: "ok" }
+		}),
+		failure: settled
+	});
+	const request = (operation, generation, send) => (0, unthrown.fromPromise)(send(), (cause) => {
+		const reason = ERASED.get(nameOf(cause));
+		return reason === void 0 ? new require_keys.KeysUnavailable({
+			operation,
+			owner: generation.owner,
+			cause
+		}) : new require_keys.KeyErased({
+			owner: generation.owner,
+			keyId: generation.keyId,
+			reason
+		});
+	});
+	const unwrap = (entry, generation) => {
+		const { owner, keyId } = generation;
+		const unwrapping = through("unwrap", owner, keyId, () => request("unwrap", generation, () => client.send(new _aws_sdk_client_kms.DecryptCommand({
+			CiphertextBlob: generation.wrapped,
+			KeyId: aliasOf(owner),
+			EncryptionContext: {
+				owner,
+				keyId
+			}
+		}))).flatMap(({ Plaintext }) => {
+			const plaintext = Plaintext;
+			return (0, unthrown.fromSafePromise)(crypto.subtle.importKey("raw", plaintext, "HKDF", false, ["deriveKey", "deriveBits"]).finally(() => plaintext.fill(0)));
+		})).tap((root) => {
+			inFlight.delete(entry);
+			const now = clock.now();
+			for (const [key, kept] of cached) if (kept.expiresAt <= now) cached.delete(key);
+			cached.set(entry, {
+				owner,
+				root,
+				expiresAt: now + config.cacheTtlMs
+			});
+		}).tapFailure(() => inFlight.delete(entry));
+		inFlight.set(entry, unwrapping);
+		return unwrapping;
+	};
+	return {
+		rootKey: (generation) => {
+			const entry = JSON.stringify([
+				generation.owner,
+				generation.keyId,
+				Buffer.from(generation.wrapped).toString("base64")
+			]);
+			const hit = cached.get(entry);
+			if (hit !== void 0 && clock.now() < hit.expiresAt) return (0, unthrown.OkAsync)(hit.root);
+			cached.delete(entry);
+			return inFlight.get(entry) ?? unwrap(entry, generation);
+		},
+		provision: (owner, keyId) => through("provision", owner, keyId, () => request("provision", {
+			owner,
+			keyId
+		}, () => client.send(new _aws_sdk_client_kms.GenerateDataKeyWithoutPlaintextCommand({
+			KeyId: aliasOf(owner),
+			KeySpec: "AES_256",
+			EncryptionContext: {
+				owner,
+				keyId
+			}
+		}))).map(({ CiphertextBlob }) => ({
+			owner,
+			keyId,
+			wrapped: CiphertextBlob
+		}))),
+		erase: (owner) => {
+			const erasing = (cause) => GONE.has(nameOf(cause)) ? "gone" : new require_keys.KeysUnavailable({
+				operation: "erase",
+				owner,
+				cause
+			});
+			return through("erase", owner, void 0, () => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_kms.DescribeKeyCommand({ KeyId: aliasOf(owner) })), erasing).flatMap(({ KeyMetadata }) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_kms.ScheduleKeyDeletionCommand({
+				KeyId: KeyMetadata.KeyId,
+				PendingWindowInDays: config.pendingWindowDays
+			})), erasing)).map(() => void 0).flatMapErrCases((matcher) => matcher.with("gone", () => (0, unthrown.Ok)(void 0)).with(unthrown.P.tag("KeysUnavailable"), (unavailable) => (0, unthrown.Err)(unavailable)))).tap(() => {
+				for (const [key, kept] of cached) if (kept.owner === owner) cached.delete(key);
+			});
+		}
+	};
+};
+/**
+* **An erased generation settles `ok` with `result: "erased"`, not `error`.**
+* Asking for a key that was erased is the answer erasure exists to give, so
+* it is counted rather than written as a fault line; `KeysUnavailable` is
+* what pages somebody.
+*/
+const settled = (failure) => failure.tag === "Err" && failure.error._tag === "KeyErased" ? {
+	outcome: "ok",
+	attributes: {
+		result: "erased",
+		reason: failure.error.reason
+	}
+} : {
+	outcome: "error",
+	attributes: { result: "error" },
+	cause: failure.tag === "Err" ? failure.error : failure.cause
+};
+//#endregion
+exports.kmsKeys = kmsKeys;

package/dist/kms.d.cts

@@ -0,0 +1,60 @@
+import { t as EnvelopeKeys } from "./keys-DpvmIcWy.cjs";
+import { ConfigInvalid, EnvReading } from "@btravstack/config";
+import { Clock } from "@btravstack/core";
+import { Module, Scope } from "@btravstack/di";
+//#region src/kms.d.ts
+/** What {@link kmsKeys} is handed. Each value option pins the variable named beside it. */
+export type KmsKeysOptions = {
+  /**
+   * Pins `KEYS_KMS_ENDPOINT` (default: AWS's own endpoint for the region): a
+   * KMS-compatible emulator, or a VPC endpoint.
+   */
+  readonly endpoint?: string;
+  /**
+   * Pins `KEYS_CACHE_TTL_MS` (default `300000`, five minutes): how long an
+   * unwrapped root key is kept. It bounds two things at once: the KMS
+   * requests, one per generation per process per TTL, and how long a process
+   * that did not erase an owner keeps serving that owner's keys after it was
+   * erased. `0` keeps nothing.
+   */
+  readonly cacheTtlMs?: number;
+  /**
+   * Pins `KEYS_KMS_PENDING_WINDOW_DAYS` (default `30`, AWS's own, between 7
+   * and 30): the days a scheduled deletion can still be cancelled. Every
+   * generation answers `KeyErased` from the moment it is scheduled.
+   */
+  readonly pendingWindowDays?: number;
+  /** What the cache's TTL is measured against (default: the kernel's `systemClock`). */
+  readonly clock?: Clock;
+};
+/** The variables {@link kmsKeys} reads: two required, the rest defaulted or pinnable. */
+export type KmsKeysEnv = EnvReading<"KEYS_KMS_REGION" | "KEYS_KMS_ALIAS_PREFIX", "KEYS_KMS_ENDPOINT" | "KEYS_CACHE_TTL_MS" | "KEYS_KMS_PENDING_WINDOW_DAYS">;
+/**
+ * `EnvelopeKeys` over AWS KMS, with one KMS key per owner, named by the alias
+ * `<KEYS_KMS_ALIAS_PREFIX><owner>`.
+ *
+ * ```ts
+ * Module("Documents")({ imports: [kmsKeys()], provides: [sealer] });
+ * ```
+ *
+ * - **Configured from `KEYS_KMS_REGION` and `KEYS_KMS_ALIAS_PREFIX`** (an
+ *   alias prefix, `alias/tenant-` say), and the pinnable variables of
+ *   {@link KmsKeysOptions}. Credentials are the AWS SDK's default chain: a
+ *   workload identity, an instance profile, or `AWS_*` variables.
+ * - **A generation is a KMS data key**: `provision` asks
+ *   `GenerateDataKeyWithoutPlaintext` for an AES-256 key under the owner's
+ *   KMS key, and `rootKey` unwraps it with `Decrypt`, both with the encryption
+ *   context `{ owner, keyId }` and the owner's alias as the key, so a blob
+ *   handed in for another owner or key id is refused rather than unwrapped.
+ * - **Erasure is one key deletion**: `erase` resolves the owner's alias and
+ *   schedules its key's deletion, after which KMS refuses every generation of
+ *   the owner. This process forgets the keys it kept at once; another
+ *   process keeps serving its own until they expire, which is what
+ *   `KEYS_CACHE_TTL_MS` bounds.
+ * - **Refusals are answers**: a disabled, deleted, missing or refusing key is
+ *   `KeyErased`; anything else KMS says is `KeysUnavailable`, never cached.
+ * - **Every KMS request is reported to `Observers`** (`component: "keys"`); a
+ *   key served from memory reports nothing.
+ */
+export declare const kmsKeys: (options?: KmsKeysOptions) => Module<EnvelopeKeys, ConfigInvalid, KmsKeysEnv | Scope>;
+//#endregion

package/dist/kms.d.mts

@@ -0,0 +1,60 @@
+import { t as EnvelopeKeys } from "./keys-DpvmIcWy.mjs";
+import { Module, Scope } from "@btravstack/di";
+import { ConfigInvalid, EnvReading } from "@btravstack/config";
+import { Clock } from "@btravstack/core";
+//#region src/kms.d.ts
+/** What {@link kmsKeys} is handed. Each value option pins the variable named beside it. */
+export type KmsKeysOptions = {
+  /**
+   * Pins `KEYS_KMS_ENDPOINT` (default: AWS's own endpoint for the region): a
+   * KMS-compatible emulator, or a VPC endpoint.
+   */
+  readonly endpoint?: string;
+  /**
+   * Pins `KEYS_CACHE_TTL_MS` (default `300000`, five minutes): how long an
+   * unwrapped root key is kept. It bounds two things at once: the KMS
+   * requests, one per generation per process per TTL, and how long a process
+   * that did not erase an owner keeps serving that owner's keys after it was
+   * erased. `0` keeps nothing.
+   */
+  readonly cacheTtlMs?: number;
+  /**
+   * Pins `KEYS_KMS_PENDING_WINDOW_DAYS` (default `30`, AWS's own, between 7
+   * and 30): the days a scheduled deletion can still be cancelled. Every
+   * generation answers `KeyErased` from the moment it is scheduled.
+   */
+  readonly pendingWindowDays?: number;
+  /** What the cache's TTL is measured against (default: the kernel's `systemClock`). */
+  readonly clock?: Clock;
+};
+/** The variables {@link kmsKeys} reads: two required, the rest defaulted or pinnable. */
+export type KmsKeysEnv = EnvReading<"KEYS_KMS_REGION" | "KEYS_KMS_ALIAS_PREFIX", "KEYS_KMS_ENDPOINT" | "KEYS_CACHE_TTL_MS" | "KEYS_KMS_PENDING_WINDOW_DAYS">;
+/**
+ * `EnvelopeKeys` over AWS KMS, with one KMS key per owner, named by the alias
+ * `<KEYS_KMS_ALIAS_PREFIX><owner>`.
+ *
+ * ```ts
+ * Module("Documents")({ imports: [kmsKeys()], provides: [sealer] });
+ * ```
+ *
+ * - **Configured from `KEYS_KMS_REGION` and `KEYS_KMS_ALIAS_PREFIX`** (an
+ *   alias prefix, `alias/tenant-` say), and the pinnable variables of
+ *   {@link KmsKeysOptions}. Credentials are the AWS SDK's default chain: a
+ *   workload identity, an instance profile, or `AWS_*` variables.
+ * - **A generation is a KMS data key**: `provision` asks
+ *   `GenerateDataKeyWithoutPlaintext` for an AES-256 key under the owner's
+ *   KMS key, and `rootKey` unwraps it with `Decrypt`, both with the encryption
+ *   context `{ owner, keyId }` and the owner's alias as the key, so a blob
+ *   handed in for another owner or key id is refused rather than unwrapped.
+ * - **Erasure is one key deletion**: `erase` resolves the owner's alias and
+ *   schedules its key's deletion, after which KMS refuses every generation of
+ *   the owner. This process forgets the keys it kept at once; another
+ *   process keeps serving its own until they expire, which is what
+ *   `KEYS_CACHE_TTL_MS` bounds.
+ * - **Refusals are answers**: a disabled, deleted, missing or refusing key is
+ *   `KeyErased`; anything else KMS says is `KeysUnavailable`, never cached.
+ * - **Every KMS request is reported to `Observers`** (`component: "keys"`); a
+ *   key served from memory reports nothing.
+ */
+export declare const kmsKeys: (options?: KmsKeysOptions) => Module<EnvelopeKeys, ConfigInvalid, KmsKeysEnv | Scope>;
+//#endregion

package/dist/kms.mjs

@@ -0,0 +1,210 @@
+import { n as KeyErased, r as KeysUnavailable, t as EnvelopeKeys } from "./keys-CGbVjuu3.mjs";
+import { Err, Ok, OkAsync, P, fromPromise, fromSafePromise } from "unthrown";
+import { Module, Port, Provider } from "@btravstack/di";
+import { DecryptCommand, DescribeKeyCommand, GenerateDataKeyWithoutPlaintextCommand, KMSClient, ScheduleKeyDeletionCommand } from "@aws-sdk/client-kms";
+import { Config, Env } from "@btravstack/config";
+import { Observers, noObserverMember, observed, systemClock } from "@btravstack/core";
+//#region src/kms.ts
+/** What the graph bound from the environment for the KMS adapter. */
+var KeysConfig = class extends Port("KeysConfig") {};
+/** The client, as a port of its own, so the scope closing destroys it. */
+var KmsConnection = class extends Port("KmsConnection") {};
+const optionalUrl = (variable) => {
+	const url = Config.url(variable);
+	return {
+		variable,
+		parse: (raw) => raw === void 0 ? Ok(void 0) : url.parse(raw),
+		check: (value) => url.parse(String(value))
+	};
+};
+/**
+* `EnvelopeKeys` over AWS KMS, with one KMS key per owner, named by the alias
+* `<KEYS_KMS_ALIAS_PREFIX><owner>`.
+*
+* ```ts
+* Module("Documents")({ imports: [kmsKeys()], provides: [sealer] });
+* ```
+*
+* - **Configured from `KEYS_KMS_REGION` and `KEYS_KMS_ALIAS_PREFIX`** (an
+*   alias prefix, `alias/tenant-` say), and the pinnable variables of
+*   {@link KmsKeysOptions}. Credentials are the AWS SDK's default chain: a
+*   workload identity, an instance profile, or `AWS_*` variables.
+* - **A generation is a KMS data key**: `provision` asks
+*   `GenerateDataKeyWithoutPlaintext` for an AES-256 key under the owner's
+*   KMS key, and `rootKey` unwraps it with `Decrypt`, both with the encryption
+*   context `{ owner, keyId }` and the owner's alias as the key, so a blob
+*   handed in for another owner or key id is refused rather than unwrapped.
+* - **Erasure is one key deletion**: `erase` resolves the owner's alias and
+*   schedules its key's deletion, after which KMS refuses every generation of
+*   the owner. This process forgets the keys it kept at once; another
+*   process keeps serving its own until they expire, which is what
+*   `KEYS_CACHE_TTL_MS` bounds.
+* - **Refusals are answers**: a disabled, deleted, missing or refusing key is
+*   `KeyErased`; anything else KMS says is `KeysUnavailable`, never cached.
+* - **Every KMS request is reported to `Observers`** (`component: "keys"`); a
+*   key served from memory reports nothing.
+*/
+const kmsKeys = (options = {}) => Module("KmsKeys")({
+	needs: [Env],
+	provides: [
+		noObserverMember,
+		Config.provider(KeysConfig)(Config.object({
+			region: Config.string("KEYS_KMS_REGION"),
+			aliasPrefix: Config.string("KEYS_KMS_ALIAS_PREFIX"),
+			endpoint: Config.pinned(options.endpoint, optionalUrl("KEYS_KMS_ENDPOINT")),
+			cacheTtlMs: Config.pinned(options.cacheTtlMs, Config.integer("KEYS_CACHE_TTL_MS", {
+				default: 3e5,
+				min: 0
+			})),
+			pendingWindowDays: Config.pinned(options.pendingWindowDays, Config.integer("KEYS_KMS_PENDING_WINDOW_DAYS", {
+				default: 30,
+				min: 7,
+				max: 30
+			}))
+		})),
+		Provider(KmsConnection)({
+			inject: { config: KeysConfig },
+			acquire: ({ config }) => Ok(new KMSClient({
+				region: config.region,
+				...config.endpoint === void 0 ? {} : { endpoint: config.endpoint }
+			})),
+			release: (client) => client.destroy()
+		}),
+		Provider(EnvelopeKeys)({
+			inject: {
+				config: KeysConfig,
+				client: KmsConnection,
+				observers: Observers
+			},
+			sync: ({ config, client, observers }) => kmsEnvelopeKeys(client, config, observers, options.clock ?? systemClock)
+		})
+	],
+	exports: [EnvelopeKeys]
+});
+/** The KMS errors that mean the generation will never be unwrapped again, and the reason each one gives. */
+const ERASED = /* @__PURE__ */ new Map([
+	["DisabledException", "disabled"],
+	["KMSInvalidStateException", "pending_deletion"],
+	["NotFoundException", "not_found"],
+	["InvalidCiphertextException", "refused"],
+	["IncorrectKeyException", "refused"]
+]);
+const GONE = /* @__PURE__ */ new Set(["NotFoundException", "KMSInvalidStateException"]);
+const nameOf = (cause) => Object(cause).name;
+const kmsEnvelopeKeys = (client, config, observers, clock) => {
+	const cached = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	const aliasOf = (owner) => `${config.aliasPrefix}${owner}`;
+	const through = (name, owner, keyId, call) => observed(observers, {
+		component: "keys",
+		name,
+		attributes: { operation: name },
+		details: {
+			"btravstack.keys.owner": owner,
+			...keyId === void 0 ? {} : { "btravstack.keys.key_id": keyId }
+		}
+	}, call, {
+		ok: () => ({
+			outcome: "ok",
+			attributes: { result: "ok" }
+		}),
+		failure: settled
+	});
+	const request = (operation, generation, send) => fromPromise(send(), (cause) => {
+		const reason = ERASED.get(nameOf(cause));
+		return reason === void 0 ? new KeysUnavailable({
+			operation,
+			owner: generation.owner,
+			cause
+		}) : new KeyErased({
+			owner: generation.owner,
+			keyId: generation.keyId,
+			reason
+		});
+	});
+	const unwrap = (entry, generation) => {
+		const { owner, keyId } = generation;
+		const unwrapping = through("unwrap", owner, keyId, () => request("unwrap", generation, () => client.send(new DecryptCommand({
+			CiphertextBlob: generation.wrapped,
+			KeyId: aliasOf(owner),
+			EncryptionContext: {
+				owner,
+				keyId
+			}
+		}))).flatMap(({ Plaintext }) => {
+			const plaintext = Plaintext;
+			return fromSafePromise(crypto.subtle.importKey("raw", plaintext, "HKDF", false, ["deriveKey", "deriveBits"]).finally(() => plaintext.fill(0)));
+		})).tap((root) => {
+			inFlight.delete(entry);
+			const now = clock.now();
+			for (const [key, kept] of cached) if (kept.expiresAt <= now) cached.delete(key);
+			cached.set(entry, {
+				owner,
+				root,
+				expiresAt: now + config.cacheTtlMs
+			});
+		}).tapFailure(() => inFlight.delete(entry));
+		inFlight.set(entry, unwrapping);
+		return unwrapping;
+	};
+	return {
+		rootKey: (generation) => {
+			const entry = JSON.stringify([
+				generation.owner,
+				generation.keyId,
+				Buffer.from(generation.wrapped).toString("base64")
+			]);
+			const hit = cached.get(entry);
+			if (hit !== void 0 && clock.now() < hit.expiresAt) return OkAsync(hit.root);
+			cached.delete(entry);
+			return inFlight.get(entry) ?? unwrap(entry, generation);
+		},
+		provision: (owner, keyId) => through("provision", owner, keyId, () => request("provision", {
+			owner,
+			keyId
+		}, () => client.send(new GenerateDataKeyWithoutPlaintextCommand({
+			KeyId: aliasOf(owner),
+			KeySpec: "AES_256",
+			EncryptionContext: {
+				owner,
+				keyId
+			}
+		}))).map(({ CiphertextBlob }) => ({
+			owner,
+			keyId,
+			wrapped: CiphertextBlob
+		}))),
+		erase: (owner) => {
+			const erasing = (cause) => GONE.has(nameOf(cause)) ? "gone" : new KeysUnavailable({
+				operation: "erase",
+				owner,
+				cause
+			});
+			return through("erase", owner, void 0, () => fromPromise(client.send(new DescribeKeyCommand({ KeyId: aliasOf(owner) })), erasing).flatMap(({ KeyMetadata }) => fromPromise(client.send(new ScheduleKeyDeletionCommand({
+				KeyId: KeyMetadata.KeyId,
+				PendingWindowInDays: config.pendingWindowDays
+			})), erasing)).map(() => void 0).flatMapErrCases((matcher) => matcher.with("gone", () => Ok(void 0)).with(P.tag("KeysUnavailable"), (unavailable) => Err(unavailable)))).tap(() => {
+				for (const [key, kept] of cached) if (kept.owner === owner) cached.delete(key);
+			});
+		}
+	};
+};
+/**
+* **An erased generation settles `ok` with `result: "erased"`, not `error`.**
+* Asking for a key that was erased is the answer erasure exists to give, so
+* it is counted rather than written as a fault line; `KeysUnavailable` is
+* what pages somebody.
+*/
+const settled = (failure) => failure.tag === "Err" && failure.error._tag === "KeyErased" ? {
+	outcome: "ok",
+	attributes: {
+		result: "erased",
+		reason: failure.error.reason
+	}
+} : {
+	outcome: "error",
+	attributes: { result: "error" },
+	cause: failure.tag === "Err" ? failure.error : failure.cause
+};
+//#endregion
+export { kmsKeys };

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@btravstack/keys",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.45.0",
+  "description": "An EnvelopeKeys port for @btravstack/core: per-owner root keys wrapped by an AWS KMS key of that owner, unwrapped in memory and cached for a TTL, erased with one key deletion, and an HKDF helper giving each purpose its own key",
+  "keywords": [
+    "crypto-shredding",
+    "dependency-injection",
+    "envelope-encryption",
+    "hkdf",
+    "kms",
+    "typescript",
+    "unthrown"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/keys"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./kms": {
+      "import": {
+        "types": "./dist/kms.d.mts",
+        "default": "./dist/kms.mjs"
+      },
+      "require": {
+        "types": "./dist/kms.d.cts",
+        "default": "./dist/kms.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-kms": "3.1152.0",
+    "@btravstack/config": "0.45.0",
+    "@btravstack/core": "0.45.0",
+    "@btravstack/di": "0.45.0",
+    "@btravstack/internal-test-infra": "0.0.0",
+    "@btravstack/testing": "0.45.0",
+    "@btravstack/tsconfig": "0.4.0",
+    "@types/node": "26.6.5",
+    "@unthrown/vitest": "5.12.1",
+    "@vitest/coverage-v8": "5.0.3",
+    "tsdown": "0.23.1",
+    "typescript": "7.0.2",
+    "unthrown": "5.12.1",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-kms": "^3.1000.0",
+    "@btravstack/config": "^0.45.0",
+    "@btravstack/core": "^0.45.0",
+    "@btravstack/di": "^0.45.0",
+    "unthrown": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-kms": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/kms.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts src/kms.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
+  }
 }