@dnsid-ai/sdk 0.20.1

package/dist/node.d.cts

@@ -0,0 +1,195 @@
+import { KeyProvider, DnsIdJWK, DNSSECMode, DnsidConfig, IdentityConfig, IdentityManagerDependencies, IdentityManager } from '@dnsid-ai/protocol';
+export { CreateIdentityManagerDependencies } from './index.cjs';
+import '@dnsid-ai/jose';
+import '@dnsid-ai/http-signatures';
+import '@dnsid-ai/registry';
+import '@dnsid-ai/web-bot-auth';
+
+type LocalKeyAlgorithm = 'EdDSA' | 'ES256';
+interface LocalKeyProviderEnvironmentOptions {
+    /** Default key-store path when the environment variable is absent. Default: .dnsid/keys.json. */
+    defaultPath?: string;
+    /** Create an initial key store if the file does not exist. Default: false. */
+    createIfMissing?: boolean;
+    /** Algorithm used when creating a missing key store. Default: EdDSA. */
+    algorithm?: LocalKeyAlgorithm;
+}
+/**
+ * File-backed KeyProvider that stores Ed25519 or ECDSA P-256 keys as a JSON file.
+ *
+ * This concrete key-storage implementation is provided by `@dnsid-ai/sdk` as the default developer/runtime key provider.
+ * Use only one provider instance/process per file. Mutations within an instance are serialized.
+ * Writes require filesystem support for atomic rename, hard links, and directory fsync.
+ * Existing symlinks are resolved at load time; `<resolvedPath>.bak` holds the private previous generation.
+ * A failure after replacement may mean the new state is visible but not crash-durable;
+ * memory follows the visible file. Inspect the store before retrying a failed mutation.
+ */
+declare class LocalKeyProvider implements KeyProvider {
+    private store;
+    private readonly filePath;
+    private mutations;
+    private constructor();
+    static load(filePath: string, createIfMissing?: boolean, algorithm?: LocalKeyAlgorithm): Promise<LocalKeyProvider>;
+    static fromEnvironment(env?: Record<string, string | undefined>, options?: LocalKeyProviderEnvironmentOptions): Promise<LocalKeyProvider>;
+    static generate(algorithm?: LocalKeyAlgorithm): Promise<LocalKeyProvider>;
+    static fromDirectory(dir: string): Promise<LocalKeyProvider>;
+    /** Loads a single private JWK file, including DNSid CLI `entity_key_path` files. */
+    static fromFile(filePath: string): Promise<LocalKeyProvider>;
+    static fromDomain(domain: string, dnsidDir?: string): Promise<LocalKeyProvider>;
+    signingKey(): Promise<DnsIdJWK>;
+    jwk(kid: string): Promise<DnsIdJWK>;
+    listKeyIds(): Promise<string[]>;
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+    signKey(kid: string, payload: Uint8Array): Promise<Uint8Array>;
+    generateKey(): Promise<string>;
+    activate(kid: string): Promise<void>;
+    supersede(kid: string): Promise<void>;
+    /** @deprecated Use supersede(). */
+    purge(kid: string): Promise<void>;
+    private mutate;
+}
+declare function keyStorePathFromEnvironment(env?: Record<string, string | undefined>, defaultPath?: string): string;
+
+declare const dnsidEnvironmentVariables: {
+    readonly domain: "DNSID_DOMAIN";
+    readonly governanceId: "DNSID_GOVERNANCE_ID";
+    readonly registryUrl: "DNSID_REGISTRY_URL";
+    readonly apiKey: "DNSID_API_KEY";
+    readonly statusUrl: "DNSID_STATUS_URL";
+    readonly logRef: "DNSID_LOG_REF";
+    readonly ekUrl: "DNSID_EK_URL";
+    readonly kuUrl: "DNSID_KU_URL";
+    readonly dnsServer: "DNSID_DNS_SERVER";
+    readonly caBundlePath: "DNSID_CA_BUNDLE";
+    readonly dnssecMode: "DNSID_DNSSEC_MODE";
+    readonly publicUrl: "DNSID_PUBLIC_URL";
+    readonly keyStorePath: "DNSID_KEY_STORE";
+    readonly agentPort: "DNSID_AGENT_PORT";
+    readonly agentName: "DNSID_AGENT_NAME";
+};
+type EnvironmentFieldName = keyof typeof dnsidEnvironmentVariables;
+type EnvironmentVariableName = (typeof dnsidEnvironmentVariables)[EnvironmentFieldName];
+type EnvironmentSource = Record<string, string | undefined>;
+interface EnvironmentField<T> {
+    variable: EnvironmentVariableName;
+    parse(value: string, variable: EnvironmentVariableName): T;
+}
+declare const environmentSchema: {
+    domain: EnvironmentField<string>;
+    governanceId: EnvironmentField<string>;
+    registryUrl: EnvironmentField<string>;
+    apiKey: EnvironmentField<string>;
+    statusUrl: EnvironmentField<string>;
+    logRef: EnvironmentField<string>;
+    ekUrl: EnvironmentField<string>;
+    kuUrl: EnvironmentField<string>;
+    dnsServer: EnvironmentField<string>;
+    caBundlePath: EnvironmentField<string>;
+    dnssecMode: EnvironmentField<DNSSECMode>;
+    publicUrl: EnvironmentField<string>;
+    keyStorePath: EnvironmentField<string>;
+    agentPort: EnvironmentField<number>;
+    agentName: EnvironmentField<string>;
+};
+type EnvironmentValue<K extends EnvironmentFieldName> = typeof environmentSchema[K] extends EnvironmentField<infer T> ? T : never;
+type DnsidEnvironment = {
+    [K in EnvironmentFieldName]?: EnvironmentValue<K>;
+};
+type ConfigForEnvironment<RequiredFields extends EnvironmentFieldName> = DnsidConfig & {
+    identity: IdentityConfig & Required<Pick<IdentityConfig, Extract<RequiredFields, keyof IdentityConfig>>>;
+};
+interface EnvironmentConfigResultBase<RequiredFields extends EnvironmentFieldName = never> {
+    /** Core configuration: `identity` publication fields, `verification.dnssecMode`, and `transport` from the environment. */
+    config: ConfigForEnvironment<RequiredFields>;
+    /** Base URL of the DNSid registry for control-plane workflows. Defaults to the local registry ({@link DEFAULT_REGISTRY_URL}). Not core config. */
+    registryUrl: string;
+    /** Owner API key for registry workflows (`DNSID_API_KEY`); `dnsid local env` exports one for the local registry. */
+    apiKey?: string;
+    /** Optional public base URL for the agent, e.g. https://alice.example.com. */
+    publicUrl?: string;
+    /** Optional local key-store path for LocalKeyProvider. */
+    keyStorePath?: string;
+    /** Optional example/server display name. */
+    agentName?: string;
+    /** Optional example/server port. */
+    agentPort?: number;
+}
+type EnvironmentConfigResult<RequiredFields extends EnvironmentFieldName = never> = EnvironmentConfigResultBase<RequiredFields> & Required<Pick<EnvironmentConfigResultBase<RequiredFields>, Extract<RequiredFields, keyof EnvironmentConfigResultBase<RequiredFields>>>>;
+interface ConfigFromEnvironmentOptions<RequiredFields extends EnvironmentFieldName = never> {
+    require?: readonly RequiredFields[];
+}
+/**
+ * Explicit loader mapping DNSID_* environment variables to a {@link DnsidConfig} plus
+ * registry/example settings. Constructors never read the environment themselves.
+ */
+declare function configFromEnvironment<const RequiredFields extends EnvironmentFieldName = never>(options?: ConfigFromEnvironmentOptions<RequiredFields>): EnvironmentConfigResult<RequiredFields>;
+declare function configFromEnvironment<const RequiredFields extends EnvironmentFieldName = never>(env: EnvironmentSource | undefined, options?: ConfigFromEnvironmentOptions<RequiredFields>): EnvironmentConfigResult<RequiredFields>;
+/**
+ * Registry client options from `DNSID_REGISTRY_URL` and `DNSID_API_KEY`, the
+ * variables `dnsid local env` exports. Unset means the local registry with no
+ * credential. Unlike {@link configFromEnvironment} this needs no identity
+ * variables, so it works before an agent exists:
+ * `new RegistryClient(registryClientOptionsFromEnvironment())`.
+ */
+declare function registryClientOptionsFromEnvironment(env?: EnvironmentSource): {
+    baseUrl: string;
+    token?: string;
+};
+
+/** Explicit inputs for {@link createNodeIdentityManagerFromDnsid}. */
+interface CreateNodeIdentityManagerFromDnsidOptions {
+    /** Root DNSid directory containing config.json and <fqdn>/{private,public}.jwk. Defaults to `DNSID_CONFIG_DIR` or ~/.dnsid. */
+    dnsidDir?: string;
+    /** Environment used to discover DNSID_CONFIG_DIR. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /**
+     * Caller settings. `identity` fields overlay the persisted publication fields before any
+     * normalization or derivation; `verification` and `transport` are never read from the CLI files.
+     */
+    config?: Omit<DnsidConfig, 'identity'> & {
+        identity?: Partial<IdentityConfig>;
+    };
+}
+/**
+ * Creates an IdentityManager with Node.js DNS and HTTPS defaults.
+ *
+ * `config.transport` configures only the SDK-managed defaults: `dnsServer` applies to whichever of
+ * `dnsResolver`/`fetchJson` is not injected and is rejected when both are; `caBundlePath` and
+ * `allowedUnsafeHosts` apply to the default fetcher and are rejected when `fetchJson` is injected. Injected dependencies are never
+ * inspected or modified. `@dnsid-ai/transport` is an optional peer; install it or inject both
+ * dependencies. The system resolver reports `UNKNOWN`; `validated`/`required` DNSSEC modes need a
+ * DNSSEC-aware resolver.
+ *
+ * @example
+ * ```ts
+ * import { configFromEnvironment, createNodeIdentityManager, LocalKeyProvider } from '@dnsid-ai/sdk/node';
+ *
+ * const { config, keyStorePath } = configFromEnvironment();
+ * const keyProvider = await LocalKeyProvider.load(keyStorePath ?? '.dnsid/keys.json', true);
+ * const idm = await createNodeIdentityManager(config, { keyProvider, entityKeyProvider });
+ * ```
+ */
+declare function createNodeIdentityManager(config: DnsidConfig, deps?: IdentityManagerDependencies): Promise<IdentityManager>;
+/** Creates a verification-only IdentityManager with Node.js DNS and HTTPS defaults (`config.identity` omitted). */
+declare function createNodeIdentityVerifier(config?: Omit<DnsidConfig, 'identity'>, deps?: Omit<IdentityManagerDependencies, 'keyProvider' | 'entityKeyProvider'>): Promise<IdentityManager>;
+/**
+ * Creates an IdentityManager from a DNSid CLI directory layout (`~/.dnsid` by default).
+ *
+ * Reads `config.json` (following a `domain` pointer to a per-identity config when present) and
+ * maps its publication fields into `config.identity`; caller `options.config.identity` values win
+ * and are applied before normalization or `status_url` derivation. Key files are located by the
+ * effective domain. Verification and transport settings come only from `options.config`. Supplied
+ * `deps.keyProvider`/`deps.entityKeyProvider` win over loaded key files. The result is identical to
+ * calling {@link createNodeIdentityManager} with the assembled configuration.
+ *
+ * @example
+ * ```ts
+ * import { createNodeIdentityManagerFromDnsid } from '@dnsid-ai/sdk/node';
+ *
+ * // Reads ~/.dnsid (or DNSID_CONFIG_DIR) for config.json and key files.
+ * const idm = await createNodeIdentityManagerFromDnsid();
+ * ```
+ */
+declare function createNodeIdentityManagerFromDnsid(options?: CreateNodeIdentityManagerFromDnsidOptions, deps?: IdentityManagerDependencies): Promise<IdentityManager>;
+
+export { type ConfigFromEnvironmentOptions, type CreateNodeIdentityManagerFromDnsidOptions, type DnsidEnvironment, type EnvironmentConfigResult, type EnvironmentFieldName, type LocalKeyAlgorithm, LocalKeyProvider, type LocalKeyProviderEnvironmentOptions, configFromEnvironment, createNodeIdentityManager, createNodeIdentityManagerFromDnsid, createNodeIdentityVerifier, dnsidEnvironmentVariables, keyStorePathFromEnvironment, registryClientOptionsFromEnvironment };

