TypeScript: @dnsid-ai/key-aws
AWS KMS-backed DNSid KeyProvider.
Private keys stay in AWS KMS. This package fetches public keys, exposes them as DNSid JWKs, signs through KMS, and manages active/pending/retained key state.
Install
Section titled “Install”npm install @dnsid-ai/key-aws @dnsid-ai/protocol @aws-sdk/client-kmsimport { KMSClient } from '@aws-sdk/client-kms';import { AwsKmsKeyProvider, AwsSdkKmsFacade } from '@dnsid-ai/key-aws';
const state = { activeKeyId: 'alias/dnsid-current', retainedKeyIds: [], pendingKeyIds: [],};
const provider = await AwsKmsKeyProvider.load( new AwsSdkKmsFacade(new KMSClient({ region: 'us-east-1' })), { state, algorithm: 'ECDSA_SHA_256', keySpec: 'ECC_NIST_P256', },);
const signature = await provider.sign(new TextEncoder().encode('payload'));const jwk = await provider.signingKey();Persist provider.stateSnapshot() after generateKey(), activate(), or supersede(). The package mutates the supplied state object, but persistence is the caller’s job.
Supported KMS keys
Section titled “Supported KMS keys”| DNSid/JWS alg | AWS signing algorithm | AWS key spec |
|---|---|---|
ES256 | ECDSA_SHA_256 | ECC_NIST_P256 |
EdDSA | ED25519_SHA_512 | ECC_NIST_EDWARDS25519 |
Loaded keys must have:
KeyUsage: SIGN_VERIFY- matching
KeySpec SigningAlgorithmscontaining the configured algorithm
Aliases, alias ARNs, key IDs, and key ARNs are accepted. They are resolved to canonical KMS key IDs on load.
IAM permissions
Section titled “IAM permissions”Minimum runtime permissions:
kms:GetPublicKeykms:Sign
Rotation permissions, if used:
kms:CreateKeyforgenerateKey()kms:ScheduleKeyDeletionforsupersede()whenscheduleKeyDeletionOnPurgeis enabled
Rotation
Section titled “Rotation”const nextKid = await provider.generateKey();await provider.activate(nextKid);await provider.supersede('old-key-id');
await saveState(provider.stateSnapshot());Pending keys are not published by listKeyIds() or jwk(). Activating a pending key moves the previous active key to retained.
Large payloads
Section titled “Large payloads”AWS KMS RAW signing is limited to 4096 bytes. For ECDSA_SHA_256, larger payloads are SHA-256 hashed locally and signed with KMS DIGEST mode. ED25519_SHA_512 remains RAW-only.
LocalStack smoke test
Section titled “LocalStack smoke test”From the repo root:
DNSID_AWS_KMS_LOCALSTACK=1 npm run test:aws-kms:localstackAWS KMS-backed key provider for DNSid.
@dnsid-ai/key-aws implements the KeyProvider contract from
@dnsid-ai/protocol on top of AWS KMS: private key material never
leaves KMS, while AwsKmsKeyProvider exposes public keys as DNSid JWKs, signs
through KMS, and manages the active/pending/retained key lifecycle. Callers persist
stateSnapshot() after lifecycle changes. AwsSdkKmsFacade adapts AWS SDK v3’s
KMSClient to the narrow AwsKmsFacade interface this package depends on.
Classes
Section titled “Classes”AwsKmsKeyProvider
Section titled “AwsKmsKeyProvider”Defined in: index.ts:173
AWS KMS-backed DNSid KeyProvider.
AWS KMS owns private key material and signing. This provider owns DNSid’s active/pending/retained lifecycle state and exposes public keys as JWKs.
Implements
Section titled “Implements”Methods
Section titled “Methods”activate()
Section titled “activate()”activate(kid): Promise<void>;Defined in: index.ts:279
Promotes a pending key to active. The previously active key transitions to retained.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”generateKey()
Section titled “generateKey()”generateKey(): Promise<string>;Defined in: index.ts:263
Generates a new key pair in the pending state. Returns the new key’s kid.
Returns
Section titled “Returns”Promise<string>
Implementation of
Section titled “Implementation of”jwk(kid): Promise<DnsIdJWK>;Defined in: index.ts:213
Returns the JWK representation of a key by ID (active, pending, or retained). Raises if not found.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<DnsIdJWK>
Implementation of
Section titled “Implementation of”listKeyIds()
Section titled “listKeyIds()”listKeyIds(): Promise<string[]>;Defined in: index.ts:220
Returns the IDs of all active and retained keys (pending keys excluded). The active key ID MUST appear first; retained keys follow in any order.
Returns
Section titled “Returns”Promise<string[]>
Implementation of
Section titled “Implementation of”purge()
Section titled “purge()”purge(kid): Promise<void>;Defined in: index.ts:310
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Deprecated
Section titled “Deprecated”Use supersede().
Implementation of
Section titled “Implementation of”sign()
Section titled “sign()”sign(payload): Promise<Uint8Array<ArrayBufferLike>>;Defined in: index.ts:232
Signs the given payload with the current active signing key. Returns raw signature bytes.
Parameters
Section titled “Parameters”payload
Section titled “payload”Uint8Array
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
Implementation of
Section titled “Implementation of”signingKey()
Section titled “signingKey()”signingKey(): Promise<DnsIdJWK>;Defined in: index.ts:209
Returns the JWK representation of the current active public signing key. The returned kid MUST NOT contain ’#’.
Returns
Section titled “Returns”Promise<DnsIdJWK>
Implementation of
Section titled “Implementation of”signKey()
Section titled “signKey()”signKey(kid, payload): Promise<Uint8Array<ArrayBufferLike>>;Defined in: index.ts:236
Signs with a specified active or pending key.
Parameters
Section titled “Parameters”string
payload
Section titled “payload”Uint8Array
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
Implementation of
Section titled “Implementation of”stateSnapshot()
Section titled “stateSnapshot()”stateSnapshot(): AwsKmsKeyState;Defined in: index.ts:224
Returns
Section titled “Returns”supersede()
Section titled “supersede()”supersede(kid): Promise<void>;Defined in: index.ts:288
Supersedes and removes a retained key from this provider’s published key set.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”load()
Section titled “load()”static load(client, config): Promise<AwsKmsKeyProvider>;Defined in: index.ts:197
Parameters
Section titled “Parameters”client
Section titled “client”config
Section titled “config”Returns
Section titled “Returns”Promise<AwsKmsKeyProvider>
AwsSdkKmsFacade
Section titled “AwsSdkKmsFacade”Defined in: index.ts:107
Adapter from AWS SDK v3’s KMSClient to the narrow facade used by AwsKmsKeyProvider.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AwsSdkKmsFacade(client): AwsSdkKmsFacade;Defined in: index.ts:108
Parameters
Section titled “Parameters”client
Section titled “client”Returns
Section titled “Returns”Methods
Section titled “Methods”createSigningKey()
Section titled “createSigningKey()”createSigningKey(input): Promise<{ keyId: string;}>;Defined in: index.ts:110
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<{
keyId: string;
}>
Implementation of
Section titled “Implementation of”getPublicKey()
Section titled “getPublicKey()”getPublicKey(input): Promise<{ keyId?: string; keySpec?: string; keyUsage?: string; publicKey: Uint8Array; signingAlgorithms?: string[];}>;Defined in: index.ts:122
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<{
keyId?: string;
keySpec?: string;
keyUsage?: string;
publicKey: Uint8Array;
signingAlgorithms?: string[];
}>
Implementation of
Section titled “Implementation of”scheduleKeyDeletion()
Section titled “scheduleKeyDeletion()”scheduleKeyDeletion(input): Promise<void>;Defined in: index.ts:159
Parameters
Section titled “Parameters”AwsKmsScheduleKeyDeletionInput
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”AwsKmsFacade.scheduleKeyDeletion
sign()
Section titled “sign()”sign(input): Promise<{ keyId?: string; signature: Uint8Array; signingAlgorithm?: string;}>;Defined in: index.ts:140
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<{
keyId?: string;
signature: Uint8Array;
signingAlgorithm?: string;
}>
Implementation of
Section titled “Implementation of”Interfaces
Section titled “Interfaces”AwsKmsConfig
Section titled “AwsKmsConfig”Defined in: index.ts:39
Extends
Section titled “Extends”Partial<AwsKmsKeyState>
Properties
Section titled “Properties”activeKeyArn?
Section titled “activeKeyArn?”optional activeKeyArn?: string;Defined in: index.ts:46
Legacy alias for activeKeyId kept for existing callers.
activeKeyId?
Section titled “activeKeyId?”optional activeKeyId?: string;Defined in: index.ts:32
ARN, key ID, alias, or alias ARN of the currently active signing key. Aliases are resolved to canonical key IDs on load.
Inherited from
Section titled “Inherited from”algorithm
Section titled “algorithm”algorithm: AwsKmsSigningAlgorithm;Defined in: index.ts:52
KMS signing algorithm to request. Must match the key spec.
deletionWindowInDays?
Section titled “deletionWindowInDays?”optional deletionWindowInDays?: number;Defined in: index.ts:62
Waiting period for ScheduleKeyDeletion. AWS allows 7-30 days. Default: 30.
description?
Section titled “description?”optional description?: string;Defined in: index.ts:56
Optional description passed to generated KMS keys.
keySpec?
Section titled “keySpec?”optional keySpec?: AwsKmsKeySpec;Defined in: index.ts:54
KMS key spec to use when generateKey creates a new key.
pendingKeyArns?
Section titled “pendingKeyArns?”optional pendingKeyArns?: string[];Defined in: index.ts:50
Legacy alias for pendingKeyIds kept for existing callers.
pendingKeyIds?
Section titled “pendingKeyIds?”optional pendingKeyIds?: string[];Defined in: index.ts:36
KMS key IDs generated but not yet active.
Inherited from
Section titled “Inherited from”retainedKeyArns?
Section titled “retainedKeyArns?”optional retainedKeyArns?: string[];Defined in: index.ts:48
Legacy alias for retainedKeyIds kept for existing callers.
retainedKeyIds?
Section titled “retainedKeyIds?”optional retainedKeyIds?: string[];Defined in: index.ts:34
KMS key IDs retained for verification of previous signatures.
Inherited from
Section titled “Inherited from”scheduleKeyDeletionOnPurge?
Section titled “scheduleKeyDeletionOnPurge?”optional scheduleKeyDeletionOnPurge?: boolean;Defined in: index.ts:60
Schedule deletion of retained KMS keys on purge. Default: false.
state?
Section titled “state?”optional state?: AwsKmsKeyState;Defined in: index.ts:44
Mutable state object for provider lifecycle. Prefer this over the legacy top-level active/retained/pending fields when state must persist.
optional tags?: Record<string, string>;Defined in: index.ts:58
Optional tags passed to generated KMS keys.
AwsKmsCreateSigningKeyInput
Section titled “AwsKmsCreateSigningKeyInput”Defined in: index.ts:65
Properties
Section titled “Properties”description?
Section titled “description?”optional description?: string;Defined in: index.ts:67
keySpec
Section titled “keySpec”keySpec: AwsKmsKeySpec;Defined in: index.ts:66
optional tags?: Record<string, string>;Defined in: index.ts:68
AwsKmsFacade
Section titled “AwsKmsFacade”Defined in: index.ts:87
Methods
Section titled “Methods”createSigningKey()
Section titled “createSigningKey()”createSigningKey(input): Promise<{ keyId: string;}>;Defined in: index.ts:88
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<{
keyId: string;
}>
getPublicKey()
Section titled “getPublicKey()”getPublicKey(input): Promise<{ keyId?: string; keySpec?: string; keyUsage?: string; publicKey: Uint8Array; signingAlgorithms?: string[];}>;Defined in: index.ts:89
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<{
keyId?: string;
keySpec?: string;
keyUsage?: string;
publicKey: Uint8Array;
signingAlgorithms?: string[];
}>
scheduleKeyDeletion()?
Section titled “scheduleKeyDeletion()?”optional scheduleKeyDeletion(input): Promise<void>;Defined in: index.ts:101
Parameters
Section titled “Parameters”AwsKmsScheduleKeyDeletionInput
Returns
Section titled “Returns”Promise<void>
sign()
Section titled “sign()”sign(input): Promise<{ keyId?: string; signature: Uint8Array; signingAlgorithm?: string;}>;Defined in: index.ts:96
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<{
keyId?: string;
signature: Uint8Array;
signingAlgorithm?: string;
}>
AwsKmsGetPublicKeyInput
Section titled “AwsKmsGetPublicKeyInput”Defined in: index.ts:71
Properties
Section titled “Properties”keyId: string;Defined in: index.ts:72
AwsKmsKeyState
Section titled “AwsKmsKeyState”Defined in: index.ts:30
Properties
Section titled “Properties”activeKeyId
Section titled “activeKeyId”activeKeyId: string;Defined in: index.ts:32
ARN, key ID, alias, or alias ARN of the currently active signing key. Aliases are resolved to canonical key IDs on load.
pendingKeyIds?
Section titled “pendingKeyIds?”optional pendingKeyIds?: string[];Defined in: index.ts:36
KMS key IDs generated but not yet active.
retainedKeyIds?
Section titled “retainedKeyIds?”optional retainedKeyIds?: string[];Defined in: index.ts:34
KMS key IDs retained for verification of previous signatures.
AwsKmsScheduleKeyDeletionInput
Section titled “AwsKmsScheduleKeyDeletionInput”Defined in: index.ts:82
Properties
Section titled “Properties”keyId: string;Defined in: index.ts:83
pendingWindowInDays
Section titled “pendingWindowInDays”pendingWindowInDays: number;Defined in: index.ts:84
AwsKmsSignInput
Section titled “AwsKmsSignInput”Defined in: index.ts:75
Properties
Section titled “Properties”keyId: string;Defined in: index.ts:76
message
Section titled “message”message: Uint8Array;Defined in: index.ts:77
messageType
Section titled “messageType”messageType: "RAW" | "DIGEST";Defined in: index.ts:79
signingAlgorithm
Section titled “signingAlgorithm”signingAlgorithm: AwsKmsSigningAlgorithm;Defined in: index.ts:78
Type Aliases
Section titled “Type Aliases”AwsKmsKeySpec
Section titled “AwsKmsKeySpec”type AwsKmsKeySpec = "ECC_NIST_P256" | "ECC_NIST_EDWARDS25519";Defined in: index.ts:26
AwsKmsSigningAlgorithm
Section titled “AwsKmsSigningAlgorithm”type AwsKmsSigningAlgorithm = "ECDSA_SHA_256" | "ED25519_SHA_512";Defined in: index.ts:24
AwsSdkKmsClient
Section titled “AwsSdkKmsClient”type AwsSdkKmsClient = Pick<KMSClient, "send">;Defined in: index.ts:104