@dnsid-ai/sdk 0.29.0 → 0.31.0

package/README.md

@@ -68,6 +68,40 @@ If `ManagedKeyRotationActivationError` is raised, registry acceptance succeeded
 but local key-state reconciliation is incomplete. Resume with the error's exact
 rotation state; already-completed activation or supersession is not repeated.
 
+Rotation requires `persistRotation`, `setApplicationSigningPaused`,
+`setApplicationSigner`, and `verifyPublicationEvidence`. The verifier must return
+fresh protocol-verified signed TXT/ku evidence; evict old publication evidence
+before verification. Acceptance is checked against the saved bytes/hash, new
+key, and indexed log reference before publication and continuity checks.
+
+Supply stable `previousProviderReference` and `newProviderReference` values;
+`targetKeyProvider` optionally selects another provider. Recovery uses
+`resolveKeyProvider(reference)` to restore the saved providers, not current
+deployment settings. It restores the saved new signer before unpausing.
+Old rotation records without the new bindings must not be resumed automatically.
+Recovery rejects unrelated active source keys. A removed previous key is accepted
+only with saved acceptance and the exact saved target key already active; for
+cross-provider recovery, the source must have no active key. Provider lookup
+errors, including a listed but unavailable previous key, fail recovery.
+Resolvers must reopen the saved provider state, not create replacement state.
+
+Set `targetAlgorithm` (`EdDSA` or `ES256`) when changing algorithms; omission
+preserves the previous algorithm. The target's `validateKeyGeneration(algorithm)`
+checks settings/support before generation, and rotation checks the generated key
+before registry preparation. Providers without this hook must already have an
+active key using the selected algorithm. Local generation accepts either
+algorithm; AWS generation must match the configured KMS algorithm.
+
+Custom providers that can retire their active key may implement
+`activeSigningKey()` to return `null` when none exists. Without this hook,
+recovery treats an empty `listKeyIds()` as no active key and otherwise calls
+`signingKey()`; lookup errors are never treated as completed supersession.
+
+Cross-provider transfer requires a previous provider that supports superseding
+its active key after transfer. Built-in local and AWS providers currently reject
+this operation. AWS and CLI/in-memory provider state also needs application-owned
+durable recovery. These limits are declared in `SDK_CONFORMANCE.knownDeviations`.
+
 ## Node.js convenience usage
 
 ```ts

package/dist/index.cjs

@@ -128,18 +128,35 @@ var ManagedKeyRotationActivationError = class extends import_protocol.Verificati
   }
 };
 async function rotateManagedOperationalKey(options) {
+  assertCoordination(options);
+  const domain = (0, import_protocol.normalizeFQDN)(options.domain, true);
+  assertOperationReferences(options.previousProviderReference, options.newProviderReference, options.idempotencyKey);
+  const target = options.targetKeyProvider ?? options.keyProvider;
+  if (target === options.keyProvider !== (options.previousProviderReference === options.newProviderReference)) {
+    throw new import_protocol.ArgumentError("provider references must identify the selected previous and target providers");
+  }
   const previousKey = await options.keyProvider.signingKey();
   new import_protocol.JWKS([previousKey]).validateOperational();
   const previousThumbprint = await (0, import_protocol.jwkThumbprint)(previousKey);
-  const newKid = await options.keyProvider.generateKey();
-  const newKey = await options.keyProvider.jwk(newKid);
+  const algorithm = options.targetAlgorithm ?? previousKey.alg;
+  if (algorithm !== "EdDSA" && algorithm !== "ES256") throw new import_protocol.ArgumentError("unsupported target algorithm");
+  if (target.validateKeyGeneration) {
+    await target.validateKeyGeneration(algorithm);
+  } else {
+    const active = await target.signingKey();
+    new import_protocol.JWKS([active]).validateOperational();
+    if (active.alg !== algorithm) throw new import_protocol.ArgumentError("target provider must validate support for the selected algorithm");
+  }
+  const newKid = await target.generateKey(algorithm);
+  const newKey = await target.jwk(newKid);
   new import_protocol.JWKS([newKey]).validateOperational();
+  if (newKey.alg !== algorithm) throw permanentRotationError("generated key does not use the selected algorithm");
   if (await (0, import_protocol.jwkThumbprint)(newKey) === previousThumbprint) {
     throw permanentRotationError("managed KEY_ROTATION requires a distinct pending operational key");
   }
   let raw;
   try {
-    raw = await options.registryClient.prepareKeyRotation(options.domain, {
+    raw = await options.registryClient.prepareKeyRotation(domain, {
       previousKeyId: previousThumbprint,
       publicKey: newKey
     }, options.idempotencyKey);
@@ -153,12 +170,12 @@ async function rotateManagedOperationalKey(options) {
   if (raw.logReference !== options.logReference) {
     throw permanentRotationError(`registry preparation returned unexpected log reference ${raw.logReference}`);
   }
-  const context = { expectedFqdn: options.domain, previousOperationalKey: previousKey };
+  const context = { expectedFqdn: domain, previousOperationalKey: previousKey };
   let prepared = await (0, import_writer.parsePreparedC2spTlogEvent)(raw.entryBytes, raw.logReference, context);
   if (prepared.envelope.type !== "KEY_ROTATION") {
     throw permanentRotationError(`registry preparation returned ${String(prepared.envelope.type)} instead of KEY_ROTATION`);
   }
-  if (prepared.envelope.fqdn !== options.domain) {
+  if (prepared.envelope.fqdn !== domain) {
     throw permanentRotationError("registry KEY_ROTATION fqdn does not match the expected identity");
   }
   if (prepared.envelope.prev_thumb !== previousThumbprint) {
@@ -166,40 +183,61 @@ async function rotateManagedOperationalKey(options) {
   }
   await assertPreparedRotationKey(prepared.envelope.new_ku, prepared.envelope.new_thumb, newKey);
   prepared = await (0, import_writer.signPreparedC2spTlogEvent)(prepared, "PreviousOperational", options.keyProvider, context);
-  prepared = await (0, import_writer.signPreparedC2spTlogEvent)(prepared, "NewOperational", options.keyProvider, context);
+  prepared = await (0, import_writer.signPreparedC2spTlogEvent)(prepared, "NewOperational", target, context);
   const entryBytes = await (0, import_writer.c2spTlogEntryBytes)(prepared, context);
   const rotation = {
-    domain: options.domain,
+    domain,
     logReference: options.logReference,
     previousKid: previousKey.kid,
     newKid,
+    previousProviderReference: options.previousProviderReference,
+    newProviderReference: options.newProviderReference,
+    previousKey,
+    previousThumbprint,
+    newThumbprint: await (0, import_protocol.jwkThumbprint)(newKey),
+    entryHash: await sha256Hex(entryBytes),
     entryBytes: entryBytes.slice(),
     idempotencyKey: options.idempotencyKey,
     activated: false,
     applicationSigningPaused: true
   };
-  await options.persistRotation(rotation);
-  await options.setApplicationSigningPaused(true);
-  return submitManagedRotation(options.keyProvider, options.registryClient, rotation, options.persistRotation, options.setApplicationSigningPaused);
+  try {
+    await options.persistRotation(rotation);
+    await options.setApplicationSigningPaused(true);
+  } catch (cause) {
+    throw new ManagedKeyRotationSubmissionError("managed rotation persistence or pause failed; resume this state", rotation, true, cause);
+  }
+  return submitManagedRotation(options, options.keyProvider, target, rotation);
 }
 async function resumeManagedOperationalKeyRotation(options) {
-  if (options.rotation.activated) {
-    if (!options.rotation.applicationSigningPaused) return options.rotation;
-    await options.setApplicationSigningPaused(false);
-    const completed = { ...options.rotation, applicationSigningPaused: false };
-    await options.persistRotation(completed);
-    return completed;
-  }
-  if (options.rotation.submission?.state === "rejected") {
-    throw permanentRotationError("cannot resume a rejected managed key rotation");
+  assertCoordination(options);
+  if (typeof options.resolveKeyProvider !== "function") throw new import_protocol.ArgumentError("managed rotation recovery requires resolveKeyProvider");
+  const rotation = options.rotation;
+  try {
+    assertOperationReferences(rotation.previousProviderReference, rotation.newProviderReference, rotation.idempotencyKey);
+    const previous = await options.resolveKeyProvider(rotation.previousProviderReference);
+    const target = rotation.newProviderReference === rotation.previousProviderReference ? previous : await options.resolveKeyProvider(rotation.newProviderReference);
+    await validateSavedRotation(rotation, previous, target);
+    if (rotation.submission?.state === "rejected") {
+      throw new ManagedKeyRotationSubmissionError("cannot resume a rejected managed key rotation", rotation, false);
+    }
+    await options.setApplicationSigningPaused(true);
+    if (rotation.submission?.state === "accepted") {
+      await assertSubmissionMatchesRotation(rotation, rotation.submission);
+      return activateRotation(options, previous, target, rotation);
+    }
+    if (rotation.activated) throw permanentRotationError("activated rotation has no accepted submission");
+    await options.persistRotation(rotation);
+    return submitManagedRotation(options, previous, target, rotation);
+  } catch (cause) {
+    if (cause instanceof ManagedKeyRotationSubmissionError || cause instanceof ManagedKeyRotationActivationError) throw cause;
+    throw new ManagedKeyRotationActivationError("managed rotation recovery failed; signing must remain paused", rotation, cause);
   }
-  await options.setApplicationSigningPaused(true);
-  return submitManagedRotation(options.keyProvider, options.registryClient, options.rotation, options.persistRotation, options.setApplicationSigningPaused);
 }
-async function submitManagedRotation(keyProvider, registryClient, rotation, persistRotation, setApplicationSigningPaused) {
+async function submitManagedRotation(options, previous, target, rotation) {
   let submission;
   try {
-    submission = await registryClient.submitPreparedEvent(rotation.domain, rotation.entryBytes, rotation.idempotencyKey);
+    submission = await options.registryClient.submitPreparedEvent(rotation.domain, rotation.entryBytes, rotation.idempotencyKey);
   } catch (cause) {
     const retryWithSameBytes2 = structuredRetryWithSameBytes(cause);
     throw new ManagedKeyRotationSubmissionError(
@@ -209,9 +247,13 @@ async function submitManagedRotation(keyProvider, registryClient, rotation, pers
       cause
     );
   }
-  await assertSubmissionMatchesRotation(rotation, submission);
   const next = { ...rotation, submission };
-  await persistRotation(next);
+  try {
+    await assertSubmissionMatchesRotation(rotation, submission);
+    await options.persistRotation(next);
+  } catch (cause) {
+    throw new ManagedKeyRotationSubmissionError("managed rotation acceptance binding or persistence failed; resume this state", next, true, cause);
+  }
   if (submission.state === "rejected") {
     throw new ManagedKeyRotationSubmissionError(
       `registry rejected the prepared KEY_ROTATION: ${submission.errorCode ?? "unknown error"}`,
@@ -220,15 +262,24 @@ async function submitManagedRotation(keyProvider, registryClient, rotation, pers
     );
   }
   if (submission.state !== "accepted") return next;
-  let recoverable = next;
+  return activateRotation(options, previous, target, next);
+}
+async function activateRotation(options, previous, target, rotation) {
+  let recoverable = rotation;
   try {
-    await reconcileAcceptedRotation(keyProvider, rotation);
-    const activated = { ...next, activated: true };
-    await persistRotation(activated);
+    await verifyAcceptedPublication(options, rotation);
+    if (!rotation.activated) await reconcileAcceptedRotation(previous, target, rotation);
+    if (previous !== target && await activeKey(previous, await previous.listKeyIds())) {
+      throw permanentRotationError("superseded source provider still has an active signing key");
+    }
+    const activated = { ...rotation, activated: true, applicationSigningPaused: true };
+    await options.persistRotation(activated);
     recoverable = activated;
-    await setApplicationSigningPaused(false);
+    await assertKeyBinding(await target.signingKey(), rotation.newKid, rotation.newThumbprint);
+    await options.setApplicationSigner(target, rotation.newKid);
+    await options.setApplicationSigningPaused(false);
     const completed = { ...activated, applicationSigningPaused: false };
-    await persistRotation(completed);
+    await options.persistRotation(completed);
     return completed;
   } catch (cause) {
     throw new ManagedKeyRotationActivationError(
@@ -238,15 +289,84 @@ async function submitManagedRotation(keyProvider, registryClient, rotation, pers
     );
   }
 }
-async function reconcileAcceptedRotation(keyProvider, rotation) {
-  const activeKid = (await keyProvider.signingKey()).kid;
-  if (activeKid === rotation.previousKid) {
-    await keyProvider.activate(rotation.newKid);
-  } else if (activeKid !== rotation.newKid) {
-    throw permanentRotationError(`unexpected active key ${activeKid} while reconciling managed key rotation`);
+async function reconcileAcceptedRotation(previous, target, rotation) {
+  const active = await target.signingKey();
+  if (active.kid !== rotation.newKid) {
+    if (previous === target) await assertKeyBinding(active, rotation.previousKid, rotation.previousThumbprint);
+    await target.activate(rotation.newKid);
+  }
+  await assertKeyBinding(await target.signingKey(), rotation.newKid, rotation.newThumbprint);
+  if ((await previous.listKeyIds()).includes(rotation.previousKid)) await previous.supersede(rotation.previousKid);
+}
+function assertCoordination(options) {
+  for (const name of ["persistRotation", "setApplicationSigningPaused", "setApplicationSigner", "verifyPublicationEvidence"]) {
+    if (typeof options[name] !== "function") throw new import_protocol.ArgumentError(`managed rotation requires ${name}`);
+  }
+}
+function assertOperationReferences(previous, next, idempotencyKey) {
+  if (!previous?.trim() || !next?.trim() || !idempotencyKey || idempotencyKey.trim() !== idempotencyKey || idempotencyKey.length > 200) {
+    throw permanentRotationError("managed rotation requires provider references and a valid idempotency key");
   }
-  if ((await keyProvider.listKeyIds()).includes(rotation.previousKid)) {
-    await keyProvider.supersede(rotation.previousKid);
+}
+async function assertKeyBinding(key, kid, thumbprint) {
+  new import_protocol.JWKS([key]).validateOperational();
+  if (key.kid !== kid || await (0, import_protocol.jwkThumbprint)(key) !== thumbprint) {
+    throw permanentRotationError("saved managed rotation key binding mismatch");
+  }
+}
+async function activeKey(provider, listedIds) {
+  if (provider.activeSigningKey) return provider.activeSigningKey();
+  return listedIds.length ? provider.signingKey() : null;
+}
+async function validateSavedRotation(rotation, previous, target) {
+  assertOperationReferences(rotation.previousProviderReference, rotation.newProviderReference, rotation.idempotencyKey);
+  if (typeof rotation.activated !== "boolean" || typeof rotation.applicationSigningPaused !== "boolean" || (0, import_protocol.normalizeFQDN)(rotation.domain, true) !== rotation.domain || await sha256Hex(rotation.entryBytes) !== rotation.entryHash) {
+    throw permanentRotationError("saved managed rotation domain or entry hash mismatch");
+  }
+  await assertKeyBinding(rotation.previousKey, rotation.previousKid, rotation.previousThumbprint);
+  const previousIds = await previous.listKeyIds();
+  const sourceActive = await activeKey(previous, previousIds);
+  if (previousIds.includes(rotation.previousKid)) {
+    await assertKeyBinding(await previous.jwk(rotation.previousKid), rotation.previousKid, rotation.previousThumbprint);
+    if (sourceActive) {
+      const targetIsActive = previous === target && rotation.submission?.state === "accepted" && sourceActive.kid === rotation.newKid;
+      await assertKeyBinding(
+        sourceActive,
+        targetIsActive ? rotation.newKid : rotation.previousKid,
+        targetIsActive ? rotation.newThumbprint : rotation.previousThumbprint
+      );
+    }
+  } else {
+    if (rotation.submission?.state !== "accepted") throw permanentRotationError("saved previous key is unavailable without saved acceptance");
+    await assertSubmissionMatchesRotation(rotation, rotation.submission);
+    await assertKeyBinding(await target.signingKey(), rotation.newKid, rotation.newThumbprint);
+    if (previous !== target && sourceActive) throw permanentRotationError("superseded source provider still has an active signing key");
+  }
+  const next = await target.jwk(rotation.newKid);
+  await assertKeyBinding(next, rotation.newKid, rotation.newThumbprint);
+  const context = { expectedFqdn: rotation.domain, previousOperationalKey: rotation.previousKey };
+  const prepared = await (0, import_writer.parsePreparedC2spTlogEvent)(rotation.entryBytes, rotation.logReference, context);
+  if (prepared.envelope.type !== "KEY_ROTATION" || prepared.envelope.fqdn !== rotation.domain || prepared.envelope.prev_thumb !== rotation.previousThumbprint) {
+    throw permanentRotationError("saved managed rotation event binding mismatch");
+  }
+  await assertPreparedRotationKey(prepared.envelope.new_ku, prepared.envelope.new_thumb, next);
+  await (0, import_writer.c2spTlogEntryBytes)(prepared, context);
+  if (rotation.submission) await assertSubmissionMatchesRotation(rotation, rotation.submission);
+}
+async function verifyAcceptedPublication(options, rotation) {
+  const verified = await options.verifyPublicationEvidence(rotation.domain);
+  if (verified.domain !== rotation.domain || verified.record.lr !== rotation.logReference) {
+    throw permanentRotationError("current signed publication does not match managed rotation");
+  }
+  await assertKeyBinding(verified.jwks.currentOperationalSigningKey(), rotation.newKid, rotation.newThumbprint);
+  const prepared = await (0, import_writer.parsePreparedC2spTlogEvent)(rotation.entryBytes, rotation.logReference, {
+    expectedFqdn: rotation.domain,
+    previousOperationalKey: rotation.previousKey
+  });
+  const signatures = prepared.envelope.sigs;
+  const event = await verified.logReader.readEvent(rotation.submission.logRef);
+  if (event.type !== "KEY_ROTATION" || event.domain !== rotation.domain || event.previousOperationalThumbprint !== rotation.previousThumbprint || event.newOperationalKid !== rotation.newKid || event.newOperationalThumbprint !== rotation.newThumbprint || event.signingKid !== signatures.prev_op.kid || event.sig !== signatures.prev_op.sig || event.newOperationalProof !== signatures.new_op.sig || event.timestamp.getTime() !== prepared.envelope.ts * 1e3) {
+    throw permanentRotationError("accepted managed rotation continuity mismatch");
   }
 }
 async function assertPreparedRotationKey(value, thumbprint, expected) {
@@ -263,12 +383,18 @@ async function assertSubmissionMatchesRotation(rotation, submission) {
   if (rotation.submission?.entryHash && submission.entryHash && rotation.submission.entryHash !== submission.entryHash) {
     throw permanentRotationError("registry reconciled a different entry hash for this managed key rotation");
   }
+  if (submission.entryHash !== void 0 && submission.entryHash !== rotation.entryHash) {
+    throw permanentRotationError("submission entry hash does not match the exact managed key rotation bytes");
+  }
   if (submission.state !== "accepted") return;
   const expectedHash = await sha256Hex(rotation.entryBytes);
   if (submission.entryHash !== expectedHash) {
     throw permanentRotationError("accepted submission entry hash does not match the exact managed key rotation bytes");
   }
-  if (submission.keyId !== void 0 && submission.keyId !== rotation.newKid) {
+  if (submission.logRef !== `${rotation.logReference}@${submission.index}` || !Number.isSafeInteger(submission.index) || submission.index < 0) {
+    throw permanentRotationError("accepted submission log reference does not match managed rotation");
+  }
+  if (submission.keyId !== rotation.newKid) {
     throw permanentRotationError("accepted submission key_id does not match the generated pending key");
   }
 }
@@ -579,7 +705,11 @@ var SDK_CONFORMANCE = Object.freeze({
   logBindings: Object.freeze({
     "c2sp-tlog": c2spTlogConformance
   }),
-  knownDeviations: Object.freeze([])
+  knownDeviations: Object.freeze([
+    "Managed cross-provider rotation requires providers that can supersede the previous active key after transfer; built-in LocalKeyProvider and AwsKmsKeyProvider reject active-key supersession.",
+    "AWS KMS and CLI/in-memory key providers do not durably persist rotation key state; restart recovery requires application-managed provider state or a file-backed local key store.",
+    "Account onboarding validates bindings and reports proof readiness, but does not implement named managed creation or establish permanent registration replay claims."
+  ])
 });
 
 // src/index.ts

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { VerificationError, KeyProvider, DnsIdJWK, IdentityManagerDependencies, DnsidConfig, IdentityManager } from '@dnsid-ai/protocol';
+import { VerificationError, DnsIdJWK, KeyProvider, VerifiedDomain, IdentityManagerDependencies, DnsidConfig, IdentityManager } from '@dnsid-ai/protocol';
 export * from '@dnsid-ai/protocol';
 export { ArgumentError, DNSID_VERSION, DNSSECMode, DNSSECState, DnsIdTxtRecord, DomainLog, DomainSnapshot, IdentityManager, InMemoryIdentityCache, JWKS, JWKS_MAX_RESPONSE_BYTES, LogRegistry, NoopLogReader, ParseError, SIGNING_ALGS, STATUS_MAX_RESPONSE_BYTES, ValidationError, VerificationCode, VerificationError, VerifiedDomain, activeStatusDocument, fromBase64Url, isDomainName, isTransientVerificationError, jwkSignatureAlg, jwkThumbprint, normalizeFQDN, parseKaDuration, parseKeyId, retryTransientVerification, toArrayBuffer, toBase64Url, validateAgentStatus, verifyWithKey } from '@dnsid-ai/protocol';
 import * as jose from '@dnsid-ai/jose';
@@ -19,24 +19,42 @@ interface ManagedKeyRotationRegistry {
     prepareKeyRotation(domain: string, request: KeyRotationPreparationRequest, idempotencyKey: string): Promise<PreparedRegistryEvent>;
     submitPreparedEvent(domain: string, entryBytes: Uint8Array, idempotencyKey: string): Promise<SubmissionResult>;
 }
-interface RotateManagedOperationalKeyOptions {
+interface ManagedKeyRotationCoordination {
+    /** Durably persists exact bytes and every subsequent reconciliation state. */
+    persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
+    /** Blocks new application signing and drains in-flight request/directory signing before resolving;
+     * resumes signing only after durable activation. */
+    setApplicationSigningPaused: (paused: boolean) => Promise<void>;
+    /** Restores the application signer before signing is resumed. */
+    setApplicationSigner: (provider: KeyProvider, kid: string) => Promise<void>;
+    /** Must return fresh, protocol-verified signed TXT/ku evidence, not cached pre-rotation evidence. */
+    verifyPublicationEvidence: (domain: string) => Promise<VerifiedDomain>;
+}
+interface RotateManagedOperationalKeyOptions extends ManagedKeyRotationCoordination {
     domain: string;
     /** Exact unindexed c2sp-tlog reference configured for this identity. */
     logReference: string;
     keyProvider: KeyProvider;
+    previousProviderReference: string;
+    /** Omit to rotate within the previous provider. */
+    targetKeyProvider?: KeyProvider;
+    /** Defaults to the previous key's algorithm. Required when changing algorithms. */
+    targetAlgorithm?: 'EdDSA' | 'ES256';
+    newProviderReference: string;
     registryClient: ManagedKeyRotationRegistry;
     idempotencyKey: string;
-    /** Durably persists exact bytes and every subsequent reconciliation state. */
-    persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
-    /** Blocks new application signing and drains in-flight request/directory signing before resolving;
-     * resumes signing only after durable activation. */
-    setApplicationSigningPaused: (paused: boolean) => Promise<void>;
 }
 interface ManagedKeyRotationResult {
     readonly domain: string;
     readonly logReference: string;
     readonly previousKid: string;
     readonly newKid: string;
+    readonly previousProviderReference: string;
+    readonly newProviderReference: string;
+    readonly previousKey: DnsIdJWK;
+    readonly previousThumbprint: string;
+    readonly newThumbprint: string;
+    readonly entryHash: string;
     /**
      * Persist these exact bytes with idempotencyKey while activated is false.
      * Callers must pause new application signing until this rotation is accepted.
@@ -47,12 +65,11 @@ interface ManagedKeyRotationResult {
     readonly activated: boolean;
     readonly applicationSigningPaused: boolean;
 }
-interface ResumeManagedOperationalKeyRotationOptions {
-    keyProvider: KeyProvider;
+interface ResumeManagedOperationalKeyRotationOptions extends ManagedKeyRotationCoordination {
+    /** Resolves durable references, never the current deployment's selected provider. */
+    resolveKeyProvider: (reference: string) => Promise<KeyProvider>;
     registryClient: Pick<ManagedKeyRotationRegistry, 'submitPreparedEvent'>;
     rotation: ManagedKeyRotationResult;
-    persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
-    setApplicationSigningPaused: (paused: boolean) => Promise<void>;
 }
 /** Submission failed after the completed entry bytes were fixed. */
 declare class ManagedKeyRotationSubmissionError extends VerificationError {
@@ -208,4 +225,4 @@ declare function createIdentityManager(config: DnsidConfig, deps: CreateIdentity
  */
 declare function createIdentityVerifier(config: Omit<DnsidConfig, 'identity'>, deps: Omit<CreateIdentityManagerDependencies, 'keyProvider' | 'entityKeyProvider'>): IdentityManager;
 
-export { type CreateIdentityManagerDependencies, type IssueManagedIdentityOptions, ManagedIssuanceActivationError, type ManagedIssuanceCoordination, type ManagedIssuanceRegistry, type ManagedIssuanceState, type ManagedIssuanceSubmission, ManagedIssuanceSubmissionError, ManagedKeyRotationActivationError, type ManagedKeyRotationRegistry, type ManagedKeyRotationResult, ManagedKeyRotationSubmissionError, type ResumeManagedIssuanceOptions, type ResumeManagedOperationalKeyRotationOptions, type RotateManagedOperationalKeyOptions, type SDKConformance, SDK_CONFORMANCE, createIdentityManager, createIdentityVerifier, issueManagedIdentity, resumeManagedIssuance, resumeManagedOperationalKeyRotation, rotateManagedOperationalKey };
+export { type CreateIdentityManagerDependencies, type IssueManagedIdentityOptions, ManagedIssuanceActivationError, type ManagedIssuanceCoordination, type ManagedIssuanceRegistry, type ManagedIssuanceState, type ManagedIssuanceSubmission, ManagedIssuanceSubmissionError, ManagedKeyRotationActivationError, type ManagedKeyRotationCoordination, type ManagedKeyRotationRegistry, type ManagedKeyRotationResult, ManagedKeyRotationSubmissionError, type ResumeManagedIssuanceOptions, type ResumeManagedOperationalKeyRotationOptions, type RotateManagedOperationalKeyOptions, type SDKConformance, SDK_CONFORMANCE, createIdentityManager, createIdentityVerifier, issueManagedIdentity, resumeManagedIssuance, resumeManagedOperationalKeyRotation, rotateManagedOperationalKey };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { VerificationError, KeyProvider, DnsIdJWK, IdentityManagerDependencies, DnsidConfig, IdentityManager } from '@dnsid-ai/protocol';
+import { VerificationError, DnsIdJWK, KeyProvider, VerifiedDomain, IdentityManagerDependencies, DnsidConfig, IdentityManager } from '@dnsid-ai/protocol';
 export * from '@dnsid-ai/protocol';
 export { ArgumentError, DNSID_VERSION, DNSSECMode, DNSSECState, DnsIdTxtRecord, DomainLog, DomainSnapshot, IdentityManager, InMemoryIdentityCache, JWKS, JWKS_MAX_RESPONSE_BYTES, LogRegistry, NoopLogReader, ParseError, SIGNING_ALGS, STATUS_MAX_RESPONSE_BYTES, ValidationError, VerificationCode, VerificationError, VerifiedDomain, activeStatusDocument, fromBase64Url, isDomainName, isTransientVerificationError, jwkSignatureAlg, jwkThumbprint, normalizeFQDN, parseKaDuration, parseKeyId, retryTransientVerification, toArrayBuffer, toBase64Url, validateAgentStatus, verifyWithKey } from '@dnsid-ai/protocol';
 import * as jose from '@dnsid-ai/jose';
@@ -19,24 +19,42 @@ interface ManagedKeyRotationRegistry {
     prepareKeyRotation(domain: string, request: KeyRotationPreparationRequest, idempotencyKey: string): Promise<PreparedRegistryEvent>;
     submitPreparedEvent(domain: string, entryBytes: Uint8Array, idempotencyKey: string): Promise<SubmissionResult>;
 }
-interface RotateManagedOperationalKeyOptions {
+interface ManagedKeyRotationCoordination {
+    /** Durably persists exact bytes and every subsequent reconciliation state. */
+    persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
+    /** Blocks new application signing and drains in-flight request/directory signing before resolving;
+     * resumes signing only after durable activation. */
+    setApplicationSigningPaused: (paused: boolean) => Promise<void>;
+    /** Restores the application signer before signing is resumed. */
+    setApplicationSigner: (provider: KeyProvider, kid: string) => Promise<void>;
+    /** Must return fresh, protocol-verified signed TXT/ku evidence, not cached pre-rotation evidence. */
+    verifyPublicationEvidence: (domain: string) => Promise<VerifiedDomain>;
+}
+interface RotateManagedOperationalKeyOptions extends ManagedKeyRotationCoordination {
     domain: string;
     /** Exact unindexed c2sp-tlog reference configured for this identity. */
     logReference: string;
     keyProvider: KeyProvider;
+    previousProviderReference: string;
+    /** Omit to rotate within the previous provider. */
+    targetKeyProvider?: KeyProvider;
+    /** Defaults to the previous key's algorithm. Required when changing algorithms. */
+    targetAlgorithm?: 'EdDSA' | 'ES256';
+    newProviderReference: string;
     registryClient: ManagedKeyRotationRegistry;
     idempotencyKey: string;
-    /** Durably persists exact bytes and every subsequent reconciliation state. */
-    persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
-    /** Blocks new application signing and drains in-flight request/directory signing before resolving;
-     * resumes signing only after durable activation. */
-    setApplicationSigningPaused: (paused: boolean) => Promise<void>;
 }
 interface ManagedKeyRotationResult {
     readonly domain: string;
     readonly logReference: string;
     readonly previousKid: string;
     readonly newKid: string;
+    readonly previousProviderReference: string;
+    readonly newProviderReference: string;
+    readonly previousKey: DnsIdJWK;
+    readonly previousThumbprint: string;
+    readonly newThumbprint: string;
+    readonly entryHash: string;
     /**
      * Persist these exact bytes with idempotencyKey while activated is false.
      * Callers must pause new application signing until this rotation is accepted.
@@ -47,12 +65,11 @@ interface ManagedKeyRotationResult {
     readonly activated: boolean;
     readonly applicationSigningPaused: boolean;
 }
-interface ResumeManagedOperationalKeyRotationOptions {
-    keyProvider: KeyProvider;
+interface ResumeManagedOperationalKeyRotationOptions extends ManagedKeyRotationCoordination {
+    /** Resolves durable references, never the current deployment's selected provider. */
+    resolveKeyProvider: (reference: string) => Promise<KeyProvider>;
     registryClient: Pick<ManagedKeyRotationRegistry, 'submitPreparedEvent'>;
     rotation: ManagedKeyRotationResult;
-    persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
-    setApplicationSigningPaused: (paused: boolean) => Promise<void>;
 }
 /** Submission failed after the completed entry bytes were fixed. */
 declare class ManagedKeyRotationSubmissionError extends VerificationError {
@@ -208,4 +225,4 @@ declare function createIdentityManager(config: DnsidConfig, deps: CreateIdentity
  */
 declare function createIdentityVerifier(config: Omit<DnsidConfig, 'identity'>, deps: Omit<CreateIdentityManagerDependencies, 'keyProvider' | 'entityKeyProvider'>): IdentityManager;
 
-export { type CreateIdentityManagerDependencies, type IssueManagedIdentityOptions, ManagedIssuanceActivationError, type ManagedIssuanceCoordination, type ManagedIssuanceRegistry, type ManagedIssuanceState, type ManagedIssuanceSubmission, ManagedIssuanceSubmissionError, ManagedKeyRotationActivationError, type ManagedKeyRotationRegistry, type ManagedKeyRotationResult, ManagedKeyRotationSubmissionError, type ResumeManagedIssuanceOptions, type ResumeManagedOperationalKeyRotationOptions, type RotateManagedOperationalKeyOptions, type SDKConformance, SDK_CONFORMANCE, createIdentityManager, createIdentityVerifier, issueManagedIdentity, resumeManagedIssuance, resumeManagedOperationalKeyRotation, rotateManagedOperationalKey };
+export { type CreateIdentityManagerDependencies, type IssueManagedIdentityOptions, ManagedIssuanceActivationError, type ManagedIssuanceCoordination, type ManagedIssuanceRegistry, type ManagedIssuanceState, type ManagedIssuanceSubmission, ManagedIssuanceSubmissionError, ManagedKeyRotationActivationError, type ManagedKeyRotationCoordination, type ManagedKeyRotationRegistry, type ManagedKeyRotationResult, ManagedKeyRotationSubmissionError, type ResumeManagedIssuanceOptions, type ResumeManagedOperationalKeyRotationOptions, type RotateManagedOperationalKeyOptions, type SDKConformance, SDK_CONFORMANCE, createIdentityManager, createIdentityVerifier, issueManagedIdentity, resumeManagedIssuance, resumeManagedOperationalKeyRotation, rotateManagedOperationalKey };

package/dist/index.js

@@ -25,8 +25,8 @@ import {
   ValidationError,
   VerificationError as VerificationError3,
   VerificationCode as VerificationCode3,
-  ArgumentError,
-  normalizeFQDN as normalizeFQDN2,
+  ArgumentError as ArgumentError2,
+  normalizeFQDN as normalizeFQDN3,
   isDomainName,
   parseKeyId,
   toBase64Url,
@@ -55,6 +55,8 @@ import {
 
 // src/managed-key-rotation.ts
 import {
+  ArgumentError,
+  normalizeFQDN,
   JWKS,
   VerificationCode,
   VerificationError,
@@ -84,18 +86,35 @@ var ManagedKeyRotationActivationError = class extends VerificationError {
   }
 };
 async function rotateManagedOperationalKey(options) {
+  assertCoordination(options);
+  const domain = normalizeFQDN(options.domain, true);
+  assertOperationReferences(options.previousProviderReference, options.newProviderReference, options.idempotencyKey);
+  const target = options.targetKeyProvider ?? options.keyProvider;
+  if (target === options.keyProvider !== (options.previousProviderReference === options.newProviderReference)) {
+    throw new ArgumentError("provider references must identify the selected previous and target providers");
+  }
   const previousKey = await options.keyProvider.signingKey();
   new JWKS([previousKey]).validateOperational();
   const previousThumbprint = await jwkThumbprint(previousKey);
-  const newKid = await options.keyProvider.generateKey();
-  const newKey = await options.keyProvider.jwk(newKid);
+  const algorithm = options.targetAlgorithm ?? previousKey.alg;
+  if (algorithm !== "EdDSA" && algorithm !== "ES256") throw new ArgumentError("unsupported target algorithm");
+  if (target.validateKeyGeneration) {
+    await target.validateKeyGeneration(algorithm);
+  } else {
+    const active = await target.signingKey();
+    new JWKS([active]).validateOperational();
+    if (active.alg !== algorithm) throw new ArgumentError("target provider must validate support for the selected algorithm");
+  }
+  const newKid = await target.generateKey(algorithm);
+  const newKey = await target.jwk(newKid);
   new JWKS([newKey]).validateOperational();
+  if (newKey.alg !== algorithm) throw permanentRotationError("generated key does not use the selected algorithm");
   if (await jwkThumbprint(newKey) === previousThumbprint) {
     throw permanentRotationError("managed KEY_ROTATION requires a distinct pending operational key");
   }
   let raw;
   try {
-    raw = await options.registryClient.prepareKeyRotation(options.domain, {
+    raw = await options.registryClient.prepareKeyRotation(domain, {
       previousKeyId: previousThumbprint,
       publicKey: newKey
     }, options.idempotencyKey);
@@ -109,12 +128,12 @@ async function rotateManagedOperationalKey(options) {
   if (raw.logReference !== options.logReference) {
     throw permanentRotationError(`registry preparation returned unexpected log reference ${raw.logReference}`);
   }
-  const context = { expectedFqdn: options.domain, previousOperationalKey: previousKey };
+  const context = { expectedFqdn: domain, previousOperationalKey: previousKey };
   let prepared = await parsePreparedC2spTlogEvent(raw.entryBytes, raw.logReference, context);
   if (prepared.envelope.type !== "KEY_ROTATION") {
     throw permanentRotationError(`registry preparation returned ${String(prepared.envelope.type)} instead of KEY_ROTATION`);
   }
-  if (prepared.envelope.fqdn !== options.domain) {
+  if (prepared.envelope.fqdn !== domain) {
     throw permanentRotationError("registry KEY_ROTATION fqdn does not match the expected identity");
   }
   if (prepared.envelope.prev_thumb !== previousThumbprint) {
@@ -122,40 +141,61 @@ async function rotateManagedOperationalKey(options) {
   }
   await assertPreparedRotationKey(prepared.envelope.new_ku, prepared.envelope.new_thumb, newKey);
   prepared = await signPreparedC2spTlogEvent(prepared, "PreviousOperational", options.keyProvider, context);
-  prepared = await signPreparedC2spTlogEvent(prepared, "NewOperational", options.keyProvider, context);
+  prepared = await signPreparedC2spTlogEvent(prepared, "NewOperational", target, context);
   const entryBytes = await c2spTlogEntryBytes(prepared, context);
   const rotation = {
-    domain: options.domain,
+    domain,
     logReference: options.logReference,
     previousKid: previousKey.kid,
     newKid,
+    previousProviderReference: options.previousProviderReference,
+    newProviderReference: options.newProviderReference,
+    previousKey,
+    previousThumbprint,
+    newThumbprint: await jwkThumbprint(newKey),
+    entryHash: await sha256Hex(entryBytes),
     entryBytes: entryBytes.slice(),
     idempotencyKey: options.idempotencyKey,
     activated: false,
     applicationSigningPaused: true
   };
-  await options.persistRotation(rotation);
-  await options.setApplicationSigningPaused(true);
-  return submitManagedRotation(options.keyProvider, options.registryClient, rotation, options.persistRotation, options.setApplicationSigningPaused);
+  try {
+    await options.persistRotation(rotation);
+    await options.setApplicationSigningPaused(true);
+  } catch (cause) {
+    throw new ManagedKeyRotationSubmissionError("managed rotation persistence or pause failed; resume this state", rotation, true, cause);
+  }
+  return submitManagedRotation(options, options.keyProvider, target, rotation);
 }
 async function resumeManagedOperationalKeyRotation(options) {
-  if (options.rotation.activated) {
-    if (!options.rotation.applicationSigningPaused) return options.rotation;
-    await options.setApplicationSigningPaused(false);
-    const completed = { ...options.rotation, applicationSigningPaused: false };
-    await options.persistRotation(completed);
-    return completed;
-  }
-  if (options.rotation.submission?.state === "rejected") {
-    throw permanentRotationError("cannot resume a rejected managed key rotation");
+  assertCoordination(options);
+  if (typeof options.resolveKeyProvider !== "function") throw new ArgumentError("managed rotation recovery requires resolveKeyProvider");
+  const rotation = options.rotation;
+  try {
+    assertOperationReferences(rotation.previousProviderReference, rotation.newProviderReference, rotation.idempotencyKey);
+    const previous = await options.resolveKeyProvider(rotation.previousProviderReference);
+    const target = rotation.newProviderReference === rotation.previousProviderReference ? previous : await options.resolveKeyProvider(rotation.newProviderReference);
+    await validateSavedRotation(rotation, previous, target);
+    if (rotation.submission?.state === "rejected") {
+      throw new ManagedKeyRotationSubmissionError("cannot resume a rejected managed key rotation", rotation, false);
+    }
+    await options.setApplicationSigningPaused(true);
+    if (rotation.submission?.state === "accepted") {
+      await assertSubmissionMatchesRotation(rotation, rotation.submission);
+      return activateRotation(options, previous, target, rotation);
+    }
+    if (rotation.activated) throw permanentRotationError("activated rotation has no accepted submission");
+    await options.persistRotation(rotation);
+    return submitManagedRotation(options, previous, target, rotation);
+  } catch (cause) {
+    if (cause instanceof ManagedKeyRotationSubmissionError || cause instanceof ManagedKeyRotationActivationError) throw cause;
+    throw new ManagedKeyRotationActivationError("managed rotation recovery failed; signing must remain paused", rotation, cause);
   }
-  await options.setApplicationSigningPaused(true);
-  return submitManagedRotation(options.keyProvider, options.registryClient, options.rotation, options.persistRotation, options.setApplicationSigningPaused);
 }
-async function submitManagedRotation(keyProvider, registryClient, rotation, persistRotation, setApplicationSigningPaused) {
+async function submitManagedRotation(options, previous, target, rotation) {
   let submission;
   try {
-    submission = await registryClient.submitPreparedEvent(rotation.domain, rotation.entryBytes, rotation.idempotencyKey);
+    submission = await options.registryClient.submitPreparedEvent(rotation.domain, rotation.entryBytes, rotation.idempotencyKey);
   } catch (cause) {
     const retryWithSameBytes2 = structuredRetryWithSameBytes(cause);
     throw new ManagedKeyRotationSubmissionError(
@@ -165,9 +205,13 @@ async function submitManagedRotation(keyProvider, registryClient, rotation, pers
       cause
     );
   }
-  await assertSubmissionMatchesRotation(rotation, submission);
   const next = { ...rotation, submission };
-  await persistRotation(next);
+  try {
+    await assertSubmissionMatchesRotation(rotation, submission);
+    await options.persistRotation(next);
+  } catch (cause) {
+    throw new ManagedKeyRotationSubmissionError("managed rotation acceptance binding or persistence failed; resume this state", next, true, cause);
+  }
   if (submission.state === "rejected") {
     throw new ManagedKeyRotationSubmissionError(
       `registry rejected the prepared KEY_ROTATION: ${submission.errorCode ?? "unknown error"}`,
@@ -176,15 +220,24 @@ async function submitManagedRotation(keyProvider, registryClient, rotation, pers
     );
   }
   if (submission.state !== "accepted") return next;
-  let recoverable = next;
+  return activateRotation(options, previous, target, next);
+}
+async function activateRotation(options, previous, target, rotation) {
+  let recoverable = rotation;
   try {
-    await reconcileAcceptedRotation(keyProvider, rotation);
-    const activated = { ...next, activated: true };
-    await persistRotation(activated);
+    await verifyAcceptedPublication(options, rotation);
+    if (!rotation.activated) await reconcileAcceptedRotation(previous, target, rotation);
+    if (previous !== target && await activeKey(previous, await previous.listKeyIds())) {
+      throw permanentRotationError("superseded source provider still has an active signing key");
+    }
+    const activated = { ...rotation, activated: true, applicationSigningPaused: true };
+    await options.persistRotation(activated);
     recoverable = activated;
-    await setApplicationSigningPaused(false);
+    await assertKeyBinding(await target.signingKey(), rotation.newKid, rotation.newThumbprint);
+    await options.setApplicationSigner(target, rotation.newKid);
+    await options.setApplicationSigningPaused(false);
     const completed = { ...activated, applicationSigningPaused: false };
-    await persistRotation(completed);
+    await options.persistRotation(completed);
     return completed;
   } catch (cause) {
     throw new ManagedKeyRotationActivationError(
@@ -194,15 +247,84 @@ async function submitManagedRotation(keyProvider, registryClient, rotation, pers
     );
   }
 }
-async function reconcileAcceptedRotation(keyProvider, rotation) {
-  const activeKid = (await keyProvider.signingKey()).kid;
-  if (activeKid === rotation.previousKid) {
-    await keyProvider.activate(rotation.newKid);
-  } else if (activeKid !== rotation.newKid) {
-    throw permanentRotationError(`unexpected active key ${activeKid} while reconciling managed key rotation`);
+async function reconcileAcceptedRotation(previous, target, rotation) {
+  const active = await target.signingKey();
+  if (active.kid !== rotation.newKid) {
+    if (previous === target) await assertKeyBinding(active, rotation.previousKid, rotation.previousThumbprint);
+    await target.activate(rotation.newKid);
+  }
+  await assertKeyBinding(await target.signingKey(), rotation.newKid, rotation.newThumbprint);
+  if ((await previous.listKeyIds()).includes(rotation.previousKid)) await previous.supersede(rotation.previousKid);
+}
+function assertCoordination(options) {
+  for (const name of ["persistRotation", "setApplicationSigningPaused", "setApplicationSigner", "verifyPublicationEvidence"]) {
+    if (typeof options[name] !== "function") throw new ArgumentError(`managed rotation requires ${name}`);
+  }
+}
+function assertOperationReferences(previous, next, idempotencyKey) {
+  if (!previous?.trim() || !next?.trim() || !idempotencyKey || idempotencyKey.trim() !== idempotencyKey || idempotencyKey.length > 200) {
+    throw permanentRotationError("managed rotation requires provider references and a valid idempotency key");
+  }
+}
+async function assertKeyBinding(key, kid, thumbprint) {
+  new JWKS([key]).validateOperational();
+  if (key.kid !== kid || await jwkThumbprint(key) !== thumbprint) {
+    throw permanentRotationError("saved managed rotation key binding mismatch");
   }
-  if ((await keyProvider.listKeyIds()).includes(rotation.previousKid)) {
-    await keyProvider.supersede(rotation.previousKid);
+}
+async function activeKey(provider, listedIds) {
+  if (provider.activeSigningKey) return provider.activeSigningKey();
+  return listedIds.length ? provider.signingKey() : null;
+}
+async function validateSavedRotation(rotation, previous, target) {
+  assertOperationReferences(rotation.previousProviderReference, rotation.newProviderReference, rotation.idempotencyKey);
+  if (typeof rotation.activated !== "boolean" || typeof rotation.applicationSigningPaused !== "boolean" || normalizeFQDN(rotation.domain, true) !== rotation.domain || await sha256Hex(rotation.entryBytes) !== rotation.entryHash) {
+    throw permanentRotationError("saved managed rotation domain or entry hash mismatch");
+  }
+  await assertKeyBinding(rotation.previousKey, rotation.previousKid, rotation.previousThumbprint);
+  const previousIds = await previous.listKeyIds();
+  const sourceActive = await activeKey(previous, previousIds);
+  if (previousIds.includes(rotation.previousKid)) {
+    await assertKeyBinding(await previous.jwk(rotation.previousKid), rotation.previousKid, rotation.previousThumbprint);
+    if (sourceActive) {
+      const targetIsActive = previous === target && rotation.submission?.state === "accepted" && sourceActive.kid === rotation.newKid;
+      await assertKeyBinding(
+        sourceActive,
+        targetIsActive ? rotation.newKid : rotation.previousKid,
+        targetIsActive ? rotation.newThumbprint : rotation.previousThumbprint
+      );
+    }
+  } else {
+    if (rotation.submission?.state !== "accepted") throw permanentRotationError("saved previous key is unavailable without saved acceptance");
+    await assertSubmissionMatchesRotation(rotation, rotation.submission);
+    await assertKeyBinding(await target.signingKey(), rotation.newKid, rotation.newThumbprint);
+    if (previous !== target && sourceActive) throw permanentRotationError("superseded source provider still has an active signing key");
+  }
+  const next = await target.jwk(rotation.newKid);
+  await assertKeyBinding(next, rotation.newKid, rotation.newThumbprint);
+  const context = { expectedFqdn: rotation.domain, previousOperationalKey: rotation.previousKey };
+  const prepared = await parsePreparedC2spTlogEvent(rotation.entryBytes, rotation.logReference, context);
+  if (prepared.envelope.type !== "KEY_ROTATION" || prepared.envelope.fqdn !== rotation.domain || prepared.envelope.prev_thumb !== rotation.previousThumbprint) {
+    throw permanentRotationError("saved managed rotation event binding mismatch");
+  }
+  await assertPreparedRotationKey(prepared.envelope.new_ku, prepared.envelope.new_thumb, next);
+  await c2spTlogEntryBytes(prepared, context);
+  if (rotation.submission) await assertSubmissionMatchesRotation(rotation, rotation.submission);
+}
+async function verifyAcceptedPublication(options, rotation) {
+  const verified = await options.verifyPublicationEvidence(rotation.domain);
+  if (verified.domain !== rotation.domain || verified.record.lr !== rotation.logReference) {
+    throw permanentRotationError("current signed publication does not match managed rotation");
+  }
+  await assertKeyBinding(verified.jwks.currentOperationalSigningKey(), rotation.newKid, rotation.newThumbprint);
+  const prepared = await parsePreparedC2spTlogEvent(rotation.entryBytes, rotation.logReference, {
+    expectedFqdn: rotation.domain,
+    previousOperationalKey: rotation.previousKey
+  });
+  const signatures = prepared.envelope.sigs;
+  const event = await verified.logReader.readEvent(rotation.submission.logRef);
+  if (event.type !== "KEY_ROTATION" || event.domain !== rotation.domain || event.previousOperationalThumbprint !== rotation.previousThumbprint || event.newOperationalKid !== rotation.newKid || event.newOperationalThumbprint !== rotation.newThumbprint || event.signingKid !== signatures.prev_op.kid || event.sig !== signatures.prev_op.sig || event.newOperationalProof !== signatures.new_op.sig || event.timestamp.getTime() !== prepared.envelope.ts * 1e3) {
+    throw permanentRotationError("accepted managed rotation continuity mismatch");
   }
 }
 async function assertPreparedRotationKey(value, thumbprint, expected) {
@@ -219,12 +341,18 @@ async function assertSubmissionMatchesRotation(rotation, submission) {
   if (rotation.submission?.entryHash && submission.entryHash && rotation.submission.entryHash !== submission.entryHash) {
     throw permanentRotationError("registry reconciled a different entry hash for this managed key rotation");
   }
+  if (submission.entryHash !== void 0 && submission.entryHash !== rotation.entryHash) {
+    throw permanentRotationError("submission entry hash does not match the exact managed key rotation bytes");
+  }
   if (submission.state !== "accepted") return;
   const expectedHash = await sha256Hex(rotation.entryBytes);
   if (submission.entryHash !== expectedHash) {
     throw permanentRotationError("accepted submission entry hash does not match the exact managed key rotation bytes");
   }
-  if (submission.keyId !== void 0 && submission.keyId !== rotation.newKid) {
+  if (submission.logRef !== `${rotation.logReference}@${submission.index}` || !Number.isSafeInteger(submission.index) || submission.index < 0) {
+    throw permanentRotationError("accepted submission log reference does not match managed rotation");
+  }
+  if (submission.keyId !== rotation.newKid) {
     throw permanentRotationError("accepted submission key_id does not match the generated pending key");
   }
 }
@@ -249,7 +377,7 @@ import {
   VerificationCode as VerificationCode2,
   VerificationError as VerificationError2,
   jwkThumbprint as jwkThumbprint2,
-  normalizeFQDN
+  normalizeFQDN as normalizeFQDN2
 } from "@dnsid-ai/protocol";
 import {
   c2spTlogEntryBytes as c2spTlogEntryBytes2,
@@ -279,8 +407,8 @@ var ManagedIssuanceActivationError = class extends VerificationError2 {
   }
 };
 async function issueManagedIdentity(options) {
-  const domain = normalizeFQDN(options.domain, true);
-  const governanceId = normalizeFQDN(options.governanceId, true);
+  const domain = normalizeFQDN2(options.domain, true);
+  const governanceId = normalizeFQDN2(options.governanceId, true);
   if (!options.idempotencyKey || options.idempotencyKey.trim() !== options.idempotencyKey || options.idempotencyKey.length > 200) {
     throw permanentLogError("managed ISSUANCE idempotencyKey must contain 1 to 200 characters without surrounding whitespace");
   }
@@ -549,7 +677,11 @@ var SDK_CONFORMANCE = Object.freeze({
   logBindings: Object.freeze({
     "c2sp-tlog": c2spTlogConformance
   }),
-  knownDeviations: Object.freeze([])
+  knownDeviations: Object.freeze([
+    "Managed cross-provider rotation requires providers that can supersede the previous active key after transfer; built-in LocalKeyProvider and AwsKmsKeyProvider reject active-key supersession.",
+    "AWS KMS and CLI/in-memory key providers do not durably persist rotation key state; restart recovery requires application-managed provider state or a file-backed local key store.",
+    "Account onboarding validates bindings and reports proof readiness, but does not implement named managed creation or establish permanent registration replay claims."
+  ])
 });
 
 // src/index.ts
@@ -560,7 +692,7 @@ function createIdentityVerifier(config, deps) {
   return new IdentityManager(config, deps);
 }
 export {
-  ArgumentError,
+  ArgumentError2 as ArgumentError,
   DEFAULT_REGISTRY_URL,
   DNSID_VERSION2 as DNSID_VERSION,
   DNSSECMode,
@@ -607,7 +739,7 @@ export {
   jose,
   jwkSignatureAlg,
   jwkThumbprint3 as jwkThumbprint,
-  normalizeFQDN2 as normalizeFQDN,
+  normalizeFQDN3 as normalizeFQDN,
   parseKaDuration,
   parseKeyId,
   publishClientControlledRecord,

package/dist/node.cjs

@@ -162,9 +162,14 @@ var LocalKeyProvider = class _LocalKeyProvider {
     const sig = await crypto.subtle.sign(signAlgorithm(key), cryptoKey, toArrayBuffer(payload));
     return new Uint8Array(sig);
   }
-  async generateKey() {
+  async validateKeyGeneration(algorithm) {
+    if (algorithm !== "EdDSA" && algorithm !== "ES256") throw new import_protocol.ArgumentError(`unsupported local key algorithm: ${algorithm}`);
+  }
+  async generateKey(algorithm) {
     return this.mutate(async (next) => {
-      const key = await generateStoredKey(localKeyAlgorithm(next.active));
+      const selected = algorithm ?? localKeyAlgorithm(next.active);
+      await this.validateKeyGeneration(selected);
+      const key = await generateStoredKey(selected);
       next.pending.push(key);
       return key.kid;
     });
@@ -321,6 +326,13 @@ var import_protocol2 = require("@dnsid-ai/protocol");
 async function createNodeIdentityManager(config, deps = {}) {
   const { transport, ...core } = (0, import_protocol2.validateDnsidConfig)(config);
   const { dnsServer, caBundlePath, privateAddressHosts } = transport;
+  validateInjectedTransport(transport, deps);
+  const transportModule = deps.fetchJson && deps.dnsResolver ? null : await loadNodeTransport();
+  const fetchJson = deps.fetchJson ?? ((url, fetchOptions) => transportModule.fetchJson(url, { ...fetchOptions, dnsServer, caBundlePath, privateAddressHosts }));
+  const dnsResolver = deps.dnsResolver ?? transportModule.createDefaultDnsResolver({ dnsServer });
+  return new import_protocol2.IdentityManager(core, { ...deps, dnsResolver, fetchJson });
+}
+function validateInjectedTransport({ dnsServer, caBundlePath, privateAddressHosts }, deps) {
   if (dnsServer !== void 0 && deps.dnsResolver && deps.fetchJson) {
     throw new import_protocol2.ArgumentError("config.transport.dnsServer has no SDK-managed consumer when both dnsResolver and fetchJson are injected");
   }
@@ -330,10 +342,6 @@ async function createNodeIdentityManager(config, deps = {}) {
   if (privateAddressHosts !== void 0 && deps.fetchJson) {
     throw new import_protocol2.ArgumentError("config.transport.privateAddressHosts has no SDK-managed consumer when fetchJson is injected");
   }
-  const transportModule = deps.fetchJson && deps.dnsResolver ? null : await loadNodeTransport();
-  const fetchJson = deps.fetchJson ?? ((url, fetchOptions) => transportModule.fetchJson(url, { ...fetchOptions, dnsServer, caBundlePath, privateAddressHosts }));
-  const dnsResolver = deps.dnsResolver ?? transportModule.createDefaultDnsResolver({ dnsServer });
-  return new import_protocol2.IdentityManager(core, { ...deps, dnsResolver, fetchJson });
 }
 async function createNodeIdentityVerifier(config = {}, deps = {}) {
   return createNodeIdentityManager(config, deps);
@@ -559,7 +567,23 @@ function mergeSection(base, overlay) {
 }
 var MANAGED_DEFAULTS_MS = 10 * 60 * 1e3;
 async function constructIdentityManager(loaded, deps = {}) {
-  (0, import_protocol3.validateDnsidConfig)(loaded.dnsid ?? {});
+  const config = (0, import_protocol3.validateDnsidConfig)(loaded.dnsid ?? {});
+  validateInjectedTransport(config.transport ?? {}, deps);
+  if (!config.identity && (deps.keyProvider || deps.entityKeyProvider)) {
+    throw new import_protocol3.ArgumentError("key providers have no consumer without config.identity");
+  }
+  if (config.identity && !deps.keyProvider) {
+    const source = loaded.keySource;
+    if (source) await validateKeySource(source);
+    if (source?.generation) throw new import_protocol3.ArgumentError("identity-manager construction opens existing keys only; use managed setup for generation");
+    if (!source?.keyRef && !source?.cliDirectory && !source?.keyStorePath) {
+      throw new import_protocol3.ArgumentError("deps.keyProvider or a configured operational key source is required when config.identity is set");
+    }
+  }
+  const entityKeyPath = loaded.dnsid?.identity && !deps.entityKeyProvider ? loaded.keySource?.entityKeyPath : void 0;
+  if (entityKeyPath !== void 0 && (typeof entityKeyPath !== "string" || !entityKeyPath.trim())) {
+    throw new import_protocol3.ArgumentError("keySource.entityKeyPath must be nonempty");
+  }
   const filled = { ...deps };
   if (!filled.logRegistry && loaded.logTrust) {
     filled.logRegistry = await logRegistryFromTrust(loaded.logTrust, loaded.dnsid?.transport);
@@ -621,9 +645,10 @@ async function operationalKeyProvider(source, domain) {
 async function validateKeySource(source = {}) {
   const provider = source.provider ?? "file";
   if (!["file", "aws-kms", "google-kms", "azure-key-vault"].includes(provider)) throw new import_protocol3.ArgumentError(`unknown key provider: ${provider}`);
-  for (const field of ["keyRef", "keyStorePath", "cliDirectory", "entityKeyPath"]) {
+  for (const field of ["keyRef", "keyStorePath", "cliDirectory"]) {
     if (source[field] !== void 0 && (typeof source[field] !== "string" || !source[field].trim())) throw new import_protocol3.ArgumentError(`keySource.${field} must be nonempty`);
   }
+  if (source.settings !== void 0) object(source.settings, "keySource.settings");
   if (source.keyRef && source.generation) throw new import_protocol3.ArgumentError("keyRef and generation are mutually exclusive");
   if ((source.cliDirectory || source.keyStorePath) && (provider !== "file" || source.keyRef || source.generation)) throw new import_protocol3.ArgumentError("CLI/keyStorePath cannot combine with cloud, keyRef, or generation");
   if (source.generation && (typeof source.generation.locator !== "string" || !source.generation.locator.trim() || !["EdDSA", "ES256"].includes(source.generation.algorithm))) throw new import_protocol3.ArgumentError("generation requires a stable locator and supported EdDSA or ES256 algorithm");

package/dist/node.d.cts

@@ -36,7 +36,8 @@ declare class LocalKeyProvider implements KeyProvider {
     sign(payload: Uint8Array): Promise<Uint8Array>;
     signKey(kid: string, payload: Uint8Array): Promise<Uint8Array>;
     private signWithKey;
-    generateKey(): Promise<string>;
+    validateKeyGeneration(algorithm: string): Promise<void>;
+    generateKey(algorithm?: string): Promise<string>;
     activate(kid: string): Promise<void>;
     supersede(kid: string): Promise<void>;
     /** @deprecated Use supersede(). */

package/dist/node.d.ts

@@ -36,7 +36,8 @@ declare class LocalKeyProvider implements KeyProvider {
     sign(payload: Uint8Array): Promise<Uint8Array>;
     signKey(kid: string, payload: Uint8Array): Promise<Uint8Array>;
     private signWithKey;
-    generateKey(): Promise<string>;
+    validateKeyGeneration(algorithm: string): Promise<void>;
+    generateKey(algorithm?: string): Promise<string>;
     activate(kid: string): Promise<void>;
     supersede(kid: string): Promise<void>;
     /** @deprecated Use supersede(). */

package/dist/node.js

@@ -115,9 +115,14 @@ var LocalKeyProvider = class _LocalKeyProvider {
     const sig = await crypto.subtle.sign(signAlgorithm(key), cryptoKey, toArrayBuffer(payload));
     return new Uint8Array(sig);
   }
-  async generateKey() {
+  async validateKeyGeneration(algorithm) {
+    if (algorithm !== "EdDSA" && algorithm !== "ES256") throw new ArgumentError(`unsupported local key algorithm: ${algorithm}`);
+  }
+  async generateKey(algorithm) {
     return this.mutate(async (next) => {
-      const key = await generateStoredKey(localKeyAlgorithm(next.active));
+      const selected = algorithm ?? localKeyAlgorithm(next.active);
+      await this.validateKeyGeneration(selected);
+      const key = await generateStoredKey(selected);
       next.pending.push(key);
       return key.kid;
     });
@@ -274,6 +279,13 @@ import { IdentityManager, ArgumentError as ArgumentError2, validateDnsidConfig }
 async function createNodeIdentityManager(config, deps = {}) {
   const { transport, ...core } = validateDnsidConfig(config);
   const { dnsServer, caBundlePath, privateAddressHosts } = transport;
+  validateInjectedTransport(transport, deps);
+  const transportModule = deps.fetchJson && deps.dnsResolver ? null : await loadNodeTransport();
+  const fetchJson = deps.fetchJson ?? ((url, fetchOptions) => transportModule.fetchJson(url, { ...fetchOptions, dnsServer, caBundlePath, privateAddressHosts }));
+  const dnsResolver = deps.dnsResolver ?? transportModule.createDefaultDnsResolver({ dnsServer });
+  return new IdentityManager(core, { ...deps, dnsResolver, fetchJson });
+}
+function validateInjectedTransport({ dnsServer, caBundlePath, privateAddressHosts }, deps) {
   if (dnsServer !== void 0 && deps.dnsResolver && deps.fetchJson) {
     throw new ArgumentError2("config.transport.dnsServer has no SDK-managed consumer when both dnsResolver and fetchJson are injected");
   }
@@ -283,10 +295,6 @@ async function createNodeIdentityManager(config, deps = {}) {
   if (privateAddressHosts !== void 0 && deps.fetchJson) {
     throw new ArgumentError2("config.transport.privateAddressHosts has no SDK-managed consumer when fetchJson is injected");
   }
-  const transportModule = deps.fetchJson && deps.dnsResolver ? null : await loadNodeTransport();
-  const fetchJson = deps.fetchJson ?? ((url, fetchOptions) => transportModule.fetchJson(url, { ...fetchOptions, dnsServer, caBundlePath, privateAddressHosts }));
-  const dnsResolver = deps.dnsResolver ?? transportModule.createDefaultDnsResolver({ dnsServer });
-  return new IdentityManager(core, { ...deps, dnsResolver, fetchJson });
 }
 async function createNodeIdentityVerifier(config = {}, deps = {}) {
   return createNodeIdentityManager(config, deps);
@@ -523,7 +531,23 @@ function mergeSection(base, overlay) {
 }
 var MANAGED_DEFAULTS_MS = 10 * 60 * 1e3;
 async function constructIdentityManager(loaded, deps = {}) {
-  validateDnsidConfig2(loaded.dnsid ?? {});
+  const config = validateDnsidConfig2(loaded.dnsid ?? {});
+  validateInjectedTransport(config.transport ?? {}, deps);
+  if (!config.identity && (deps.keyProvider || deps.entityKeyProvider)) {
+    throw new ArgumentError3("key providers have no consumer without config.identity");
+  }
+  if (config.identity && !deps.keyProvider) {
+    const source = loaded.keySource;
+    if (source) await validateKeySource(source);
+    if (source?.generation) throw new ArgumentError3("identity-manager construction opens existing keys only; use managed setup for generation");
+    if (!source?.keyRef && !source?.cliDirectory && !source?.keyStorePath) {
+      throw new ArgumentError3("deps.keyProvider or a configured operational key source is required when config.identity is set");
+    }
+  }
+  const entityKeyPath = loaded.dnsid?.identity && !deps.entityKeyProvider ? loaded.keySource?.entityKeyPath : void 0;
+  if (entityKeyPath !== void 0 && (typeof entityKeyPath !== "string" || !entityKeyPath.trim())) {
+    throw new ArgumentError3("keySource.entityKeyPath must be nonempty");
+  }
   const filled = { ...deps };
   if (!filled.logRegistry && loaded.logTrust) {
     filled.logRegistry = await logRegistryFromTrust(loaded.logTrust, loaded.dnsid?.transport);
@@ -585,9 +609,10 @@ async function operationalKeyProvider(source, domain) {
 async function validateKeySource(source = {}) {
   const provider = source.provider ?? "file";
   if (!["file", "aws-kms", "google-kms", "azure-key-vault"].includes(provider)) throw new ArgumentError3(`unknown key provider: ${provider}`);
-  for (const field of ["keyRef", "keyStorePath", "cliDirectory", "entityKeyPath"]) {
+  for (const field of ["keyRef", "keyStorePath", "cliDirectory"]) {
     if (source[field] !== void 0 && (typeof source[field] !== "string" || !source[field].trim())) throw new ArgumentError3(`keySource.${field} must be nonempty`);
   }
+  if (source.settings !== void 0) object(source.settings, "keySource.settings");
   if (source.keyRef && source.generation) throw new ArgumentError3("keyRef and generation are mutually exclusive");
   if ((source.cliDirectory || source.keyStorePath) && (provider !== "file" || source.keyRef || source.generation)) throw new ArgumentError3("CLI/keyStorePath cannot combine with cloud, keyRef, or generation");
   if (source.generation && (typeof source.generation.locator !== "string" || !source.generation.locator.trim() || !["EdDSA", "ES256"].includes(source.generation.algorithm))) throw new ArgumentError3("generation requires a stable locator and supported EdDSA or ES256 algorithm");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dnsid-ai/sdk",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Runtime-neutral DNSid SDK entrypoint with optional Node.js convenience helpers.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -39,16 +39,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@dnsid-ai/protocol": "^0.29.0",
-    "@dnsid-ai/http-signatures": "^0.29.0",
-    "@dnsid-ai/jose": "^0.29.0",
-    "@dnsid-ai/log-c2sp-tlog": "^0.29.0",
-    "@dnsid-ai/registry": "^0.29.0",
-    "@dnsid-ai/web-bot-auth": "^0.29.0"
+    "@dnsid-ai/protocol": "^0.31.0",
+    "@dnsid-ai/http-signatures": "^0.31.0",
+    "@dnsid-ai/jose": "^0.31.0",
+    "@dnsid-ai/log-c2sp-tlog": "^0.31.0",
+    "@dnsid-ai/registry": "^0.31.0",
+    "@dnsid-ai/web-bot-auth": "^0.31.0"
   },
   "peerDependencies": {
-    "@dnsid-ai/key-aws": "^0.29.0",
-    "@dnsid-ai/transport": "^0.29.0"
+    "@dnsid-ai/key-aws": "^0.31.0",
+    "@dnsid-ai/transport": "^0.31.0"
   },
   "peerDependenciesMeta": {
     "@dnsid-ai/key-aws": {