@dnsid-ai/key-gcp 0.35.0 → 0.36.0

package/README.md

@@ -1,8 +1,10 @@
 # @dnsid-ai/key-gcp
 
-Optional Node.js Google Cloud KMS provider for an existing **software
-EC_SIGN_ED25519** key version. Install this package separately from the base SDK;
-its Google dependency is not required by base SDK consumers.
+Optional Node.js Google Cloud KMS provider that opens existing **software
+EC_SIGN_ED25519** key versions or explicitly creates a pending first version
+through `create()` under an existing compatible CryptoKey. Install this package
+separately from the base SDK; its Google dependency is not required by base SDK
+consumers.
 
 ```ts
 import { KeyManagementServiceClient } from '@google-cloud/kms';
@@ -14,13 +16,28 @@ const keyProvider = await GcpCloudKmsKeyProvider.load(new KeyManagementServiceCl
 });
 ```
 
-Use ambient Google credentials with permission to read the public key and sign.
+Use ambient Google credentials with `cloudkms.cryptoKeyVersions.viewPublicKey`
+and `cloudkms.cryptoKeyVersions.useToSign` permissions. Both initial `create()`
+and rotation through `generateKey()` also require
+`cloudkms.cryptoKeyVersions.create` and `cloudkms.cryptoKeyVersions.get` for
+version creation and readiness metadata reads. Initial `create()` additionally
+requires `cloudkms.cryptoKeys.get` to validate the existing parent. Grant the
+version metadata-read permission before either operation: a readiness read can
+fail after the remote version has already been created.
 The reference must name a numeric immutable version, not a parent or alias. The
 provider exports only the public Ed25519 JWK, with an RFC 7638 thumbprint as `kid`.
 It sends raw data (never a digest) and verifies request/response CRC32C integrity
 and returned version bindings. Google transport and permission errors propagate;
 there is no local signing fallback, key import, or generation during opening.
 
