TypeScript: @dnsid-ai/sdk/node

Node.js conveniences for DNSid — the @dnsid-ai/sdk/node subpath.

Provides LocalKeyProvider (filesystem-backed key storage), the configuration loaders (loadEnvironment, loadFile, loadCliDirectory → mergeLoadedConfig → constructIdentityManager), the one-call createNodeIdentityManagerFromEnvironment / createNodeIdentityManagerFromDnsid / createNodeIdentityManagerFromFile constructors, and createNodeIdentityManager, which defaults DNS resolution and HTTPS JSON fetching to the optional @dnsid-ai/transport peer. Loaders parse; constructors default. No constructor reads the environment or files. The system resolver reports DNSSEC state UNKNOWN; the default auto policy accepts and preserves that state, while stricter policies require a DNSSEC-aware resolver.

Classes

LocalKeyProvider

Defined in: packages/sdk/src/local-key-provider.ts:38

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.

Implements

• KeyProvider

Methods

activate()

activate(kid): Promise<void>;

Defined in: packages/sdk/src/local-key-provider.ts:145

Promotes a pending key to active. The previously active key transitions to retained.

Parameters

kid

string

Returns

Promise<void>

Implementation of

KeyProvider.activate

generateKey()

generateKey(): Promise<string>;

Defined in: packages/sdk/src/local-key-provider.ts:137

Generates a new key pair in the pending state. Returns the new key’s kid.

Returns

Promise<string>

Implementation of

KeyProvider.generateKey

jwk()

jwk(kid): Promise<DnsIdJWK>;

Defined in: packages/sdk/src/local-key-provider.ts:112

Returns the JWK representation of a key by ID (active, pending, or retained). Raises if not found.

Parameters

kid

string

Returns

Promise<DnsIdJWK>

Implementation of

KeyProvider.jwk

listKeyIds()

listKeyIds(): Promise<string[]>;

Defined in: packages/sdk/src/local-key-provider.ts:121

Returns the IDs of all active and retained keys (pending keys excluded). The active key ID MUST appear first; retained keys follow in any order.

Returns

Promise<string[]>

Implementation of

KeyProvider.listKeyIds

purge()

purge(kid): Promise<void>;

Defined in: packages/sdk/src/local-key-provider.ts:167

Parameters

kid

string

Returns

Promise<void>

Deprecated

Use supersede().

Implementation of

KeyProvider.purge

sign()

sign(payload): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/sdk/src/local-key-provider.ts:125

Signs the given payload with the current active signing key. Returns raw signature bytes.

Parameters

payload

Uint8Array

Returns

Promise<Uint8Array<ArrayBufferLike>>

Implementation of

KeyProvider.sign

signingKey()

signingKey(): Promise<DnsIdJWK>;

Defined in: packages/sdk/src/local-key-provider.ts:108

Returns the JWK representation of the current active public signing key. The returned kid MUST NOT contain ’#’.

Returns

Promise<DnsIdJWK>

Implementation of

KeyProvider.signingKey

signKey()

signKey(kid, payload): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/sdk/src/local-key-provider.ts:129

Signs with a specified active or pending key.

Parameters

kid

string

payload

Uint8Array

Returns

Promise<Uint8Array<ArrayBufferLike>>

Implementation of

KeyProvider.signKey

supersede()

supersede(kid): Promise<void>;

Defined in: packages/sdk/src/local-key-provider.ts:155

Supersedes and removes a retained key from this provider’s published key set.

Parameters

kid

string

Returns

Promise<void>

Implementation of

KeyProvider.supersede

fromDirectory()

static fromDirectory(dir): Promise<LocalKeyProvider>;

Defined in: packages/sdk/src/local-key-provider.ts:81

Parameters

dir

string

Returns

Promise<LocalKeyProvider>

fromDomain()

static fromDomain(domain, dnsidDir?): Promise<LocalKeyProvider>;

Defined in: packages/sdk/src/local-key-provider.ts:104

Parameters

domain

string

dnsidDir?

string = ...

Returns

Promise<LocalKeyProvider>

fromFile()

static fromFile(filePath): Promise<LocalKeyProvider>;

Defined in: packages/sdk/src/local-key-provider.ts:98

Loads a single private JWK file, including DNSid CLI entity_key_path files.

Parameters

filePath

string

Returns

Promise<LocalKeyProvider>

generate()

static generate(algorithm?): Promise<LocalKeyProvider>;

