@dnsid-ai/sdk 0.25.0 → 0.26.0

package/README.md

@@ -124,6 +124,31 @@ The CLI loader maps persisted fields as written: a missing `status_url` or `log_
 
 DNSSEC modes are: `auto` (default), which rejects `FAILED` and permits `VALID`, `UNSIGNED`, or `UNKNOWN`; `validated`, which permits `VALID` or `UNSIGNED`; and `required`, which permits only `VALID`.
 
+## Registration and provider groundwork
+
+Deployment files support `registration.organizationId`, optional `governanceId`, and an
+independently selected `entityKeyUrl`. These are setup expectations, not registry-root selectors
+or counterparty acceptance defaults. `RegistryClient.getOrganizationOnboarding()` reads the
+existing authenticated endpoint and exposes organization/GI proof and delegation readiness;
+it does not supply an entity-JWKS URL or establish trust.
+
+`keySource` selects file custody or an optional existing AWS KMS key using `provider`, `keyRef`,
+and non-secret `settings` (`region` and EdDSA/ES256 `algorithm`). Injected providers win, and
+only the selected factory is loaded. AWS authentication uses ambient credential chains, not
+secrets in deployment files. Unavailable factories or invalid settings fail without file fallback.
+Ordinary manager construction opens existing keys only; generation requires workflow coordination.
+Configuration-selected file and AWS keys must match the current operational key of the verified published
+identity, including key ID, algorithm, and public material. Missing publication or unavailable
+verification fails construction. Initial setup supplies an injected provider and owns its binding
+checks. Selecting local files emits a production-safety warning.
+Google KMS and Azure factories are unavailable in this binding.
+
+This groundwork does not expose automatic managed registration or named recovery. Those require
+a separate SDK workflow and verified permanent server replay/name claims; the existing expiring
+store is insufficient. Existing low-level registration remains available without assuming those
+server capabilities. Moving custody to another provider requires authorized, publicly verified
+rotation, not configuration alone.
+
 ## Included surfaces
 
 `@dnsid-ai/sdk` re-exports the common core and profile surfaces and namespaces:

package/dist/node.cjs

@@ -386,9 +386,9 @@ async function loadEnvironment(env = process.env) {
 }
 async function loadFile(filePath) {
   const root = jsonObject(await fs3.readFile(filePath), filePath);
-  rejectUnknown(root, filePath, ["dnsid", "logTrust", "registry"]);
+  rejectUnknown(root, filePath, ["dnsid", "logTrust", "registry", "registration", "keySource"]);
   const loaded = {};
-  if (root.dnsid !== void 0) loaded.dnsid = loadedDnsid(root.dnsid, `${filePath}: dnsid`);
+  if (root.dnsid !== void 0) loaded.dnsid = validateLoadedDnsidConfig(root.dnsid, `${filePath}: dnsid`);
   if (root.logTrust !== void 0) {
     const trust = object(root.logTrust, `${filePath}: logTrust`);
     rejectUnknown(trust, `${filePath}: logTrust`, ["managed", "profile", "policyUrl"]);
@@ -403,9 +403,32 @@ async function loadFile(filePath) {
     rejectUnknown(registry, `${filePath}: registry`, ["registryUrl"]);
     loaded.registry = compact({ registryUrl: optional(registry, "registryUrl", "string", `${filePath}: registry`) });
   }
+  if (root.registration !== void 0) {
+    const registration = object(root.registration, `${filePath}: registration`);
+    rejectUnknown(registration, `${filePath}: registration`, ["organizationId", "governanceId", "entityKeyUrl"]);
+    loaded.registration = compact({
+      organizationId: optional(registration, "organizationId", "string", `${filePath}: registration`),
+      governanceId: optional(registration, "governanceId", "string", `${filePath}: registration`),
+      entityKeyUrl: optional(registration, "entityKeyUrl", "string", `${filePath}: registration`)
+    });
+  }
+  if (root.keySource !== void 0) {
+    const source = object(root.keySource, `${filePath}: keySource`);
+    rejectUnknown(source, "keySource", ["provider", "keyRef", "generation", "settings", "cliDirectory", "keyStorePath", "entityKeyPath"]);
+    for (const field of ["provider", "keyRef", "cliDirectory", "keyStorePath", "entityKeyPath"]) optional(source, field, "string", "keySource");
+    if (source.settings !== void 0) object(source.settings, "keySource.settings");
+    if (source.generation !== void 0) {
+      const generation = object(source.generation, "keySource.generation");
+      rejectUnknown(generation, "keySource.generation", ["locator", "algorithm"]);
+      for (const field of ["locator", "algorithm"]) {
+        if (typeof generation[field] !== "string") throw new import_protocol3.ArgumentError(`keySource.generation.${field} must be a string`);
+      }
+    }
+    loaded.keySource = source;
+  }
   return loaded;
 }
-function loadedDnsid(value, source) {
+function validateLoadedDnsidConfig(value, source = "dnsid") {
   const raw = object(value, source);
   rejectUnknown(raw, source, ["identity", "verification", "transport"]);
   if (raw.identity !== void 0) {
@@ -494,9 +517,15 @@ function mergeLoadedConfig(base, overlay) {
     dnsid: mergeDnsid(base.dnsid, overlay.dnsid),
     logTrust: overlay.logTrust ?? base.logTrust,
     registry: mergeSection(base.registry, overlay.registry),
-    keySource: mergeSection(base.keySource, overlay.keySource)
+    registration: mergeSection(base.registration, overlay.registration),
+    keySource: mergeKeySource(base.keySource, overlay.keySource)
   });
 }
+function mergeKeySource(base, overlay) {
+  if (!overlay) return base;
+  const replacesOperational = ["provider", "keyRef", "generation", "settings", "cliDirectory", "keyStorePath"].some((field) => overlay[field] !== void 0);
+  return mergeSection(replacesOperational ? compact({ entityKeyPath: base?.entityKeyPath }) : base, overlay);
+}
 function mergeDnsid(base, overlay) {
   if (!base || !overlay) return overlay ?? base;
   return compact({
@@ -523,7 +552,16 @@ async function constructIdentityManager(loaded, deps = {}) {
       filled.entityKeyProvider = await LocalKeyProvider.fromFile(loaded.keySource.entityKeyPath);
     }
   }
-  return createNodeIdentityManager(loaded.dnsid ?? {}, filled);
+  const manager = await createNodeIdentityManager(loaded.dnsid ?? {}, filled);
+  if (identity && !deps.keyProvider && filled.keyProvider) {
+    const verified = await manager.verifyPublicationEvidence(manager.config.identity.domain);
+    const selected = await filled.keyProvider.signingKey();
+    const published = verified.jwks.currentOperationalSigningKey();
+    if (selected.kid !== published.kid || selected.alg !== published.alg || await (0, import_protocol3.jwkThumbprint)(selected) !== await (0, import_protocol3.jwkThumbprint)(published)) {
+      throw new import_protocol3.ArgumentError("configured operational key does not match the verified identity; use authorized key rotation");
+    }
+  }
+  return manager;
 }
 async function logRegistryFromTrust(trust, transport) {
   const variants = ["managed", "profile", "policyDocument", "policyUrl"].filter((k) => trust[k] !== void 0);
@@ -545,12 +583,46 @@ async function logRegistryFromTrust(trust, transport) {
   });
 }
 async function operationalKeyProvider(source, domain) {
+  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.provider === "aws-kms") {
+    const { createAwsKmsKeyProvider } = await import("@dnsid-ai/key-aws");
+    return createAwsKmsKeyProvider(source.keyRef, source.settings);
+  }
+  if (source.keyRef !== void 0 || source.cliDirectory !== void 0 || source.keyStorePath !== void 0) {
+    console.warn("Local private-key files are unsuitable for production. Configure keySource.provider/keyRef for cloud custody.");
+  }
+  if (source.keyRef !== void 0) return LocalKeyProvider.load(source.keyRef);
   if (source.cliDirectory !== void 0) {
     return LocalKeyProvider.fromDirectory(await identityKeyDir(source.cliDirectory, domain));
   }
   if (source.keyStorePath !== void 0) return LocalKeyProvider.load(source.keyStorePath);
   return void 0;
 }
+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"]) {
+    if (source[field] !== void 0 && (typeof source[field] !== "string" || !source[field].trim())) throw new import_protocol3.ArgumentError(`keySource.${field} must be nonempty`);
+  }
+  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");
+  if (provider === "file") {
+    if (source.settings && Object.keys(source.settings).length) throw new import_protocol3.ArgumentError("file provider has no settings");
+    return;
+  }
+  if (provider !== "aws-kms") throw new import_protocol3.ArgumentError(`${provider} is unavailable; install/link a supported provider package (Google KMS and Azure factories are not implemented)`);
+  if (!source.keyRef || source.generation) throw new import_protocol3.ArgumentError("AWS KMS requires an existing keyRef; atomic generation discovery is not supported");
+  try {
+    const factory = await import("@dnsid-ai/key-aws");
+    if (typeof factory.createAwsKmsKeyProvider !== "function" || typeof factory.validateAwsKmsSettings !== "function") throw new Error("provider factory unavailable");
+    factory.validateAwsKmsSettings(source.settings);
+  } catch (cause) {
+    if (cause instanceof import_protocol3.ArgumentError) throw cause;
+    throw new import_protocol3.ArgumentError("aws-kms unavailable; install a compatible @dnsid-ai/key-aws and include it in the build");
+  }
+}
 async function identityKeyDir(dnsidDir, domain) {
   for (const filename of ["private.jwk", "private.pem"]) {
     try {
@@ -571,10 +643,10 @@ function createNodeIdentityManagerFromDnsid(dnsidDir, overlay, deps) {
 function createNodeIdentityManagerFromFile(filePath, overlay, deps) {
   return loadFile(filePath).then((loaded) => constructIdentityManager(mergeLoadedConfig(loaded, top({ dnsid: overlay })), deps));
 }
-async function createRegistryClientFromEnvironment(env) {
+async function createRegistryClientFromEnvironment(env, options = {}) {
   const source = env ?? process.env;
   const loaded = await loadEnvironment(source);
-  return new import_registry.RegistryClient(compact({ baseUrl: loaded.registry?.registryUrl, token: source.DNSID_API_KEY?.trim() || void 0 }));
+  return new import_registry.RegistryClient({ baseUrl: loaded.registry?.registryUrl, token: source.DNSID_API_KEY?.trim() || void 0, ...options });
 }
 function definedEntries(value) {
   return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));

package/dist/node.d.cts

@@ -1,7 +1,7 @@
 export { CreateIdentityManagerDependencies } from './index.cjs';
 import * as _dnsid_ai_protocol from '@dnsid-ai/protocol';
 import { KeyProvider, DnsIdJWK, DnsidConfig, IdentityManagerDependencies, IdentityManager, IdentityConfig } from '@dnsid-ai/protocol';
-import { RegistryClient } from '@dnsid-ai/registry';
+import { RegistryClientOptions, RegistryClient } from '@dnsid-ai/registry';
 import '@dnsid-ai/jose';
 import '@dnsid-ai/http-signatures';
 import '@dnsid-ai/web-bot-auth';
@@ -76,6 +76,15 @@ interface LogTrust {
     policyUrl?: string;
 }
 interface KeySource {
+    provider?: 'file' | 'aws-kms' | 'google-kms' | 'azure-key-vault';
+    /** Existing stable key reference; never combined with generation. */
+    keyRef?: string;
+    /** File generation locator; cloud factories without atomic discovery require keyRef. */
+    generation?: {
+        locator: string;
+        algorithm: string;
+    };
+    settings?: Record<string, unknown>;
     /** DNSid CLI identity directory; key files are located under the effective identity domain. */
     cliDirectory?: string;
     /** Accountable-entity private JWK file. */
@@ -83,6 +92,11 @@ interface KeySource {
     /** `LocalKeyProvider` key-store file; used only when `cliDirectory` is absent. */
     keyStorePath?: string;
 }
+interface ManagedRegistrationConfig {
+    organizationId?: string;
+    governanceId?: string;
+    entityKeyUrl: string;
+}
 interface LoadedRegistryConfig {
     registryUrl?: string;
 }
@@ -95,12 +109,14 @@ interface LoadedConfig {
     dnsid?: LoadedDnsidConfig;
     logTrust?: LogTrust;
     registry?: LoadedRegistryConfig;
+    /** Setup expectations only; never identity or counterparty acceptance defaults. */
+    registration?: Partial<ManagedRegistrationConfig>;
     keySource?: KeySource;
 }
 /** Reads configuration from `DNSID_*`. Secrets such as `DNSID_API_KEY` stay out of `LoadedConfig`. */
 declare function loadEnvironment(env?: EnvironmentSource): Promise<LoadedConfig>;
 /**
- * Reads a JSON deployment file: `{ dnsid?, logTrust?, registry? }`. Unknown members, mistyped
+ * Reads a JSON deployment file: `{ dnsid?, logTrust?, registry?, registration? }`. Unknown members, mistyped
  * values, and duplicate members are rejected; semantic `dnsid` validation stays with the constructor.
  */
 declare function loadFile(filePath: string): Promise<LoadedConfig>;
@@ -113,18 +129,21 @@ declare function loadFile(filePath: string): Promise<LoadedConfig>;
 declare function loadCliDirectory(dnsidDir?: string): Promise<LoadedConfig>;
 /**
  * Field-wise merge; presence wins, not truthiness. Lists replace. `logTrust` is replaced as a
- * whole section when `overlay` sets any variant.
+ * whole section when `overlay` sets any variant. Operational key-source fields replace together;
+ * `entityKeyPath` merges independently.
  */
 declare function mergeLoadedConfig(base: LoadedConfig, overlay: LoadedConfig): LoadedConfig;
 /**
  * Fills `deps.logRegistry` from `logTrust` and key providers from `keySource` only when the caller
  * did not supply them, then calls {@link createNodeIdentityManager}. Adds no configuration values.
+ * Configuration-selected operational keys must match verified local publication before return.
+ * Initial setup injects its provider and owns its binding checks; missing publication fails closed.
  */
 declare function constructIdentityManager(loaded: LoadedConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
 declare function createNodeIdentityManagerFromEnvironment(env?: EnvironmentSource, overlay?: LoadedDnsidConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
 declare function createNodeIdentityManagerFromDnsid(dnsidDir?: string, overlay?: LoadedDnsidConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
 declare function createNodeIdentityManagerFromFile(filePath: string, overlay?: LoadedDnsidConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
-/** `RegistryClient` from `DNSID_REGISTRY_URL` and `DNSID_API_KEY`; the constructor defaults to the local registry. */
-declare function createRegistryClientFromEnvironment(env?: EnvironmentSource): Promise<RegistryClient>;
+/** `RegistryClient` from `DNSID_REGISTRY_URL` and `DNSID_API_KEY`; explicit options win, including transport overrides. The constructor defaults to the local registry. */
+declare function createRegistryClientFromEnvironment(env?: EnvironmentSource, options?: RegistryClientOptions): Promise<RegistryClient>;
 
-export { type EnvironmentSource, type KeySource, type LoadedConfig, type LoadedDnsidConfig, type LoadedRegistryConfig, type LocalKeyAlgorithm, LocalKeyProvider, type LogTrust, constructIdentityManager, createNodeIdentityManager, createNodeIdentityManagerFromDnsid, createNodeIdentityManagerFromEnvironment, createNodeIdentityManagerFromFile, createNodeIdentityVerifier, createRegistryClientFromEnvironment, loadCliDirectory, loadEnvironment, loadFile, mergeLoadedConfig };
+export { type EnvironmentSource, type KeySource, type LoadedConfig, type LoadedDnsidConfig, type LoadedRegistryConfig, type LocalKeyAlgorithm, LocalKeyProvider, type LogTrust, type ManagedRegistrationConfig, constructIdentityManager, createNodeIdentityManager, createNodeIdentityManagerFromDnsid, createNodeIdentityManagerFromEnvironment, createNodeIdentityManagerFromFile, createNodeIdentityVerifier, createRegistryClientFromEnvironment, loadCliDirectory, loadEnvironment, loadFile, mergeLoadedConfig };

package/dist/node.d.ts

@@ -1,7 +1,7 @@
 export { CreateIdentityManagerDependencies } from './index.js';
 import * as _dnsid_ai_protocol from '@dnsid-ai/protocol';
 import { KeyProvider, DnsIdJWK, DnsidConfig, IdentityManagerDependencies, IdentityManager, IdentityConfig } from '@dnsid-ai/protocol';
-import { RegistryClient } from '@dnsid-ai/registry';
+import { RegistryClientOptions, RegistryClient } from '@dnsid-ai/registry';
 import '@dnsid-ai/jose';
 import '@dnsid-ai/http-signatures';
 import '@dnsid-ai/web-bot-auth';
@@ -76,6 +76,15 @@ interface LogTrust {
     policyUrl?: string;
 }
 interface KeySource {
+    provider?: 'file' | 'aws-kms' | 'google-kms' | 'azure-key-vault';
+    /** Existing stable key reference; never combined with generation. */
+    keyRef?: string;
+    /** File generation locator; cloud factories without atomic discovery require keyRef. */
+    generation?: {
+        locator: string;
+        algorithm: string;
+    };
+    settings?: Record<string, unknown>;
     /** DNSid CLI identity directory; key files are located under the effective identity domain. */
     cliDirectory?: string;
     /** Accountable-entity private JWK file. */
@@ -83,6 +92,11 @@ interface KeySource {
     /** `LocalKeyProvider` key-store file; used only when `cliDirectory` is absent. */
     keyStorePath?: string;
 }
+interface ManagedRegistrationConfig {
+    organizationId?: string;
+    governanceId?: string;
+    entityKeyUrl: string;
+}
 interface LoadedRegistryConfig {
     registryUrl?: string;
 }
@@ -95,12 +109,14 @@ interface LoadedConfig {
     dnsid?: LoadedDnsidConfig;
     logTrust?: LogTrust;
     registry?: LoadedRegistryConfig;
+    /** Setup expectations only; never identity or counterparty acceptance defaults. */
+    registration?: Partial<ManagedRegistrationConfig>;
     keySource?: KeySource;
 }
 /** Reads configuration from `DNSID_*`. Secrets such as `DNSID_API_KEY` stay out of `LoadedConfig`. */
 declare function loadEnvironment(env?: EnvironmentSource): Promise<LoadedConfig>;
 /**
- * Reads a JSON deployment file: `{ dnsid?, logTrust?, registry? }`. Unknown members, mistyped
+ * Reads a JSON deployment file: `{ dnsid?, logTrust?, registry?, registration? }`. Unknown members, mistyped
  * values, and duplicate members are rejected; semantic `dnsid` validation stays with the constructor.
  */
 declare function loadFile(filePath: string): Promise<LoadedConfig>;
@@ -113,18 +129,21 @@ declare function loadFile(filePath: string): Promise<LoadedConfig>;
 declare function loadCliDirectory(dnsidDir?: string): Promise<LoadedConfig>;
 /**
  * Field-wise merge; presence wins, not truthiness. Lists replace. `logTrust` is replaced as a
- * whole section when `overlay` sets any variant.
+ * whole section when `overlay` sets any variant. Operational key-source fields replace together;
+ * `entityKeyPath` merges independently.
  */
 declare function mergeLoadedConfig(base: LoadedConfig, overlay: LoadedConfig): LoadedConfig;
 /**
  * Fills `deps.logRegistry` from `logTrust` and key providers from `keySource` only when the caller
  * did not supply them, then calls {@link createNodeIdentityManager}. Adds no configuration values.
+ * Configuration-selected operational keys must match verified local publication before return.
+ * Initial setup injects its provider and owns its binding checks; missing publication fails closed.
  */
 declare function constructIdentityManager(loaded: LoadedConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
 declare function createNodeIdentityManagerFromEnvironment(env?: EnvironmentSource, overlay?: LoadedDnsidConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
 declare function createNodeIdentityManagerFromDnsid(dnsidDir?: string, overlay?: LoadedDnsidConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
 declare function createNodeIdentityManagerFromFile(filePath: string, overlay?: LoadedDnsidConfig, deps?: IdentityManagerDependencies): Promise<_dnsid_ai_protocol.IdentityManager>;
-/** `RegistryClient` from `DNSID_REGISTRY_URL` and `DNSID_API_KEY`; the constructor defaults to the local registry. */
-declare function createRegistryClientFromEnvironment(env?: EnvironmentSource): Promise<RegistryClient>;
+/** `RegistryClient` from `DNSID_REGISTRY_URL` and `DNSID_API_KEY`; explicit options win, including transport overrides. The constructor defaults to the local registry. */
+declare function createRegistryClientFromEnvironment(env?: EnvironmentSource, options?: RegistryClientOptions): Promise<RegistryClient>;
 
-export { type EnvironmentSource, type KeySource, type LoadedConfig, type LoadedDnsidConfig, type LoadedRegistryConfig, type LocalKeyAlgorithm, LocalKeyProvider, type LogTrust, constructIdentityManager, createNodeIdentityManager, createNodeIdentityManagerFromDnsid, createNodeIdentityManagerFromEnvironment, createNodeIdentityManagerFromFile, createNodeIdentityVerifier, createRegistryClientFromEnvironment, loadCliDirectory, loadEnvironment, loadFile, mergeLoadedConfig };
+export { type EnvironmentSource, type KeySource, type LoadedConfig, type LoadedDnsidConfig, type LoadedRegistryConfig, type LocalKeyAlgorithm, LocalKeyProvider, type LogTrust, type ManagedRegistrationConfig, constructIdentityManager, createNodeIdentityManager, createNodeIdentityManagerFromDnsid, createNodeIdentityManagerFromEnvironment, createNodeIdentityManagerFromFile, createNodeIdentityVerifier, createRegistryClientFromEnvironment, loadCliDirectory, loadEnvironment, loadFile, mergeLoadedConfig };

package/dist/node.js

@@ -292,6 +292,7 @@ import {
   ArgumentError as ArgumentError3,
   DNSSECMode,
   normalizeFQDN as normalizeFQDN2,
+  jwkThumbprint as jwkThumbprint2,
   parseJsonNoDuplicateMembers,
   validateDnsidConfig as validateDnsidConfig2
 } from "@dnsid-ai/protocol";
@@ -349,9 +350,9 @@ async function loadEnvironment(env = process.env) {
 }
 async function loadFile(filePath) {
   const root = jsonObject(await fs3.readFile(filePath), filePath);
-  rejectUnknown(root, filePath, ["dnsid", "logTrust", "registry"]);
+  rejectUnknown(root, filePath, ["dnsid", "logTrust", "registry", "registration", "keySource"]);
   const loaded = {};
-  if (root.dnsid !== void 0) loaded.dnsid = loadedDnsid(root.dnsid, `${filePath}: dnsid`);
+  if (root.dnsid !== void 0) loaded.dnsid = validateLoadedDnsidConfig(root.dnsid, `${filePath}: dnsid`);
   if (root.logTrust !== void 0) {
     const trust = object(root.logTrust, `${filePath}: logTrust`);
     rejectUnknown(trust, `${filePath}: logTrust`, ["managed", "profile", "policyUrl"]);
@@ -366,9 +367,32 @@ async function loadFile(filePath) {
     rejectUnknown(registry, `${filePath}: registry`, ["registryUrl"]);
     loaded.registry = compact({ registryUrl: optional(registry, "registryUrl", "string", `${filePath}: registry`) });
   }
+  if (root.registration !== void 0) {
+    const registration = object(root.registration, `${filePath}: registration`);
+    rejectUnknown(registration, `${filePath}: registration`, ["organizationId", "governanceId", "entityKeyUrl"]);
+    loaded.registration = compact({
+      organizationId: optional(registration, "organizationId", "string", `${filePath}: registration`),
+      governanceId: optional(registration, "governanceId", "string", `${filePath}: registration`),
+      entityKeyUrl: optional(registration, "entityKeyUrl", "string", `${filePath}: registration`)
+    });
+  }
+  if (root.keySource !== void 0) {
+    const source = object(root.keySource, `${filePath}: keySource`);
+    rejectUnknown(source, "keySource", ["provider", "keyRef", "generation", "settings", "cliDirectory", "keyStorePath", "entityKeyPath"]);
+    for (const field of ["provider", "keyRef", "cliDirectory", "keyStorePath", "entityKeyPath"]) optional(source, field, "string", "keySource");
+    if (source.settings !== void 0) object(source.settings, "keySource.settings");
+    if (source.generation !== void 0) {
+      const generation = object(source.generation, "keySource.generation");
+      rejectUnknown(generation, "keySource.generation", ["locator", "algorithm"]);
+      for (const field of ["locator", "algorithm"]) {
+        if (typeof generation[field] !== "string") throw new ArgumentError3(`keySource.generation.${field} must be a string`);
+      }
+    }
+    loaded.keySource = source;
+  }
   return loaded;
 }
-function loadedDnsid(value, source) {
+function validateLoadedDnsidConfig(value, source = "dnsid") {
   const raw = object(value, source);
   rejectUnknown(raw, source, ["identity", "verification", "transport"]);
   if (raw.identity !== void 0) {
@@ -457,9 +481,15 @@ function mergeLoadedConfig(base, overlay) {
     dnsid: mergeDnsid(base.dnsid, overlay.dnsid),
     logTrust: overlay.logTrust ?? base.logTrust,
     registry: mergeSection(base.registry, overlay.registry),
-    keySource: mergeSection(base.keySource, overlay.keySource)
+    registration: mergeSection(base.registration, overlay.registration),
+    keySource: mergeKeySource(base.keySource, overlay.keySource)
   });
 }
+function mergeKeySource(base, overlay) {
+  if (!overlay) return base;
+  const replacesOperational = ["provider", "keyRef", "generation", "settings", "cliDirectory", "keyStorePath"].some((field) => overlay[field] !== void 0);
+  return mergeSection(replacesOperational ? compact({ entityKeyPath: base?.entityKeyPath }) : base, overlay);
+}
 function mergeDnsid(base, overlay) {
   if (!base || !overlay) return overlay ?? base;
   return compact({
@@ -486,7 +516,16 @@ async function constructIdentityManager(loaded, deps = {}) {
       filled.entityKeyProvider = await LocalKeyProvider.fromFile(loaded.keySource.entityKeyPath);
     }
   }
-  return createNodeIdentityManager(loaded.dnsid ?? {}, filled);
+  const manager = await createNodeIdentityManager(loaded.dnsid ?? {}, filled);
+  if (identity && !deps.keyProvider && filled.keyProvider) {
+    const verified = await manager.verifyPublicationEvidence(manager.config.identity.domain);
+    const selected = await filled.keyProvider.signingKey();
+    const published = verified.jwks.currentOperationalSigningKey();
+    if (selected.kid !== published.kid || selected.alg !== published.alg || await jwkThumbprint2(selected) !== await jwkThumbprint2(published)) {
+      throw new ArgumentError3("configured operational key does not match the verified identity; use authorized key rotation");
+    }
+  }
+  return manager;
 }
 async function logRegistryFromTrust(trust, transport) {
   const variants = ["managed", "profile", "policyDocument", "policyUrl"].filter((k) => trust[k] !== void 0);
@@ -508,12 +547,46 @@ async function logRegistryFromTrust(trust, transport) {
   });
 }
 async function operationalKeyProvider(source, domain) {
+  await validateKeySource(source);
+  if (source.generation) throw new ArgumentError3("identity-manager construction opens existing keys only; use managed setup for generation");
+  if (source.provider === "aws-kms") {
+    const { createAwsKmsKeyProvider } = await import("@dnsid-ai/key-aws");
+    return createAwsKmsKeyProvider(source.keyRef, source.settings);
+  }
+  if (source.keyRef !== void 0 || source.cliDirectory !== void 0 || source.keyStorePath !== void 0) {
+    console.warn("Local private-key files are unsuitable for production. Configure keySource.provider/keyRef for cloud custody.");
+  }
+  if (source.keyRef !== void 0) return LocalKeyProvider.load(source.keyRef);
   if (source.cliDirectory !== void 0) {
     return LocalKeyProvider.fromDirectory(await identityKeyDir(source.cliDirectory, domain));
   }
   if (source.keyStorePath !== void 0) return LocalKeyProvider.load(source.keyStorePath);
   return void 0;
 }
+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"]) {
+    if (source[field] !== void 0 && (typeof source[field] !== "string" || !source[field].trim())) throw new ArgumentError3(`keySource.${field} must be nonempty`);
+  }
+  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");
+  if (provider === "file") {
+    if (source.settings && Object.keys(source.settings).length) throw new ArgumentError3("file provider has no settings");
+    return;
+  }
+  if (provider !== "aws-kms") throw new ArgumentError3(`${provider} is unavailable; install/link a supported provider package (Google KMS and Azure factories are not implemented)`);
+  if (!source.keyRef || source.generation) throw new ArgumentError3("AWS KMS requires an existing keyRef; atomic generation discovery is not supported");
+  try {
+    const factory = await import("@dnsid-ai/key-aws");
+    if (typeof factory.createAwsKmsKeyProvider !== "function" || typeof factory.validateAwsKmsSettings !== "function") throw new Error("provider factory unavailable");
+    factory.validateAwsKmsSettings(source.settings);
+  } catch (cause) {
+    if (cause instanceof ArgumentError3) throw cause;
+    throw new ArgumentError3("aws-kms unavailable; install a compatible @dnsid-ai/key-aws and include it in the build");
+  }
+}
 async function identityKeyDir(dnsidDir, domain) {
   for (const filename of ["private.jwk", "private.pem"]) {
     try {
@@ -534,10 +607,10 @@ function createNodeIdentityManagerFromDnsid(dnsidDir, overlay, deps) {
 function createNodeIdentityManagerFromFile(filePath, overlay, deps) {
   return loadFile(filePath).then((loaded) => constructIdentityManager(mergeLoadedConfig(loaded, top({ dnsid: overlay })), deps));
 }
-async function createRegistryClientFromEnvironment(env) {
+async function createRegistryClientFromEnvironment(env, options = {}) {
   const source = env ?? process.env;
   const loaded = await loadEnvironment(source);
-  return new RegistryClient(compact({ baseUrl: loaded.registry?.registryUrl, token: source.DNSID_API_KEY?.trim() || void 0 }));
+  return new RegistryClient({ baseUrl: loaded.registry?.registryUrl, token: source.DNSID_API_KEY?.trim() || void 0, ...options });
 }
 function definedEntries(value) {
   return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));

package/package.json

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