package/dist/node.d.ts

@@ -0,0 +1,195 @@
+import { KeyProvider, DnsIdJWK, DNSSECMode, DnsidConfig, IdentityConfig, IdentityManagerDependencies, IdentityManager } from '@dnsid-ai/protocol';
+export { CreateIdentityManagerDependencies } from './index.js';
+import '@dnsid-ai/jose';
+import '@dnsid-ai/http-signatures';
+import '@dnsid-ai/registry';
+import '@dnsid-ai/web-bot-auth';
+
+type LocalKeyAlgorithm = 'EdDSA' | 'ES256';
+interface LocalKeyProviderEnvironmentOptions {
+    /** Default key-store path when the environment variable is absent. Default: .dnsid/keys.json. */
+    defaultPath?: string;
+    /** Create an initial key store if the file does not exist. Default: false. */
+    createIfMissing?: boolean;
+    /** Algorithm used when creating a missing key store. Default: EdDSA. */
+    algorithm?: LocalKeyAlgorithm;
+}
+/**
+ * File-backed KeyProvider that stores Ed25519 or ECDSA P-256 keys as a JSON file.
+ *
+ * This concrete key-storage implementation is provided by `@dnsid-ai/sdk` as the default developer/runtime key provider.
+ * Use only one provider instance/process per file. Mutations within an instance are serialized.
+ * Writes require filesystem support for atomic rename, hard links, and directory fsync.
+ * Existing symlinks are resolved at load time; `<resolvedPath>.bak` holds the private previous generation.
+ * A failure after replacement may mean the new state is visible but not crash-durable;
+ * memory follows the visible file. Inspect the store before retrying a failed mutation.
+ */
+declare class LocalKeyProvider implements KeyProvider {
+    private store;
+    private readonly filePath;
+    private mutations;
+    private constructor();
+    static load(filePath: string, createIfMissing?: boolean, algorithm?: LocalKeyAlgorithm): Promise<LocalKeyProvider>;
+    static fromEnvironment(env?: Record<string, string | undefined>, options?: LocalKeyProviderEnvironmentOptions): Promise<LocalKeyProvider>;
+    static generate(algorithm?: LocalKeyAlgorithm): Promise<LocalKeyProvider>;
+    static fromDirectory(dir: string): Promise<LocalKeyProvider>;
+    /** Loads a single private JWK file, including DNSid CLI `entity_key_path` files. */
+    static fromFile(filePath: string): Promise<LocalKeyProvider>;
+    static fromDomain(domain: string, dnsidDir?: string): Promise<LocalKeyProvider>;
+    signingKey(): Promise<DnsIdJWK>;
+    jwk(kid: string): Promise<DnsIdJWK>;
+    listKeyIds(): Promise<string[]>;
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+    signKey(kid: string, payload: Uint8Array): Promise<Uint8Array>;
+    generateKey(): Promise<string>;
+    activate(kid: string): Promise<void>;
+    supersede(kid: string): Promise<void>;
+    /** @deprecated Use supersede(). */
+    purge(kid: string): Promise<void>;
+    private mutate;
+}
+declare function keyStorePathFromEnvironment(env?: Record<string, string | undefined>, defaultPath?: string): string;
+
+declare const dnsidEnvironmentVariables: {
+    readonly domain: "DNSID_DOMAIN";
+    readonly governanceId: "DNSID_GOVERNANCE_ID";
+    readonly registryUrl: "DNSID_REGISTRY_URL";
+    readonly apiKey: "DNSID_API_KEY";
+    readonly statusUrl: "DNSID_STATUS_URL";
+    readonly logRef: "DNSID_LOG_REF";
+    readonly ekUrl: "DNSID_EK_URL";
+    readonly kuUrl: "DNSID_KU_URL";
+    readonly dnsServer: "DNSID_DNS_SERVER";
+    readonly caBundlePath: "DNSID_CA_BUNDLE";
+    readonly dnssecMode: "DNSID_DNSSEC_MODE";
+    readonly publicUrl: "DNSID_PUBLIC_URL";
+    readonly keyStorePath: "DNSID_KEY_STORE";
+    readonly agentPort: "DNSID_AGENT_PORT";
+    readonly agentName: "DNSID_AGENT_NAME";
+};
+type EnvironmentFieldName = keyof typeof dnsidEnvironmentVariables;
+type EnvironmentVariableName = (typeof dnsidEnvironmentVariables)[EnvironmentFieldName];
+type EnvironmentSource = Record<string, string | undefined>;
+interface EnvironmentField<T> {
+    variable: EnvironmentVariableName;
+    parse(value: string, variable: EnvironmentVariableName): T;
+}
+declare const environmentSchema: {
+    domain: EnvironmentField<string>;
+    governanceId: EnvironmentField<string>;
+    registryUrl: EnvironmentField<string>;
+    apiKey: EnvironmentField<string>;
+    statusUrl: EnvironmentField<string>;
+    logRef: EnvironmentField<string>;
+    ekUrl: EnvironmentField<string>;
+    kuUrl: EnvironmentField<string>;
+    dnsServer: EnvironmentField<string>;
+    caBundlePath: EnvironmentField<string>;
+    dnssecMode: EnvironmentField<DNSSECMode>;
+    publicUrl: EnvironmentField<string>;
+    keyStorePath: EnvironmentField<string>;
+    agentPort: EnvironmentField<number>;
+    agentName: EnvironmentField<string>;
+};
+type EnvironmentValue<K extends EnvironmentFieldName> = typeof environmentSchema[K] extends EnvironmentField<infer T> ? T : never;
+type DnsidEnvironment = {
+    [K in EnvironmentFieldName]?: EnvironmentValue<K>;
+};
+type ConfigForEnvironment<RequiredFields extends EnvironmentFieldName> = DnsidConfig & {
+    identity: IdentityConfig & Required<Pick<IdentityConfig, Extract<RequiredFields, keyof IdentityConfig>>>;
+};
+interface EnvironmentConfigResultBase<RequiredFields extends EnvironmentFieldName = never> {
+    /** Core configuration: `identity` publication fields, `verification.dnssecMode`, and `transport` from the environment. */
+    config: ConfigForEnvironment<RequiredFields>;
+    /** Base URL of the DNSid registry for control-plane workflows. Defaults to the local registry ({@link DEFAULT_REGISTRY_URL}). Not core config. */
+    registryUrl: string;
+    /** Owner API key for registry workflows (`DNSID_API_KEY`); `dnsid local env` exports one for the local registry. */
+    apiKey?: string;
+    /** Optional public base URL for the agent, e.g. https://alice.example.com. */
+    publicUrl?: string;
+    /** Optional local key-store path for LocalKeyProvider. */
+    keyStorePath?: string;
+    /** Optional example/server display name. */
+    agentName?: string;
+    /** Optional example/server port. */
+    agentPort?: number;
+}
+type EnvironmentConfigResult<RequiredFields extends EnvironmentFieldName = never> = EnvironmentConfigResultBase<RequiredFields> & Required<Pick<EnvironmentConfigResultBase<RequiredFields>, Extract<RequiredFields, keyof EnvironmentConfigResultBase<RequiredFields>>>>;
+interface ConfigFromEnvironmentOptions<RequiredFields extends EnvironmentFieldName = never> {
+    require?: readonly RequiredFields[];
+}
+/**
+ * Explicit loader mapping DNSID_* environment variables to a {@link DnsidConfig} plus
+ * registry/example settings. Constructors never read the environment themselves.
+ */
+declare function configFromEnvironment<const RequiredFields extends EnvironmentFieldName = never>(options?: ConfigFromEnvironmentOptions<RequiredFields>): EnvironmentConfigResult<RequiredFields>;
+declare function configFromEnvironment<const RequiredFields extends EnvironmentFieldName = never>(env: EnvironmentSource | undefined, options?: ConfigFromEnvironmentOptions<RequiredFields>): EnvironmentConfigResult<RequiredFields>;
+/**
+ * Registry client options from `DNSID_REGISTRY_URL` and `DNSID_API_KEY`, the
+ * variables `dnsid local env` exports. Unset means the local registry with no
+ * credential. Unlike {@link configFromEnvironment} this needs no identity
+ * variables, so it works before an agent exists:
+ * `new RegistryClient(registryClientOptionsFromEnvironment())`.
+ */
+declare function registryClientOptionsFromEnvironment(env?: EnvironmentSource): {
+    baseUrl: string;
+    token?: string;
+};
+
+/** Explicit inputs for {@link createNodeIdentityManagerFromDnsid}. */
+interface CreateNodeIdentityManagerFromDnsidOptions {
+    /** Root DNSid directory containing config.json and <fqdn>/{private,public}.jwk. Defaults to `DNSID_CONFIG_DIR` or ~/.dnsid. */
+    dnsidDir?: string;
+    /** Environment used to discover DNSID_CONFIG_DIR. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /**
+     * Caller settings. `identity` fields overlay the persisted publication fields before any
+     * normalization or derivation; `verification` and `transport` are never read from the CLI files.
+     */
+    config?: Omit<DnsidConfig, 'identity'> & {
+        identity?: Partial<IdentityConfig>;
+    };
+}
+/**
+ * Creates an IdentityManager with Node.js DNS and HTTPS defaults.
+ *
+ * `config.transport` configures only the SDK-managed defaults: `dnsServer` applies to whichever of
+ * `dnsResolver`/`fetchJson` is not injected and is rejected when both are; `caBundlePath` and
+ * `allowedUnsafeHosts` apply to the default fetcher and are rejected when `fetchJson` is injected. Injected dependencies are never
+ * inspected or modified. `@dnsid-ai/transport` is an optional peer; install it or inject both
+ * dependencies. The system resolver reports `UNKNOWN`; `validated`/`required` DNSSEC modes need a
+ * DNSSEC-aware resolver.
+ *
+ * @example
+ * ```ts
+ * import { configFromEnvironment, createNodeIdentityManager, LocalKeyProvider } from '@dnsid-ai/sdk/node';
+ *
+ * const { config, keyStorePath } = configFromEnvironment();
+ * const keyProvider = await LocalKeyProvider.load(keyStorePath ?? '.dnsid/keys.json', true);
+ * const idm = await createNodeIdentityManager(config, { keyProvider, entityKeyProvider });
+ * ```
+ */
+declare function createNodeIdentityManager(config: DnsidConfig, deps?: IdentityManagerDependencies): Promise<IdentityManager>;
+/** Creates a verification-only IdentityManager with Node.js DNS and HTTPS defaults (`config.identity` omitted). */
+declare function createNodeIdentityVerifier(config?: Omit<DnsidConfig, 'identity'>, deps?: Omit<IdentityManagerDependencies, 'keyProvider' | 'entityKeyProvider'>): Promise<IdentityManager>;
+/**
+ * Creates an IdentityManager from a DNSid CLI directory layout (`~/.dnsid` by default).
+ *
+ * Reads `config.json` (following a `domain` pointer to a per-identity config when present) and
+ * maps its publication fields into `config.identity`; caller `options.config.identity` values win
+ * and are applied before normalization or `status_url` derivation. Key files are located by the
+ * effective domain. Verification and transport settings come only from `options.config`. Supplied
+ * `deps.keyProvider`/`deps.entityKeyProvider` win over loaded key files. The result is identical to
+ * calling {@link createNodeIdentityManager} with the assembled configuration.
+ *
+ * @example
+ * ```ts
+ * import { createNodeIdentityManagerFromDnsid } from '@dnsid-ai/sdk/node';
+ *
+ * // Reads ~/.dnsid (or DNSID_CONFIG_DIR) for config.json and key files.
+ * const idm = await createNodeIdentityManagerFromDnsid();
+ * ```
+ */
+declare function createNodeIdentityManagerFromDnsid(options?: CreateNodeIdentityManagerFromDnsidOptions, deps?: IdentityManagerDependencies): Promise<IdentityManager>;
+
+export { type ConfigFromEnvironmentOptions, type CreateNodeIdentityManagerFromDnsidOptions, type DnsidEnvironment, type EnvironmentConfigResult, type EnvironmentFieldName, type LocalKeyAlgorithm, LocalKeyProvider, type LocalKeyProviderEnvironmentOptions, configFromEnvironment, createNodeIdentityManager, createNodeIdentityManagerFromDnsid, createNodeIdentityVerifier, dnsidEnvironmentVariables, keyStorePathFromEnvironment, registryClientOptionsFromEnvironment };