Defined in: packages/sdk/src/local-key-provider.ts:77

Parameters

algorithm?

LocalKeyAlgorithm = 'EdDSA'

Returns

Promise<LocalKeyProvider>

load()

static load(
   filePath,
   createIfMissing?,
   algorithm?
): Promise<LocalKeyProvider>;

Defined in: packages/sdk/src/local-key-provider.ts:49

Parameters

filePath

string

createIfMissing?

boolean = false

algorithm?

LocalKeyAlgorithm = 'EdDSA'

Returns

Promise<LocalKeyProvider>

Interfaces

KeySource

Defined in: packages/sdk/src/config-loading.ts:49

Properties

cliDirectory?

optional cliDirectory?: string;

Defined in: packages/sdk/src/config-loading.ts:51

DNSid CLI identity directory; key files are located under the effective identity domain.

entityKeyPath?

optional entityKeyPath?: string;

Defined in: packages/sdk/src/config-loading.ts:53

Accountable-entity private JWK file.

keyStorePath?

optional keyStorePath?: string;

Defined in: packages/sdk/src/config-loading.ts:55

LocalKeyProvider key-store file; used only when cliDirectory is absent.

---

LoadedConfig

Defined in: packages/sdk/src/config-loading.ts:68

Partial configuration from one source. Every field is present only when sourced.

Properties

dnsid?

optional dnsid?: LoadedDnsidConfig;

Defined in: packages/sdk/src/config-loading.ts:69

keySource?

optional keySource?: KeySource;

Defined in: packages/sdk/src/config-loading.ts:72

logTrust?

optional logTrust?: LogTrust;

Defined in: packages/sdk/src/config-loading.ts:70

registry?

optional registry?: LoadedRegistryConfig;

Defined in: packages/sdk/src/config-loading.ts:71

---

LoadedDnsidConfig

Defined in: packages/sdk/src/config-loading.ts:63

DnsidConfig with a partial identity: sources may supply some publication fields and leave the rest to an overlay.

Extends

• Omit<DnsidConfig, "identity">

Properties

identity?

optional identity?: Partial<IdentityConfig>;

Defined in: packages/sdk/src/config-loading.ts:64

transport?

optional transport?: TransportConfig;

Defined in: packages/protocol/src/types.ts:128

Inherited from

DnsidConfig.transport

verification?

optional verification?: VerificationConfig;

Defined in: packages/protocol/src/types.ts:127

Inherited from

DnsidConfig.verification

---

LoadedRegistryConfig

Defined in: packages/sdk/src/config-loading.ts:58

Properties

registryUrl?

optional registryUrl?: string;

Defined in: packages/sdk/src/config-loading.ts:59

---

LogTrust

Defined in: packages/sdk/src/config-loading.ts:38

Log trust for deps.logRegistry; exactly one variant is required at construction.

Properties

managed?

optional managed?: boolean;

Defined in: packages/sdk/src/config-loading.ts:40

true selects the embedded DNSid-managed catalog.

policyDocument?

optional policyDocument?: Uint8Array<ArrayBufferLike>;

Defined in: packages/sdk/src/config-loading.ts:44

Trusted C2SP tlog-policy bytes.

policyUrl?

optional policyUrl?: string;

Defined in: packages/sdk/src/config-loading.ts:46

Trusted C2SP tlog-policy HTTPS URL.

profile?

optional profile?: Record<string, unknown>;

Defined in: packages/sdk/src/config-loading.ts:42

dnsid-c2sp-tlog-trust-profile@v1 document (parsed JSON).

Type Aliases

EnvironmentSource

type EnvironmentSource = Readonly<Record<string, string | undefined>>;

Defined in: packages/sdk/src/config-loading.ts:35

---

LocalKeyAlgorithm

type LocalKeyAlgorithm = "EdDSA" | "ES256";

Defined in: packages/sdk/src/local-key-provider.ts:16

Functions

constructIdentityManager()

function constructIdentityManager(loaded, deps?): Promise<IdentityManager>;

Defined in: packages/sdk/src/config-loading.ts:297

Fills deps.logRegistry from logTrust and key providers from keySource only when the caller did not supply them, then calls createNodeIdentityManager. Adds no configuration values.

Parameters

loaded

LoadedConfig

deps?

IdentityManagerDependencies = {}

Returns

Promise<IdentityManager>

---

createNodeIdentityManager()

function createNodeIdentityManager(config, deps?): Promise<IdentityManager>;

