GCP.KMS reference

CryptoKey

Source: src/GCP/KMS/CryptoKey.ts

A Cloud KMS CryptoKey — a named key that holds zero or more versions.

Purpose, location, parent KeyRing, import-only, backend, destroyScheduledDuration, and versionTemplate.protectionLevel are immutable (changing them replaces the key). Labels, rotation, and versionTemplate.algorithm update in place.

Cloud KMS only permanently deletes a CryptoKey after every version is gone, and a deleted CryptoKey’s name is retired forever — it can never be created again in the project.

Destroying a key therefore releases it instead of deleting it: every version is scheduled for destruction and the ownership labels are replaced by alchemy-released. A later deploy with the same cryptoKeyId — from this stack or any other — reclaims the released key and mints a fresh primary version. The default cryptoKeyId is deterministic per stack, stage, and logical id, so destroy/redeploy cycles reuse one key rather than leaving a new released key behind each time. Ciphertext encrypted under the old versions is not recoverable.

CryptoKey: Creating a CryptoKey

Generated name on an existing KeyRing

const ring = yield* GCP.KMS.KeyRing("Keys", {});
const key = yield* GCP.KMS.CryptoKey("Data", {
  keyRing: ring.name,
});

Explicit id, labels, and no initial version

const key = yield* GCP.KMS.CryptoKey("Data", {
  keyRing: ring.name,
  cryptoKeyId: "app-data",
  labels: { env: "prod" },
  skipInitialVersionCreation: true,
});

CryptoKey: Encrypting and Decrypting

const encrypt = yield* GCP.KMS.Encrypt(key);
const decrypt = yield* GCP.KMS.Decrypt(key);
const { ciphertext } = yield* encrypt({
  body: { plaintext: btoa("hello") },
});
const { plaintext } = yield* decrypt({
  body: { ciphertext },
});

CryptoKeyVersion

Source: src/GCP/KMS/CryptoKeyVersion.ts

A Cloud KMS CryptoKeyVersion — one generation of key material under a CryptoKey.

Parent CryptoKey, KeyRing, location, and version id are identity (changing them replaces the version). state toggles between ENABLED and DISABLED in place. Cloud KMS assigns sequential version ids on create; versions have no labels, so list returns versions whose parent CryptoKey carries Alchemy ownership labels.

Destroy schedules destruction (DESTROY_SCHEDULED, minimum 24h). Permanent delete is only possible for DESTROYED, IMPORT_FAILED, or GENERATION_FAILED versions that were never successfully imported.

CryptoKeyVersion: Creating a CryptoKeyVersion

Next version on an existing CryptoKey

const ring = yield* GCP.KMS.KeyRing("Keys", {});
const key = yield* GCP.KMS.CryptoKey("Data", {
  keyRing: ring.name,
  skipInitialVersionCreation: true,
});
const version = yield* GCP.KMS.CryptoKeyVersion("V1", {
  cryptoKey: key.name,
});

Disabled version

const version = yield* GCP.KMS.CryptoKeyVersion("V1", {
  cryptoKey: key.name,
  state: "DISABLED",
});

Decrypt

Source: src/GCP/KMS/Decrypt.ts

Runtime binding for Cloud KMS cryptoKeys.decrypt.

Bind this operation to a CryptoKey in a Function/Action init phase. Provide DecryptHttp. The CryptoKey purpose must be ENCRYPT_DECRYPT.

Decrypt: Decrypting Data

const decrypt = yield* GCP.KMS.Decrypt(key);
const { plaintext } = yield* decrypt({
  body: { ciphertext },
});

DecryptHttp

Source: src/GCP/KMS/DecryptHttp.ts Kind: Layer · Provides: GCP.KMS.Decrypt

HTTP implementation of Decrypt.

Encrypt

Source: src/GCP/KMS/Encrypt.ts

Runtime binding for Cloud KMS cryptoKeys.encrypt.

Bind this operation to a CryptoKey in a Function/Action init phase. Provide EncryptHttp. The CryptoKey purpose must be ENCRYPT_DECRYPT and it must have an enabled primary version.

Encrypt: Encrypting Data

const encrypt = yield* GCP.KMS.Encrypt(key);
const { ciphertext } = yield* encrypt({
  body: { plaintext: btoa("hello") },
});

EncryptHttp

Source: src/GCP/KMS/EncryptHttp.ts Kind: Layer · Provides: GCP.KMS.Encrypt

HTTP implementation of Encrypt.

ImportJob

Source: src/GCP/KMS/ImportJob.ts

A Cloud KMS ImportJob — a wrapping-key job used to import pre-existing key material into a CryptoKeyVersion.

Parent KeyRing, location, and id are identity (changing them replaces the job). importMethod, protectionLevel, and cryptoKeyBackend are immutable create-only fields. Cloud KMS has no ImportJob delete or update API; destroy removes the resource from state only. Jobs expire about 3 days after create and remain as EXPIRED residue until Google garbage-collects them. Account-wide nuke skips this type for the same reason. ImportJobs have no labels, so list returns every job under listed KeyRings.

ImportJob: Creating an ImportJob

Generated name on an existing KeyRing

const ring = yield* GCP.KMS.KeyRing("Keys", {});
const job = yield* GCP.KMS.ImportJob("Wrap", {
  keyRing: ring.name,
});

Explicit id, method, and protection level

const job = yield* GCP.KMS.ImportJob("Wrap", {
  keyRing: ring.name,
  importJobId: "wrap-keys",
  importMethod: "RSA_OAEP_4096_SHA256_AES_256",
  protectionLevel: "HSM",
});

KeyRing

Source: src/GCP/KMS/KeyRing.ts

A Cloud KMS KeyRing — a location-scoped container for CryptoKeys.

Key rings have no labels and no update API. Name and location are identity; Cloud KMS also has no delete API, so destroy removes the resource from state only. Account-wide nuke skips this type for the same reason.

Because the ring outlives destroy, the default keyRingId is deterministic per stack, stage, and logical id: deploying again after a destroy adopts the ring left behind rather than creating another one.

KeyRing: Creating a KeyRing

Generated name

const keys = yield* GCP.KMS.KeyRing("Keys", {});

Explicit id and location

const keys = yield* GCP.KMS.KeyRing("Keys", {
  keyRingId: "app-keys",
  location: "us-central1",
});

SingleTenantHsmInstanceProposal

Source: src/GCP/KMS/SingleTenantHsmInstanceProposal.ts

A Cloud KMS SingleTenantHsmInstanceProposal — a quorum-gated operation on a single-tenant HSM instance (refresh, enable, disable, delete, register 2FA keys, add/remove quorum members).

Parent instance, location, id, TTL, and the chosen operation are identity (changing them replaces the proposal). Cloud KMS has no update API. Proposals have no labels, so list returns every proposal under listed instances. Single-tenant HSM is entitlement-gated.

SingleTenantHsmInstanceProposal: Creating a Proposal

Refresh an instance

const proposal = yield* GCP.KMS.SingleTenantHsmInstanceProposal(
  "Refresh",
  {
    singleTenantHsmInstance: instanceName,
    refreshSingleTenantHsmInstance: true,
  },
);

Register 2FA keys

const proposal = yield* GCP.KMS.SingleTenantHsmInstanceProposal(
  "Register",
  {
    singleTenantHsmInstance: instanceName,
    registerTwoFactorAuthKeys: {
      twoFactorPublicKeyPems: [pemA, pemB, pemC],
      requiredApproverCount: 2,
    },
  },
);