+For first-key creation, explicitly call `GcpCloudKmsKeyProvider.create` with an
+existing `ASYMMETRIC_SIGN` CryptoKey parent whose version template is
+`EC_SIGN_ED25519` / `SOFTWARE`; no prior version is required. See the
+[KMS-first setup guide](https://github.com/dnsid-ai/dnsid-ts/blob/main/docs/kms-first-setup.md) for pending-key activation,
+reference handoff, publication boundaries, and failure recovery. Subsequent
+startup must reopen the saved immutable version with `load`, never recreate it;
+normal configuration remains open-only.
+
 Configuration selects this optional package with `provider: "google-kms"`, the
 immutable version as `keyRef`, and optional `settings.algorithm: "EdDSA"` (the
 only supported deployment algorithm). SDK composition translates `EdDSA` to the
@@ -39,7 +56,12 @@ const keySource = {
 An explicit `generateKey()` or `generateKey('EdDSA')` creates a pending software
 Ed25519 version under the same CryptoKey. Other requested algorithms are rejected
 before creation. `validateKeyGeneration('EdDSA')` checks algorithm support without
-creating a version. Generation does not change deployment configuration or the active signer.
+creating a version. Like first-key creation, generation waits for the exact created
+version to become enabled, polling pending generation at most 20 times, 250ms apart.
+Transport call deadlines remain caller-owned. Post-create failures retain the known
+version reference and cause; service/integrity failures are not caller-argument
+errors. There is no automatic recreation or deletion on failure.
+Generation does not change deployment configuration or the active signer.
 Pending keys support `jwk` and `signKey`; `activate` drains in-flight signatures
 and blocks new signing while promoting the pending key. `listKeyIds` contains
 only the active ID, or is empty after local supersession. `supersede` and its
@@ -47,6 +69,14 @@ only the active ID, or is empty after local supersession. `supersede` and its
 destroyed. Historical public keys remain available through `jwk`.
 
 Lifecycle state is in memory. Applications own durable recovery and publication
-orchestration; reopening the configured version does not recover pending state.
+orchestration. For recovery, pass the application's saved immutable A reference
+as `activeKeyVersion` and saved B reference as optional `pendingKeyVersion` to
+`load`. Both versions and public bindings are validated; duplicate versions or
+public-key identities are rejected. B is inserted directly as pending: `jwk` and
+rotation `signKey` are available, while `signingKey`, `sign`, and `listKeyIds`
+continue to select only A. Existing `activate` performs the local transition.
+This input is saved application state, not key discovery or permission to activate;
+managed recovery still validates the saved rotation's exact bindings. Ordinary
+A-only loading is unchanged and does not discover pending state.
 Retained-key configuration loading is rejected. Lifecycle behavior implements
 the provisional shared #56 clarification, not a claim of contract acceptance.

package/dist/index.cjs

@@ -39,8 +39,10 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
   constructor(client, version, publicKey) {
     this.client = client;
     this.version = version;
-    this.activeKid = publicKey.kid;
-    this.keys.set(publicKey.kid, { version, jwk: publicKey, state: "active" });
+    if (publicKey) {
+      this.activeKid = publicKey.kid;
+      this.keys.set(publicKey.kid, { version, jwk: publicKey, state: "active" });
+    }
   }
   client;
   version;
@@ -48,10 +50,46 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
   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;
-    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");
+    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");
@@ -59,26 +97,12 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
       const { KeyManagementServiceClient } = await import("@google-cloud/kms");
       client = new KeyManagementServiceClient();
     }
-    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 new _GcpCloudKmsKeyProvider(client, version, Object.freeze(publicKey));
+    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");
@@ -127,21 +151,46 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
   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. Never called by configuration opening. */
+  /**
+   * 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.slice(0, this.version.lastIndexOf("/cryptoKeyVersions/"));
+    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" } });
-    const created = raw;
-    if (!created?.name?.startsWith(parent + "/cryptoKeyVersions/") || created.algorithm !== "EC_SIGN_ED25519" && created.algorithm !== 40 || created.protectionLevel !== "SOFTWARE" && created.protectionLevel !== 1 || created.state !== "ENABLED" && created.state !== 1) {
-      throw new import_protocol.ArgumentError("Google Cloud KMS created an unexpected key version");
+    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 });
     }
-    const pending = await _GcpCloudKmsKeyProvider.load(this.client, { activeKeyVersion: created.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: created.name, jwk: Object.freeze(jwk), state: "pending" });
-    return jwk.kid;
   }
   async activate(kid) {
     if (this.activating) throw new import_protocol.ArgumentError("Google Cloud KMS activation is already in progress");
@@ -176,6 +225,33 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
     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;
@@ -192,6 +268,9 @@ function crc32c(bytes) {
   }
   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

@@ -3,6 +3,8 @@ 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. */
@@ -10,6 +12,14 @@ interface GcpCloudKmsConfig {
 }
 /** 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: {
@@ -27,7 +37,7 @@ interface GcpCloudKmsClient {
         };
     }): Promise<readonly unknown[]>;
 }
-/** Opens one existing software Ed25519 version without cloud mutation or fallback. */
+/** Opens existing software Ed25519 versions, or explicitly creates pending versions. */
 declare class GcpCloudKmsKeyProvider implements KeyProvider {
     private readonly client;
     private readonly version;
@@ -36,6 +46,32 @@ declare class GcpCloudKmsKeyProvider implements KeyProvider {
     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>;
@@ -49,8 +85,16 @@ declare class GcpCloudKmsKeyProvider implements KeyProvider {
     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. Never called by configuration opening. */
+    /**
+     * 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

package/dist/index.d.ts

@@ -3,6 +3,8 @@ 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. */
@@ -10,6 +12,14 @@ interface GcpCloudKmsConfig {
 }
 /** 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: {
@@ -27,7 +37,7 @@ interface GcpCloudKmsClient {
         };
     }): Promise<readonly unknown[]>;
 }
-/** Opens one existing software Ed25519 version without cloud mutation or fallback. */
+/** Opens existing software Ed25519 versions, or explicitly creates pending versions. */
 declare class GcpCloudKmsKeyProvider implements KeyProvider {
     private readonly client;
     private readonly version;
@@ -36,6 +46,32 @@ declare class GcpCloudKmsKeyProvider implements KeyProvider {
     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>;
@@ -49,8 +85,16 @@ declare class GcpCloudKmsKeyProvider implements KeyProvider {
     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. Never called by configuration opening. */
+    /**
+     * 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

package/dist/index.js

@@ -5,8 +5,10 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
   constructor(client, version, publicKey) {
     this.client = client;
     this.version = version;
-    this.activeKid = publicKey.kid;
-    this.keys.set(publicKey.kid, { version, jwk: publicKey, state: "active" });
+    if (publicKey) {
+      this.activeKid = publicKey.kid;
+      this.keys.set(publicKey.kid, { version, jwk: publicKey, state: "active" });
+    }
   }
   client;
   version;
@@ -14,10 +16,46 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
   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 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 ArgumentError("Google Cloud KMS creation requires a CryptoKey parent");
+    }
+    if (!client.getCryptoKey || !client.createCryptoKeyVersion) throw new 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 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;
-    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 ArgumentError("Google Cloud KMS requires an immutable CryptoKeyVersion name");
+    validateVersion(version);
+    const pendingVersion = config.pendingKeyVersion;
+    if (pendingVersion !== void 0) {
+      validateVersion(pendingVersion);
+      if (pendingVersion === version) throw new ArgumentError("Google Cloud KMS active and pending versions must differ");
     }
     if (config.algorithm !== "EC_SIGN_ED25519") throw new ArgumentError("Google Cloud KMS algorithm must be EC_SIGN_ED25519");
     if (config.retainedKeyVersions?.length) throw new ArgumentError("Google Cloud KMS retained key loading is not supported");
@@ -25,26 +63,12 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
       const { KeyManagementServiceClient } = await import("@google-cloud/kms");
       client = new KeyManagementServiceClient();
     }
-    const [raw] = await client.getPublicKey({ name: version });
-    const response = raw;
-    if (response?.name !== version) throw new ArgumentError("Google Cloud KMS public key version mismatch");
-    if (response.algorithm !== "EC_SIGN_ED25519" && response.algorithm !== 40) throw new ArgumentError("Google Cloud KMS public key algorithm mismatch");
-    if (response.protectionLevel !== "SOFTWARE" && response.protectionLevel !== 1) throw new ArgumentError("Google Cloud KMS public key must use SOFTWARE protection");
-    if (typeof response.pem !== "string" || !checksumMatches(Buffer.from(response.pem), response.pemCrc32c)) {
-      throw new ArgumentError("Google Cloud KMS public PEM checksum mismatch");
-    }
-    let publicKey;
-    try {
-      if (!response.pem.startsWith("-----BEGIN PUBLIC KEY-----")) throw new Error();
-      const key = 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 ArgumentError("Google Cloud KMS returned invalid Ed25519 public SPKI");
-    }
-    publicKey.kid = await jwkThumbprint(publicKey);
-    return new _GcpCloudKmsKeyProvider(client, version, Object.freeze(publicKey));
+    const publicKey = await loadPublicKey(client, version);
+    const pendingKey = pendingVersion === void 0 ? void 0 : await loadPublicKey(client, pendingVersion);
+    if (pendingKey?.kid === publicKey.kid) throw new 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 ArgumentError("Google Cloud KMS has no active key");
@@ -93,21 +117,46 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
   async validateKeyGeneration(algorithm) {
     if (algorithm !== "EdDSA") throw new ArgumentError(`Google Cloud KMS generation settings do not support ${algorithm}`);
   }
-  /** Explicit operator generation only; defaults to EdDSA and rejects other algorithms before creation. Never called by configuration opening. */
+  /**
+   * 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 ArgumentError("Google Cloud KMS client does not support version creation");
-    const parent = this.version.slice(0, this.version.lastIndexOf("/cryptoKeyVersions/"));
+    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" } });
-    const created = raw;
-    if (!created?.name?.startsWith(parent + "/cryptoKeyVersions/") || created.algorithm !== "EC_SIGN_ED25519" && created.algorithm !== 40 || created.protectionLevel !== "SOFTWARE" && created.protectionLevel !== 1 || created.state !== "ENABLED" && created.state !== 1) {
-      throw new ArgumentError("Google Cloud KMS created an unexpected key version");
+    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 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 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 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 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 });
     }
-    const pending = await _GcpCloudKmsKeyProvider.load(this.client, { activeKeyVersion: created.name, algorithm: "EC_SIGN_ED25519" });
-    const jwk = await pending.signingKey();
-    if (this.keys.has(jwk.kid)) throw new ArgumentError("Google Cloud KMS generated duplicate public key");
-    this.keys.set(jwk.kid, { version: created.name, jwk: Object.freeze(jwk), state: "pending" });
-    return jwk.kid;
   }
   async activate(kid) {
     if (this.activating) throw new ArgumentError("Google Cloud KMS activation is already in progress");
@@ -142,6 +191,33 @@ var GcpCloudKmsKeyProvider = class _GcpCloudKmsKeyProvider {
     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 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 ArgumentError("Google Cloud KMS public key version mismatch");
+  if (response.algorithm !== "EC_SIGN_ED25519" && response.algorithm !== 40) throw new ArgumentError("Google Cloud KMS public key algorithm mismatch");
+  if (response.protectionLevel !== "SOFTWARE" && response.protectionLevel !== 1) throw new ArgumentError("Google Cloud KMS public key must use SOFTWARE protection");
+  if (typeof response.pem !== "string" || !checksumMatches(Buffer.from(response.pem), response.pemCrc32c)) {
+    throw new ArgumentError("Google Cloud KMS public PEM checksum mismatch");
+  }
+  let publicKey;
+  try {
+    if (!response.pem.startsWith("-----BEGIN PUBLIC KEY-----")) throw new Error();
+    const key = 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 ArgumentError("Google Cloud KMS returned invalid Ed25519 public SPKI");
+  }
+  publicKey.kid = await jwkThumbprint(publicKey);
+  return Object.freeze(publicKey);
+}
 function checksumMatches(bytes, checksum) {
   const raw = checksum?.value;
   if (raw === void 0 || raw === null) return false;
@@ -158,6 +234,9 @@ function crc32c(bytes) {
   }
   return (crc ^ 4294967295) >>> 0;
 }
+function ed25519Software(value) {
+  return !!value && (value.algorithm === "EC_SIGN_ED25519" || value.algorithm === 40) && (value.protectionLevel === "SOFTWARE" || value.protectionLevel === 1);
+}
 export {
   GcpCloudKmsKeyProvider
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dnsid-ai/key-gcp",
   "author": "Known Systems AI, Inc.",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "DNSid Google Cloud KMS Ed25519 key provider integration.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -40,7 +40,7 @@
     "prepack": "node ../../scripts/copy-notice.mjs"
   },
   "dependencies": {
-    "@dnsid-ai/protocol": "^0.35.0",
+    "@dnsid-ai/protocol": "^0.36.0",
     "@google-cloud/kms": "^6.3.0"
   },
   "license": "Apache-2.0",