@btravstack/keys

---

@btravstack/keys / kms

kms

Type Aliases

KmsKeysEnv

type KmsKeysEnv = EnvReading<"KEYS_KMS_REGION" | "KEYS_KMS_ALIAS_PREFIX", 
  | "KEYS_KMS_ENDPOINT"
  | "KEYS_CACHE_TTL_MS"
  | "KEYS_KMS_PENDING_WINDOW_DAYS">;

Defined in: packages/keys/src/kms.ts:98

The variables kmsKeys reads: two required, the rest defaulted or pinnable.

---

KmsKeysOptions

type KmsKeysOptions = object;

Defined in: packages/keys/src/kms.ts:73

What kmsKeys is handed. Each value option pins the variable named beside it.

Properties

Property	Modifier	Type	Description	Defined in
cacheTtlMs?	readonly	number	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.	packages/keys/src/kms.ts:86
clock?	readonly	Clock	What the cache's TTL is measured against (default: the kernel's systemClock).	packages/keys/src/kms.ts:94
endpoint?	readonly	string	Pins KEYS_KMS_ENDPOINT (default: AWS's own endpoint for the region): a KMS-compatible emulator, or a VPC endpoint.	packages/keys/src/kms.ts:78
pendingWindowDays?	readonly	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.	packages/keys/src/kms.ts:92

Functions

kmsKeys()

function kmsKeys(options?): Module<EnvelopeKeys, ConfigInvalid, KmsKeysEnv | Scope>;

Defined in: packages/keys/src/kms.ts:130

EnvelopeKeys over AWS KMS, with one KMS key per owner, named by the alias <KEYS_KMS_ALIAS_PREFIX><owner>.

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 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.

Parameters

Parameter	Type
options?	KmsKeysOptions

Returns

Module<EnvelopeKeys, ConfigInvalid, KmsKeysEnv | Scope>