Defined in: packages/sdk/src/node-identity-manager.ts:32

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 privateAddressHosts 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.

Parameters

config

DnsidConfig

deps?

IdentityManagerDependencies = {}

Returns

Promise<IdentityManager>

Example

import { createNodeIdentityManager, LocalKeyProvider } from '@dnsid-ai/sdk/node';

const keyProvider = await LocalKeyProvider.load('.dnsid/keys.json', true);
const idm = await createNodeIdentityManager({ identity, verification }, { keyProvider, entityKeyProvider });

---

createNodeIdentityManagerFromDnsid()

function createNodeIdentityManagerFromDnsid(
   dnsidDir?,
   overlay?,
   deps?
): Promise<IdentityManager>;

Defined in: packages/sdk/src/config-loading.ts:361

Parameters

dnsidDir?

string

overlay?

LoadedDnsidConfig

deps?

IdentityManagerDependencies

Returns

Promise<IdentityManager>

---

createNodeIdentityManagerFromEnvironment()

function createNodeIdentityManagerFromEnvironment(
   env?,
   overlay?,
   deps?
): Promise<IdentityManager>;

Defined in: packages/sdk/src/config-loading.ts:357

Parameters

env?

Readonly<Record<string, string | undefined>>

overlay?

LoadedDnsidConfig

deps?

IdentityManagerDependencies

Returns

Promise<IdentityManager>

---

createNodeIdentityManagerFromFile()

function createNodeIdentityManagerFromFile(
   filePath,
   overlay?,
   deps?
): Promise<IdentityManager>;

Defined in: packages/sdk/src/config-loading.ts:365

Parameters

filePath

string

overlay?

LoadedDnsidConfig

deps?

IdentityManagerDependencies

Returns

Promise<IdentityManager>

---

createNodeIdentityVerifier()

function createNodeIdentityVerifier(config?, deps?): Promise<IdentityManager>;

Defined in: packages/sdk/src/node-identity-manager.ts:53

Creates a verification-only IdentityManager with Node.js DNS and HTTPS defaults (config.identity omitted).

Parameters

config?

Omit<DnsidConfig, "identity"> = {}

deps?

Omit<IdentityManagerDependencies, "keyProvider" | "entityKeyProvider"> = {}

Returns

Promise<IdentityManager>

---

createRegistryClientFromEnvironment()

function createRegistryClientFromEnvironment(env?): Promise<RegistryClient>;

Defined in: packages/sdk/src/config-loading.ts:370

RegistryClient from DNSID_REGISTRY_URL and DNSID_API_KEY; the constructor defaults to the local registry.

Parameters

env?

Readonly<Record<string, string | undefined>>

Returns

Promise<RegistryClient>

---

loadCliDirectory()

function loadCliDirectory(dnsidDir?): Promise<LoadedConfig>;

Defined in: packages/sdk/src/config-loading.ts:226

Reads a DNSid CLI directory (~/.dnsid by default): config.json, following a root domain pointer to <domain>/config.json when that file exists. Maps the snake_case publication fields into dnsid.identity and records the directory (and resolved entity_key_path) as keySource. Never consults DNSID_CONFIG_DIR.

Parameters

dnsidDir?

string = ...

Returns

Promise<LoadedConfig>

---

loadEnvironment()

function loadEnvironment(env?): Promise<LoadedConfig>;

Defined in: packages/sdk/src/config-loading.ts:90

Reads configuration from DNSID_*. Secrets such as DNSID_API_KEY stay out of LoadedConfig.

Parameters

env?

EnvironmentSource = process.env

Returns

Promise<LoadedConfig>

---

loadFile()

function loadFile(filePath): Promise<LoadedConfig>;

Defined in: packages/sdk/src/config-loading.ts:137

Reads a JSON deployment file: { dnsid?, logTrust?, registry? }. Unknown members, mistyped values, and duplicate members are rejected; semantic dnsid validation stays with the constructor.

Parameters

filePath

string

Returns

Promise<LoadedConfig>

---

mergeLoadedConfig()

function mergeLoadedConfig(base, overlay): LoadedConfig;

Defined in: packages/sdk/src/config-loading.ts:265

Field-wise merge; presence wins, not truthiness. Lists replace. logTrust is replaced as a whole section when overlay sets any variant.

Parameters

base

LoadedConfig

overlay

LoadedConfig

Returns

LoadedConfig

References

CreateIdentityManagerDependencies

Re-exports CreateIdentityManagerDependencies