@dnsid-ai/key-gcp 0.0.0-stage → 0.36.0

package/dist/index.cjs

@@ -0,0 +1,277 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GcpCloudKmsKeyProvider: () => GcpCloudKmsKeyProvider
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_crypto = require("crypto");
+var import_protocol = require("@dnsid-ai/protocol");
+var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
+  constructor(client, version, publicKey) {
+    this.client = client;
+    this.version = version;
+    if (publicKey) {
+      this.activeKid = publicKey.kid;
+      this.keys.set(publicKey.kid, { version, jwk: publicKey, state: "active" });
+    }
+  }
+  client;
+  version;
+  keys = /* @__PURE__ */ new Map();
+  activeKid;
+  signing = /* @__PURE__ */ new Set();
+  activating = false;
+  /**
+   * Creates one version under an existing ASYMMETRIC_SIGN CryptoKey with a
+   * SOFTWARE EC_SIGN_ED25519 template, without opening any prior version.
+   * Returns a locally pending provider and immutable reference; activate(kid)
+   * explicitly before initial manager injection. Never provisions the parent,
+   * writes files, deletes keys, or closes the caller-owned client.
+   * Pending generation polls the same version at most 20 times, 250ms apart.
+   * Each transport call uses the caller's client timeout configuration.
+   * Failed/indeterminate creation may leave an operator-owned remote version;
+   * do not blindly retry. Normal load/configuration remains open-only.
+   */
+  static async create(client, config) {
+    if (config.algorithm !== "EC_SIGN_ED25519") throw new import_protocol.ArgumentError("Google Cloud KMS algorithm must be EC_SIGN_ED25519");
+    if (typeof config.parent !== "string" || !/^projects\/[A-Za-z0-9._:-]+\/locations\/[A-Za-z0-9_-]+\/keyRings\/[A-Za-z0-9_-]+\/cryptoKeys\/[A-Za-z0-9_-]+$/.test(config.parent)) {
+      throw new import_protocol.ArgumentError("Google Cloud KMS creation requires a CryptoKey parent");
+    }
+    if (!client.getCryptoKey || !client.createCryptoKeyVersion) throw new import_protocol.ArgumentError("Google Cloud KMS client does not support initial creation");
+    const [raw] = await client.getCryptoKey({ name: config.parent });
+    const parent = raw;
+    if (parent?.name !== config.parent || parent.purpose !== "ASYMMETRIC_SIGN" && parent.purpose !== 5 || !ed25519Software(parent.versionTemplate)) {
+      throw new import_protocol.ArgumentError("Google Cloud KMS requires a compatible signing parent/template");
+    }
+    const provider = new _GcpCloudKmsKeyProvider(client, config.parent);
+    const kid = await provider.generatePendingKey(void 0);
+    return { provider, kid, keyRef: provider.keys.get(kid).version };
+  }
+  /**
+   * Opens the selected active version and, optionally, an application-saved pending
+   * version for recovery. Both bindings are validated; the pending key supports
+   * JWK lookup and rotation proof signing but is not the active signer or live
+   * inventory. No discovery, generation, or activation occurs. Applications own
+   * durable references and recovery checks; activate performs the local transition.
+   */
+  static async load(client, config) {
+    const version = config.activeKeyVersion;
+    validateVersion(version);
+    const pendingVersion = config.pendingKeyVersion;
+    if (pendingVersion !== void 0) {
+      validateVersion(pendingVersion);
+      if (pendingVersion === version) throw new import_protocol.ArgumentError("Google Cloud KMS active and pending versions must differ");
+    }
+    if (config.algorithm !== "EC_SIGN_ED25519") throw new import_protocol.ArgumentError("Google Cloud KMS algorithm must be EC_SIGN_ED25519");
+    if (config.retainedKeyVersions?.length) throw new import_protocol.ArgumentError("Google Cloud KMS retained key loading is not supported");
+    if (!client) {
+      const { KeyManagementServiceClient } = await import("@google-cloud/kms");
+      client = new KeyManagementServiceClient();
+    }
+    const publicKey = await loadPublicKey(client, version);
+    const pendingKey = pendingVersion === void 0 ? void 0 : await loadPublicKey(client, pendingVersion);
+    if (pendingKey?.kid === publicKey.kid) throw new import_protocol.ArgumentError("Google Cloud KMS pending version has duplicate public key");
+    const provider = new _GcpCloudKmsKeyProvider(client, version, publicKey);
+    if (pendingKey) provider.keys.set(pendingKey.kid, { version: pendingVersion, jwk: pendingKey, state: "pending" });
+    return provider;
+  }
+  async signingKey() {
+    if (!this.activeKid) throw new import_protocol.ArgumentError("Google Cloud KMS has no active key");
+    return this.jwk(this.activeKid);
+  }
+  async jwk(kid) {
+    const key = this.keys.get(kid);
+    if (!key) throw new import_protocol.ArgumentError("Google Cloud KMS key not found");
+    return { ...key.jwk };
+  }
+  /**
+   * Returns only the current active key ID, or an empty list when no key is active.
+   * Pending and superseded keys are excluded from this live key list, even when
+   * their public JWKs remain available through `jwk` for historical verification.
+   */
+  async listKeyIds() {
+    return this.activeKid ? [this.activeKid] : [];
+  }
+  async sign(payload) {
+    if (!this.activeKid) throw new import_protocol.ArgumentError("Google Cloud KMS has no active key");
+    return this.signKey(this.activeKid, payload);
+  }
+  async signKey(kid, payload) {
+    if (this.activating) throw new import_protocol.ArgumentError("Google Cloud KMS activation is in progress");
+    const key = this.keys.get(kid);
+    if (!key || key.state === "superseded") throw new import_protocol.ArgumentError("Google Cloud KMS key is not active or pending");
+    const operation = this.signVersion(key.version, payload);
+    this.signing.add(operation);
+    try {
+      return await operation;
+    } finally {
+      this.signing.delete(operation);
+    }
+  }
+  async signVersion(version, payload) {
+    const data = new Uint8Array(payload);
+    const [raw] = await this.client.asymmetricSign({ name: version, data, dataCrc32c: { value: crc32c(data) } });
+    const response = raw;
+    if (response?.name !== version) throw new import_protocol.ArgumentError("Google Cloud KMS signature version mismatch");
+    if (response.verifiedDataCrc32c !== true) throw new import_protocol.ArgumentError("Google Cloud KMS did not verify data checksum");
+    const signature = typeof response.signature === "string" ? Buffer.from(response.signature, "base64") : response.signature;
+    if (!(signature instanceof Uint8Array) || signature.byteLength !== 64) throw new import_protocol.ArgumentError("Google Cloud KMS returned invalid Ed25519 signature");
+    if (!checksumMatches(signature, response.signatureCrc32c)) throw new import_protocol.ArgumentError("Google Cloud KMS signature checksum mismatch");
+    return new Uint8Array(signature);
+  }
+  async validateKeyGeneration(algorithm) {
+    if (algorithm !== "EdDSA") throw new import_protocol.ArgumentError(`Google Cloud KMS generation settings do not support ${algorithm}`);
+  }
+  /**
+   * Explicit operator generation only; defaults to EdDSA and rejects other algorithms before creation.
+   * Pending generation polls the exact created version at most 20 times, 250ms apart,
+   * using the caller's transport timeouts, just as initial creation does.
+   * Returns a locally pending key without changing the active signer. Failures after
+   * creation retain the version reference and cause, without retrying or deleting it.
+   * Service/integrity failures are not caller-argument errors. Never called by configuration opening.
+   */
+  async generateKey(algorithm) {
+    return this.generatePendingKey(algorithm);
+  }
+  async generatePendingKey(algorithm) {
+    await this.validateKeyGeneration(algorithm ?? "EdDSA");
+    if (!this.client.createCryptoKeyVersion) throw new import_protocol.ArgumentError("Google Cloud KMS client does not support version creation");
+    const parent = this.version.includes("/cryptoKeyVersions/") ? this.version.slice(0, this.version.lastIndexOf("/cryptoKeyVersions/")) : this.version;
+    const [raw] = await this.client.createCryptoKeyVersion({ parent, cryptoKeyVersion: { state: "ENABLED" } });
+    let created = raw;
+    const name = created?.name;
+    if (typeof name !== "string" || !name.startsWith(parent + "/cryptoKeyVersions/") || !/^[1-9][0-9]*$/.test(name.slice((parent + "/cryptoKeyVersions/").length))) {
+      throw new import_protocol.ArgumentError(`Google Cloud KMS created an unexpected key version${typeof name === "string" && name ? `: ${name}` : ""}`);
+    }
+    try {
+      for (let poll = 0; ; poll++) {
+        if (created?.name !== name || !ed25519Software(created)) throw new import_protocol.ArgumentError("Google Cloud KMS created an unexpected key version");
+        if (created.state === "ENABLED" || created.state === 1) break;
+        if (created.state !== "PENDING_GENERATION" && created.state !== 5 || poll >= 20 || !this.client.getCryptoKeyVersion) {
+          throw new import_protocol.ArgumentError("Google Cloud KMS version is not ready for signing");
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        const [metadata] = await this.client.getCryptoKeyVersion({ name });
+        created = metadata;
+      }
+      const pending = await _GcpCloudKmsKeyProvider.load(this.client, { activeKeyVersion: name, algorithm: "EC_SIGN_ED25519" });
+      const jwk = await pending.signingKey();
+      if (this.keys.has(jwk.kid)) throw new import_protocol.ArgumentError("Google Cloud KMS generated duplicate public key");
+      this.keys.set(jwk.kid, { version: name, jwk: Object.freeze(jwk), state: "pending" });
+      return jwk.kid;
+    } catch (cause) {
+      throw new Error(`Google Cloud KMS created version ${name}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+  }
+  async activate(kid) {
+    if (this.activating) throw new import_protocol.ArgumentError("Google Cloud KMS activation is already in progress");
+    const key = this.keys.get(kid);
+    if (!key || key.state !== "pending") throw new import_protocol.ArgumentError("Google Cloud KMS key is not pending");
+    this.activating = true;
+    try {
+      await Promise.allSettled(this.signing);
+      if (this.activeKid) this.keys.get(this.activeKid).state = "superseded";
+      key.state = "active";
+      this.activeKid = kid;
+    } finally {
+      this.activating = false;
+    }
+  }
+  /**
+   * Removes local signing eligibility from an active, pending, or already
+   * superseded key. Superseding the active key leaves no active signer and an
+   * empty live key list; superseding another key does not clear its successor.
+   * The public JWK remains available through `jwk` for historical verification.
+   * Never disables, destroys, or otherwise mutates the remote CryptoKeyVersion.
+   */
+  async supersede(kid) {
+    if (this.activating) throw new import_protocol.ArgumentError("Google Cloud KMS activation is in progress");
+    const key = this.keys.get(kid);
+    if (!key) throw new import_protocol.ArgumentError("Google Cloud KMS key not found");
+    key.state = "superseded";
+    if (this.activeKid === kid) this.activeKid = void 0;
+  }
+  /** Alias for local supersession; never disables or destroys a cloud version. */
+  async purge(kid) {
+    return this.supersede(kid);
+  }
+};
+function validateVersion(version) {
+  if (typeof version !== "string" || !/^projects\/[A-Za-z0-9._:-]+\/locations\/[A-Za-z0-9_-]+\/keyRings\/[A-Za-z0-9_-]+\/cryptoKeys\/[A-Za-z0-9_-]+\/cryptoKeyVersions\/[1-9][0-9]*$/.test(version)) {
+    throw new import_protocol.ArgumentError("Google Cloud KMS requires an immutable CryptoKeyVersion name");
+  }
+}
+async function loadPublicKey(client, version) {
+  const [raw] = await client.getPublicKey({ name: version });
+  const response = raw;
+  if (response?.name !== version) throw new import_protocol.ArgumentError("Google Cloud KMS public key version mismatch");
+  if (response.algorithm !== "EC_SIGN_ED25519" && response.algorithm !== 40) throw new import_protocol.ArgumentError("Google Cloud KMS public key algorithm mismatch");
+  if (response.protectionLevel !== "SOFTWARE" && response.protectionLevel !== 1) throw new import_protocol.ArgumentError("Google Cloud KMS public key must use SOFTWARE protection");
+  if (typeof response.pem !== "string" || !checksumMatches(Buffer.from(response.pem), response.pemCrc32c)) {
+    throw new import_protocol.ArgumentError("Google Cloud KMS public PEM checksum mismatch");
+  }
+  let publicKey;
+  try {
+    if (!response.pem.startsWith("-----BEGIN PUBLIC KEY-----")) throw new Error();
+    const key = (0, import_node_crypto.createPublicKey)({ key: response.pem, format: "pem", type: "spki" });
+    if (key.asymmetricKeyType !== "ed25519") throw new Error();
+    const exported = key.export({ format: "jwk" });
+    publicKey = { kty: "OKP", crv: "Ed25519", x: exported.x, kid: "", alg: "EdDSA", use: "sig" };
+  } catch {
+    throw new import_protocol.ArgumentError("Google Cloud KMS returned invalid Ed25519 public SPKI");
+  }
+  publicKey.kid = await (0, import_protocol.jwkThumbprint)(publicKey);
+  return Object.freeze(publicKey);
+}
+function checksumMatches(bytes, checksum) {
+  const raw = checksum?.value;
+  if (raw === void 0 || raw === null) return false;
+  const text = String(raw);
+  if (!/^[0-9]+$/.test(text)) return false;
+  const value = Number(text);
+  return Number.isSafeInteger(value) && value >= 0 && value <= 4294967295 && value === crc32c(bytes);
+}
+function crc32c(bytes) {
+  let crc = 4294967295;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = crc >>> 1 ^ (crc & 1 ? 2197175160 : 0);
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function ed25519Software(value) {
+  return !!value && (value.algorithm === "EC_SIGN_ED25519" || value.algorithm === 40) && (value.protectionLevel === "SOFTWARE" || value.protectionLevel === 1);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GcpCloudKmsKeyProvider
+});

package/dist/index.d.cts

@@ -0,0 +1,111 @@
+import { KeyProvider, DnsIdJWK } from '@dnsid-ai/protocol';
+
+interface GcpCloudKmsConfig {
+    /** Fully qualified immutable CryptoKeyVersion resource name. */
+    activeKeyVersion: string;
+    /** Application-saved immutable pending version; never discovered or activated by load. */
+    pendingKeyVersion?: string;
+    /** Retained-key loading is not supported by this runtime slice. */
+    retainedKeyVersions?: string[];
+    /** Must be EC_SIGN_ED25519. */
+    algorithm: string;
+}
+/** Structural seam implemented by the official KeyManagementServiceClient. */
+interface GcpCloudKmsClient {
+    /** Required only for initial creation; reads the existing signing parent/template. */
+    getCryptoKey?(request: {
+        name: string;
+    }): Promise<readonly unknown[]>;
+    /** Required when a newly created version is still PENDING_GENERATION. */
+    getCryptoKeyVersion?(request: {
+        name: string;
+    }): Promise<readonly unknown[]>;
+    createCryptoKeyVersion?(request: {
+        parent: string;
+        cryptoKeyVersion: {
+            state: 'ENABLED';
+        };
+    }): Promise<readonly unknown[]>;
+    getPublicKey(request: {
+        name: string;
+    }): Promise<readonly unknown[]>;
+    asymmetricSign(request: {
+        name: string;
+        data: Uint8Array;
+        dataCrc32c: {
+            value: number;
+        };
+    }): Promise<readonly unknown[]>;
+}
+/** Opens existing software Ed25519 versions, or explicitly creates pending versions. */
+declare class GcpCloudKmsKeyProvider implements KeyProvider {
+    private readonly client;
+    private readonly version;
+    private readonly keys;
+    private activeKid;
+    private readonly signing;
+    private activating;
+    private constructor();
+    /**
+     * Creates one version under an existing ASYMMETRIC_SIGN CryptoKey with a
+     * SOFTWARE EC_SIGN_ED25519 template, without opening any prior version.
+     * Returns a locally pending provider and immutable reference; activate(kid)
+     * explicitly before initial manager injection. Never provisions the parent,
+     * writes files, deletes keys, or closes the caller-owned client.
+     * Pending generation polls the same version at most 20 times, 250ms apart.
+     * Each transport call uses the caller's client timeout configuration.
+     * Failed/indeterminate creation may leave an operator-owned remote version;
+     * do not blindly retry. Normal load/configuration remains open-only.
+     */
+    static create(client: GcpCloudKmsClient, config: {
+        parent: string;
+        algorithm: string;
+    }): Promise<{
+        provider: GcpCloudKmsKeyProvider;
+        kid: string;
+        keyRef: string;
+    }>;
+    /**
+     * Opens the selected active version and, optionally, an application-saved pending
+     * version for recovery. Both bindings are validated; the pending key supports
+     * JWK lookup and rotation proof signing but is not the active signer or live
+     * inventory. No discovery, generation, or activation occurs. Applications own
+     * durable references and recovery checks; activate performs the local transition.
+     */
+    static load(client: GcpCloudKmsClient | undefined, config: GcpCloudKmsConfig): Promise<GcpCloudKmsKeyProvider>;
+    signingKey(): Promise<DnsIdJWK>;
+    jwk(kid: string): Promise<DnsIdJWK>;
+    /**
+     * Returns only the current active key ID, or an empty list when no key is active.
+     * Pending and superseded keys are excluded from this live key list, even when
+     * their public JWKs remain available through `jwk` for historical verification.
+     */
+    listKeyIds(): Promise<string[]>;
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+    signKey(kid: string, payload: Uint8Array): Promise<Uint8Array>;
+    private signVersion;
+    validateKeyGeneration(algorithm: string): Promise<void>;
+    /**
+     * Explicit operator generation only; defaults to EdDSA and rejects other algorithms before creation.
+     * Pending generation polls the exact created version at most 20 times, 250ms apart,
+     * using the caller's transport timeouts, just as initial creation does.
+     * Returns a locally pending key without changing the active signer. Failures after
+     * creation retain the version reference and cause, without retrying or deleting it.
+     * Service/integrity failures are not caller-argument errors. Never called by configuration opening.
+     */
+    generateKey(algorithm?: string): Promise<string>;
+    private generatePendingKey;
+    activate(kid: string): Promise<void>;
+    /**
+     * Removes local signing eligibility from an active, pending, or already
+     * superseded key. Superseding the active key leaves no active signer and an
+     * empty live key list; superseding another key does not clear its successor.
+     * The public JWK remains available through `jwk` for historical verification.
+     * Never disables, destroys, or otherwise mutates the remote CryptoKeyVersion.
+     */
+    supersede(kid: string): Promise<void>;
+    /** Alias for local supersession; never disables or destroys a cloud version. */
+    purge(kid: string): Promise<void>;
+}
+
+export { type GcpCloudKmsClient, type GcpCloudKmsConfig, GcpCloudKmsKeyProvider };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { KeyProvider, DnsIdJWK } from '@dnsid-ai/protocol';
+
+interface GcpCloudKmsConfig {
+    /** Fully qualified immutable CryptoKeyVersion resource name. */
+    activeKeyVersion: string;
+    /** Application-saved immutable pending version; never discovered or activated by load. */
+    pendingKeyVersion?: string;
+    /** Retained-key loading is not supported by this runtime slice. */
+    retainedKeyVersions?: string[];
+    /** Must be EC_SIGN_ED25519. */
+    algorithm: string;
+}
+/** Structural seam implemented by the official KeyManagementServiceClient. */
+interface GcpCloudKmsClient {
+    /** Required only for initial creation; reads the existing signing parent/template. */
+    getCryptoKey?(request: {
+        name: string;
+    }): Promise<readonly unknown[]>;
+    /** Required when a newly created version is still PENDING_GENERATION. */
+    getCryptoKeyVersion?(request: {
+        name: string;
+    }): Promise<readonly unknown[]>;
+    createCryptoKeyVersion?(request: {
+        parent: string;
+        cryptoKeyVersion: {
+            state: 'ENABLED';
+        };
+    }): Promise<readonly unknown[]>;
+    getPublicKey(request: {
+        name: string;
+    }): Promise<readonly unknown[]>;
+    asymmetricSign(request: {
+        name: string;
+        data: Uint8Array;
+        dataCrc32c: {
+            value: number;
+        };
+    }): Promise<readonly unknown[]>;
+}
+/** Opens existing software Ed25519 versions, or explicitly creates pending versions. */
+declare class GcpCloudKmsKeyProvider implements KeyProvider {
+    private readonly client;
+    private readonly version;
+    private readonly keys;
+    private activeKid;
+    private readonly signing;
+    private activating;
+    private constructor();
+    /**
+     * Creates one version under an existing ASYMMETRIC_SIGN CryptoKey with a
+     * SOFTWARE EC_SIGN_ED25519 template, without opening any prior version.
+     * Returns a locally pending provider and immutable reference; activate(kid)
+     * explicitly before initial manager injection. Never provisions the parent,
+     * writes files, deletes keys, or closes the caller-owned client.
+     * Pending generation polls the same version at most 20 times, 250ms apart.
+     * Each transport call uses the caller's client timeout configuration.
+     * Failed/indeterminate creation may leave an operator-owned remote version;
+     * do not blindly retry. Normal load/configuration remains open-only.
+     */
+    static create(client: GcpCloudKmsClient, config: {
+        parent: string;
+        algorithm: string;
+    }): Promise<{
+        provider: GcpCloudKmsKeyProvider;
+        kid: string;
+        keyRef: string;
+    }>;
+    /**
+     * Opens the selected active version and, optionally, an application-saved pending
+     * version for recovery. Both bindings are validated; the pending key supports
+     * JWK lookup and rotation proof signing but is not the active signer or live
+     * inventory. No discovery, generation, or activation occurs. Applications own
+     * durable references and recovery checks; activate performs the local transition.
+     */
+    static load(client: GcpCloudKmsClient | undefined, config: GcpCloudKmsConfig): Promise<GcpCloudKmsKeyProvider>;
+    signingKey(): Promise<DnsIdJWK>;
+    jwk(kid: string): Promise<DnsIdJWK>;
+    /**
+     * Returns only the current active key ID, or an empty list when no key is active.
+     * Pending and superseded keys are excluded from this live key list, even when
+     * their public JWKs remain available through `jwk` for historical verification.
+     */
+    listKeyIds(): Promise<string[]>;
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+    signKey(kid: string, payload: Uint8Array): Promise<Uint8Array>;
+    private signVersion;
+    validateKeyGeneration(algorithm: string): Promise<void>;
+    /**
+     * Explicit operator generation only; defaults to EdDSA and rejects other algorithms before creation.
+     * Pending generation polls the exact created version at most 20 times, 250ms apart,
+     * using the caller's transport timeouts, just as initial creation does.
+     * Returns a locally pending key without changing the active signer. Failures after
+     * creation retain the version reference and cause, without retrying or deleting it.
+     * Service/integrity failures are not caller-argument errors. Never called by configuration opening.
+     */
+    generateKey(algorithm?: string): Promise<string>;
+    private generatePendingKey;
+    activate(kid: string): Promise<void>;
+    /**
+     * Removes local signing eligibility from an active, pending, or already
+     * superseded key. Superseding the active key leaves no active signer and an
+     * empty live key list; superseding another key does not clear its successor.
+     * The public JWK remains available through `jwk` for historical verification.
+     * Never disables, destroys, or otherwise mutates the remote CryptoKeyVersion.
+     */
+    supersede(kid: string): Promise<void>;
+    /** Alias for local supersession; never disables or destroys a cloud version. */
+    purge(kid: string): Promise<void>;
+}
+
+export { type GcpCloudKmsClient, type GcpCloudKmsConfig, GcpCloudKmsKeyProvider };