TypeScript: @dnsid-ai/sdk

Ergonomic aggregate package for DNSid TypeScript consumers.

The root @dnsid-ai/sdk entrypoint is runtime-neutral: callers inject DNS resolution, JSON fetching, key-provider, cache, and log implementations. Node.js defaults live behind the @dnsid-ai/sdk/node subpath and optional @dnsid-ai/transport peer.

Package layout

• Root export (@dnsid-ai/sdk) — runtime-neutral. No Node built-ins, Buffer, filesystem, or undici imports; you inject dnsResolver, fetchJson, and key providers. Safe to bundle for browsers and other non-Node runtimes. Its managed C2SP workflows use the portable writer-only binding entrypoint.
• @dnsid-ai/sdk/node subpath — Node conveniences: LocalKeyProvider, configuration loaders (loadEnvironment, loadFile, loadCliDirectory, mergeLoadedConfig, constructIdentityManager), createNodeIdentityManager, and the one-call createNodeIdentityManagerFromEnvironment / FromDnsid / FromFile. Loads the optional @dnsid-ai/transport peer when HTTPS defaults are needed.
• OIDC lives in @dnsid-ai/oidc — deliberately not re-exported from the root because its default transport is Node-bound, and private-key token minting belongs server-side. Import it directly.

Install

npm install @dnsid-ai/sdk

For Node defaults:

npm install @dnsid-ai/sdk @dnsid-ai/transport

Runtime-neutral usage

import { createIdentityManager } from '@dnsid-ai/sdk';

const idm = createIdentityManager({ identity, verification }, {
  keyProvider,       // operational ku key
  entityKeyProvider, // accountable-entity ek key
  dnsResolver,
  fetchJson,
});

For verification-only use, no local identity configuration or key provider is needed:

import { createIdentityVerifier } from '@dnsid-ai/sdk';

const verifier = createIdentityVerifier(
  { verification: { trustedEntities: [{ governanceId: 'agent.example' }] } },
  { dnsResolver, fetchJson, logRegistry },
);
const verified = await verifier.verifyDomain('agent.example');

JOSE, HTTP Message Signature, and OIDC profiles may use this verifier as their identityResolver while omitting keyProvider. Their signing or minting methods then fail with ArgumentError.

Registry-managed C2SP key rotation

rotateManagedOperationalKey() composes the registry client, C2SP prepared-event binding, and operational KeyProvider. It validates and signs the registry’s prepared bytes, then activates the pending key only after the registry accepts those exact bytes. This does not change the generic/self-managed IdentityManager.rotateOperationalKey() workflow.

If the result is pending, or ManagedKeyRotationSubmissionError reports retryWithSameBytes, persist its rotation state, pause new application signing, and call resumeManagedOperationalKeyRotation() with that exact state. Do not generate a replacement event or idempotency key.

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.

Node.js convenience usage

import { createNodeIdentityManagerFromEnvironment } from '@dnsid-ai/sdk/node';

// Loaders parse; constructors default. Identity from DNSID_*, keys from DNSID_CONFIG_DIR or
// DNSID_KEY_STORE, log trust from DNSID_LOG_POLICY_URL / _FILE / DNSID_LOG_TRUST_PROFILE_FILE.
// Without DNSID_DOMAIN the result is a verification-only manager.
const idm = await createNodeIdentityManagerFromEnvironment();

createNodeIdentityManagerFromEnvironment(env?, overlay?, deps?) is exactly constructIdentityManager(mergeLoadedConfig(await loadEnvironment(env), { dnsid: overlay }), deps); createNodeIdentityManagerFromDnsid(dir?) and createNodeIdentityManagerFromFile(path) are the same shape over loadCliDirectory and loadFile. Compose sources yourself with mergeLoadedConfig (field-wise, presence wins, lists replace, logTrust atomic). Supplied deps always win over loaded logTrust and keySource. The environment schema is in the repository README.

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

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

config.transport.dnsServer/caBundlePath configure only the SDK-managed default resolver and fetcher; a setting is rejected when every dependency it would configure is injected.

LocalKeyProvider.load(path) loads an existing store; pass true to create one when missing. Use only one provider instance/process per store; mutations within that instance are serialized. Persistence uses flushed, mode-0600 sibling files and atomic replacement, keeping the previous successful generation at <path>.bak. Existing symlinks are resolved at load time; mutations and backups use the resolved target path without replacing the link. The filesystem must support atomic rename, hard links, and directory fsync. Protect and exclude the store, backup, and sibling *.tmp files from source control; backups and crash-leftover temp files contain private keys. This is not an off-host backup. If a mutation fails before replacement, the live store and in-memory keys are unchanged. A directory fsync failure after replacement is reported, but memory follows the now-visible file; inspect it before retrying. Recovery is manual: stop all users of the store, preserve both files, and validate the backup against the registry/log state before restoring it. A backup can predate key activation or contain a superseded key; it is never automatically loaded. For dnsid-draft-01 publishing, set DNSID_EK_URL to the accountable-entity JWKS URL and DNSID_KU_URL to the operational JWKS URL. The Node helper uses the system or configured DNS resolver by default. It reports UNKNOWN, which the default auto policy permits and preserves. Inject a DNSSEC-aware resolver for validated or required policy.

If the registry CLI has already written ~/.dnsid/config.json and ~/.dnsid/<fqdn>/private.jwk:

import { createNodeIdentityManagerFromDnsid } from '@dnsid-ai/sdk/node';

const idm = await createNodeIdentityManagerFromDnsid(); // ~/.dnsid by default; never reads DNSID_CONFIG_DIR

The CLI loader maps persisted fields as written: a missing status_url or log_ref fails construction with ArgumentError unless the overlay supplies it.

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.

Included surfaces

@dnsid-ai/sdk re-exports the common core and profile surfaces and namespaces:

• @dnsid-ai/protocol
• @dnsid-ai/jose
• @dnsid-ai/http-signatures
• @dnsid-ai/registry

Use DNSid OIDC token minting and verification through @dnsid-ai/oidc. It is intentionally not re-exported here because its default transport is Node-bound; private-key token minting belongs in server-side code, not browser/client code.

Use lower-level packages directly when you need narrower dependencies or custom composition.

Modules

• index
• node

Runtime-neutral SDK entry point for DNSid.

@dnsid-ai/sdk aggregates the DNSid TypeScript packages: it re-exports the full protocol core (@dnsid-ai/protocol), the registry client and publishing helpers, the JOSE, HTTP message signatures, and web bot auth profiles, and managed operational key rotation workflows.

This root entry point makes no runtime assumptions: callers inject DNS resolution, JSON fetching, key-provider, cache, and log implementations (see createIdentityManager). Node conveniences — LocalKeyProvider, environment config loading, and Node identity manager factories — live behind the @dnsid-ai/sdk/node subpath. OIDC support deliberately lives in @dnsid-ai/oidc (Node-bound transport) and is not re-exported here.

Namespaces

• httpSignatures
• jose
• registry
• webBotAuth

Enumerations

DNSSECMode

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

Enumeration Members

auto

auto: "auto";

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

required

required: "required";

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

validated

validated: "validated";

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

---

DNSSECState

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

Enumeration Members

FAILED

FAILED: "FAILED";

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

UNKNOWN

UNKNOWN: "UNKNOWN";

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

UNSIGNED

UNSIGNED: "UNSIGNED";

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

VALID

VALID: "VALID";

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

---

VerificationCode

Defined in: packages/protocol/src/errors.ts:2

Machine-readable classification of a DNSid verification failure, carried on VerificationError.

Enumeration Members

CounterpartyNotAccepted

CounterpartyNotAccepted: "CounterpartyNotAccepted";

Defined in: packages/protocol/src/errors.ts:22

Configured trustedEntities policy denied a protocol-valid counterparty. Always permanent.

DNSResolution

DNSResolution: "DNSResolution";

Defined in: packages/protocol/src/errors.ts:4

DNS lookup of the _dnsid TXT record failed or returned no identity record. Absence alone is not classified as transient.

DNSSECFailed

DNSSECFailed: "DNSSECFailed";

Defined in: packages/protocol/src/errors.ts:6

DNSSEC validation failed, or the zone is unsigned when the configured DNSSEC mode requires signing.

KeyAgeExceeded

KeyAgeExceeded: "KeyAgeExceeded";

Defined in: packages/protocol/src/errors.ts:14

The operational key is older than the identity record’s ka maximum key age.

LogError

LogError: "LogError";

Defined in: packages/protocol/src/errors.ts:20

A transparency log read, entry check, or consistency verification failed.

RecordInvalid

RecordInvalid: "RecordInvalid";

Defined in: packages/protocol/src/errors.ts:8

The identity record or a fetched JWKS is malformed or fails protocol validation.

SignatureInvalid

SignatureInvalid: "SignatureInvalid";

Defined in: packages/protocol/src/errors.ts:10

The identity record signature (or a bilateral binding signature) does not verify against the entity key.

StatusNotActive

StatusNotActive: "StatusNotActive";

Defined in: packages/protocol/src/errors.ts:18

The agent status document reports a state other than active (e.g. revoked or retired).

StatusUnavailable

StatusUnavailable: "StatusUnavailable";

Defined in: packages/protocol/src/errors.ts:16

The agent status endpoint is unreachable or returned an unusable response.

TLSError

TLSError: "TLSError";

Defined in: packages/protocol/src/errors.ts:12

An HTTPS fetch of the JWKS or status endpoint failed at the transport/TLS layer.

Type Aliases

AgentStatusState

type AgentStatusState =
  | "PENDING"
  | "PROVISIONING"
  | "VERIFYING"
  | "ACTIVE"
  | "RETIRED"
  | "REVOKED";

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

---

CreateIdentityManagerDependencies

type CreateIdentityManagerDependencies = IdentityManagerDependencies & Required<Pick<IdentityManagerDependencies, "dnsResolver" | "fetchJson">>;

Defined in: packages/sdk/src/index.ts:102

Runtime-neutral dependencies: DNS and JSON fetching must be injected.

---

JsonFetcher

type JsonFetcher = (url, opts?) => Promise<FetchResult>;

Defined in: packages/protocol/src/identity-manager.ts:81

Parameters

url

string

opts?

JsonFetchOptions

Returns

Promise<FetchResult>

---

LifecycleErrorCategory

type LifecycleErrorCategory =
  | "GENESIS_REQUIRED"
  | "DUPLICATE_ISSUANCE"
  | "INVALID_ISSUANCE"
  | "TERMINAL_STATE"
  | "DOMAIN_MISMATCH"
  | "KEY_CONTINUITY"
  | "INVALID_REVOCATION_REASON"
  | "INVALID_MIGRATION"
  | "SNAPSHOT_EMPTY"
  | "SNAPSHOT_NON_PREFIX"
  | "UNSUPPORTED_EVENT"
  | "CHAIN_CONTINUITY"
  | "INVALID_EVIDENCE"
  | "INCOMPLETE_STREAM";

Defined in: packages/protocol/src/errors.ts:26

Stable, language-neutral categories used by lifecycle conformance vectors.

---

LogEvent

type LogEvent =
  | IssuanceEvent
  | KeyRotationEvent
  | RevocationEvent
  | RetirementEvent
  | MigrationEvent
  | DelegationEvent;

Defined in: packages/protocol/src/log-events.ts:122

---

LogEventType

type LogEventType = LogEvent["type"];

Defined in: packages/protocol/src/log-events.ts:130

---

LogRef

type LogRef = string;

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

---

LogSignerRole

type LogSignerRole =
  | "Entity"
  | "Operational"
  | "OperationalCountersignature"
  | "PreviousOperational"
  | "NewOperational";

Defined in: packages/protocol/src/log.ts:4

---

ManagedIssuanceSubmission

type ManagedIssuanceSubmission =
  | SubmissionResult
  | {
  entryHash: string;
  errorCode?: string;
  state: "indeterminate";
};

Defined in: packages/sdk/src/managed-issuance.ts:44

---

MaxKeyAge

type MaxKeyAge = "24h" | "7d" | "30d" | "90d";

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

---

RevocationReason

type RevocationReason =
  | "keyCompromise"
  | "policyViolation"
  | "superseded"
  | "cessationOfOperation";

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

Variables

DEFAULT_PUBLISH_PROFILE

const DEFAULT_PUBLISH_PROFILE: "dnsid-draft-01" = DNSID_DRAFT01_VERSION;

Defined in: packages/protocol/src/txt-record.ts:8

---

DNSID_DRAFT01_VERSION

const DNSID_DRAFT01_VERSION: "dnsid-draft-01" = 'dnsid-draft-01';

Defined in: packages/protocol/src/txt-record.ts:7

Immutable selector for submitted draft-ihsanullah-dnsid-01.

---

DNSID_VERSION

const DNSID_VERSION: "DNSid1" = 'DNSid1';

Defined in: packages/protocol/src/txt-record.ts:5

Pre-RFC moving verification selector. Never published while version 1 is a draft.

---

JWKS_MAX_RESPONSE_BYTES

const JWKS_MAX_RESPONSE_BYTES: number;

Defined in: packages/protocol/src/identity-manager.ts:71

---

SDK_CONFORMANCE

const SDK_CONFORMANCE: SDKConformance;

Defined in: packages/sdk/src/conformance.ts:24

Exact DNSid profile and log-binding behavior implemented by this SDK release.

---

sha256Bytes

const sha256Bytes: TRet<CHash<_SHA256>>;

Defined in: node_modules/@noble/hashes/sha2.d.ts:113

SHA2-256 hash function from RFC 4634. In JS it’s the fastest: even faster than Blake3. Some info:

• Trying 2^128 hashes would get 50% chance of collision, using birthday attack.
• BTC network is doing 2^70 hashes/sec (2^95 hashes/year) as per 2025.
• Each sha256 hash is executing 2^18 bit operations.
• Good 2024 ASICs can do 200Th/sec with 3500 watts of power, corresponding to 2^36 hashes/joule.

Param

msg

message bytes to hash

Param

opts

Reserved hash options.

Returns

Digest bytes.

Example

Hash a message with SHA2-256.

sha256(new Uint8Array([97, 98, 99]));

---

SIGNING_ALGS

const SIGNING_ALGS: Set<string>;

Defined in: packages/protocol/src/jwks.ts:6

---

STATUS_MAX_RESPONSE_BYTES

const STATUS_MAX_RESPONSE_BYTES: number;

Defined in: packages/protocol/src/identity-manager.ts:72

---

SUPPORTED_PUBLISH_PROFILES

const SUPPORTED_PUBLISH_PROFILES: readonly ["dnsid-draft-01"];

Defined in: packages/protocol/src/txt-record.ts:9

---

SUPPORTED_VALIDATION_PROFILES

const SUPPORTED_VALIDATION_PROFILES: readonly ["dnsid-draft-01", "DNSid1"];

Defined in: packages/protocol/src/txt-record.ts:10

Functions

activeStatusDocument()

function activeStatusDocument(lastTransitionAt?): AgentStatus;

Defined in: packages/protocol/src/agent-status.ts:16

Builds a simple ACTIVE status document for demos/tests that do not model lifecycle state.

Parameters

lastTransitionAt?

Date = ...

Returns

AgentStatus

---

canonicalIssuanceBinding()

function canonicalIssuanceBinding(event): Uint8Array;

Defined in: packages/protocol/src/identity-manager.ts:1082

Canonical bytes covered by BOTH the entity signature and the operational countersignature of a draft-01 bilateral ISSUANCE event. Both signatures MUST cover identical content, so this is the single source of that content.

ponytail: minimal, fixed-order line encoding — no JSON key-ordering traps. Replace with the spec’s canonicalization/test vectors once they land.

Parameters

event

IssuanceEvent

Returns

Uint8Array

---

createIdentityManager()

function createIdentityManager(config, deps): IdentityManager;

Defined in: packages/sdk/src/index.ts:126

Creates a DNSid IdentityManager from explicitly injected runtime dependencies.

The root @dnsid-ai/sdk entrypoint is runtime-neutral: callers provide DNS, HTTPS/JSON fetching, key storage/signing, cache, and log implementations appropriate for Node, browsers, workers, wallets, HSMs, or application backends. Omit config.identity for a verification-only manager (see createIdentityVerifier).

Parameters

config

DnsidConfig

deps

CreateIdentityManagerDependencies

Returns

IdentityManager

Example

import { createIdentityManager } from '@dnsid-ai/sdk';

const idm = createIdentityManager({ identity, verification }, {
  keyProvider,       // operational key
  entityKeyProvider, // entity key
  dnsResolver,       // DNSSEC-aware resolver
  fetchJson,
});
const verified = await idm.verifyDomain('agent.example');

---

createIdentityVerifier()

function createIdentityVerifier(config, deps): IdentityManager;

Defined in: packages/sdk/src/index.ts:136

Creates a verification-only IdentityManager: same constructor, config.identity omitted.

The returned manager supports identity verification, verified log loading, and cache eviction. Local signing, publication, and lifecycle mutation methods throw ArgumentError.

Parameters

config

Omit<DnsidConfig, "identity">

deps

Omit<CreateIdentityManagerDependencies, "keyProvider" | "entityKeyProvider">

Returns

IdentityManager

---

fromBase64Url()

function fromBase64Url(b64): Uint8Array;

Defined in: packages/protocol/src/utils.ts:150

Decodes a base64url string (accepts both padded and unpadded forms) to Uint8Array.

Parameters

b64

string

Returns

Uint8Array

---

isDomainName()

function isDomainName(value): boolean;

Defined in: packages/protocol/src/utils.ts:90

Checks whether a string is a valid domain name (for gi consistency checks). Returns true if the value looks like a domain name (as opposed to a URI or other identifier).

Parameters

value

string

Returns

boolean

---

issueManagedIdentity()

function issueManagedIdentity(options): Promise<ManagedIssuanceState>;

Defined in: packages/sdk/src/managed-issuance.ts:109

Starts one durable managed setup operation, or resumes the already persisted one.

Parameters

options

IssueManagedIdentityOptions

Returns

Promise<ManagedIssuanceState>

---

isTransientVerificationError()

function isTransientVerificationError(error): boolean;

Defined in: packages/protocol/src/retry.ts:26

Returns true when the error is a transient DNSid verification failure.

Parameters

error

unknown

Returns

boolean

---

jwkSignatureAlg()

function jwkSignatureAlg(key): string;

Defined in: packages/protocol/src/jwks.ts:37

Parameters

key

DnsIdJWK

Returns

string

---

jwkThumbprint()

function jwkThumbprint(key): Promise<string>;

Defined in: packages/protocol/src/jwks.ts:218

Computes the RFC 7638 JWK thumbprint of a key. Returns unpadded base64url (RFC 7515 §2).

Lifecycle log bindings MUST use thumbprints, not kid values, as the durable key identifier.

Parameters

key

DnsIdJWK

Returns

Promise<string>

---

keySetsShareKeyMaterial()

function keySetsShareKeyMaterial(a, b): Promise<boolean>;

Defined in: packages/protocol/src/jwks.ts:247

Returns true if any key in a shares an RFC 7638 JWK thumbprint with any key in b.

draft-01 §Two-Key Separation requires the ek and ku JWK Sets to be pairwise thumbprint-disjoint, even for self-accounted DNSids — a verifier MUST NOT infer self-accounting from key equality, so this check does not special-case any relationship between the two sets.

Throws a normalized ValidationError if any key in either set is too malformed to thumbprint.

Parameters

a

JWKS

b

JWKS

Returns

Promise<boolean>

---

matchesDnsName()

function matchesDnsName(san, fqdn): boolean;

Defined in: packages/protocol/src/utils.ts:208

RFC 9525 §4 dNSName SAN matching. Returns true when at least one SAN entry matches the given FQDN. Supports case-insensitive comparison, trailing-dot normalisation, and wildcard labels (only leftmost *. matching one or more labels at depth > 0).

Parameters

san

string[]

fqdn

string

Returns

boolean

---

normalizeFQDN()

function normalizeFQDN(name, agentFQDN?): string;

Defined in: packages/protocol/src/utils.ts:18

Converts IDNA U-labels to A-label punycode, lowercases ASCII, strips one trailing root dot, and validates DNS label constraints.

Parameters

name

string

agentFQDN?

boolean = false

Returns

string

Throws

ValidationError if the name is empty, contains empty labels, has any label over 63 octets, exceeds the 253-octet DNS limit, or (when agentFQDN=true) exceeds the 246-octet DNSid agent limit.

---

normalizePrivateAddressHost()

function normalizePrivateAddressHost(entry): string;

Defined in: packages/protocol/src/identity-manager.ts:171

Validates one TransportConfig.privateAddressHosts entry and returns it normalized: lowercase, no trailing dot, leading dot preserved for suffix entries such as .test. IP literals, ports, schemes, paths, credentials, and empty strings are rejected with ArgumentError.

Parameters

entry

string

Returns

string

---

parseCompactJose()

function parseCompactJose(token): object;

Defined in: packages/protocol/src/strict-json.ts:31

Standalone JOSE limits: 1 MiB compact token, 16 KiB encoded header.

Parameters

token

string

Returns

object

header

header: Record<string, unknown>;

parts

parts: [string, string, string];

payload

payload: Uint8Array;

signature

signature: Uint8Array;

---

parseJoseObject()

function parseJoseObject(bytes): Record<string, unknown>;

Defined in: packages/protocol/src/strict-json.ts:52

Parameters

bytes

Uint8Array

Returns

Record<string, unknown>

---

parseJsonNoDuplicateMembers()

function parseJsonNoDuplicateMembers(bytes): unknown;

Defined in: packages/protocol/src/strict-json.ts:5

UTF-8 JSON with duplicate member rejection, including escaped member names.

Parameters

bytes

Uint8Array

Returns

unknown

---

parseKaDuration()

function parseKaDuration(ka): number;

Defined in: packages/protocol/src/utils.ts:166

Parses a duration string (as used in the ka tag) to milliseconds. Valid values: “24h”, “7d”, “30d”, “90d”.

Parameters

ka

string

Returns

number

---

parseKeyId()

function parseKeyId(keyId): object;

Defined in: packages/protocol/src/utils.ts:110

Parses the DNSid SDK’s cross-profile compound key ID convention: “{domain}#{kid}”.

This is an SDK/profile convention used by packages such as @dnsid-ai/jose and @dnsid-ai/http-signatures to bind a profile-level key reference to a DNSid agent FQDN plus a JWKS “kid”. It is not a DNSid protocol wire-format requirement; the protocol itself only requires JWKS keys to carry “kid” values.

Splits on the first ’#’, normalizes the domain side with normalizeFQDN(), and rejects if either side is empty or the kid side contains another ’#’.

Parameters

keyId

string

Returns

object

domain

domain: string;

kid

kid: string;

Throws

ArgumentError if the key ID is malformed.

---

requireLocalDomain()

function requireLocalDomain(manager): string;

Defined in: packages/protocol/src/identity-manager.ts:105

Returns config.identity.domain or throws ArgumentError for verification-only managers.

Parameters

manager

SigningIdentityManager

Returns

string

---

resumeManagedIssuance()

function resumeManagedIssuance(options): Promise<ManagedIssuanceState>;

Defined in: packages/sdk/src/managed-issuance.ts:143

Resumes only the durable operation, reusing its preparation key or exact completed bytes.

Parameters

options

ResumeManagedIssuanceOptions

Returns

Promise<ManagedIssuanceState>

---

resumeManagedOperationalKeyRotation()

function resumeManagedOperationalKeyRotation(options): Promise<ManagedKeyRotationResult>;

Defined in: packages/sdk/src/managed-key-rotation.ts:161

Retries only the persisted completed bytes and activates on acceptance.

Parameters

options

ResumeManagedOperationalKeyRotationOptions

Returns

Promise<ManagedKeyRotationResult>

---

retryTransientVerification()

function retryTransientVerification<T>(operation, options?): Promise<T>;

Defined in: packages/protocol/src/retry.ts:35

Retries an operation using exponential backoff, but only for transient VerificationError failures by default. Integrity and policy failures are never retried unless callers explicitly override shouldRetry.

Type Parameters

T

T

Parameters

operation

() => Promise<T>

options?

RetryBackoffOptions = {}

Returns

Promise<T>

---

rotateManagedOperationalKey()

function rotateManagedOperationalKey(options): Promise<ManagedKeyRotationResult>;

Defined in: packages/sdk/src/managed-key-rotation.ts:99

Runs C2SP registry-managed rotation. The registry owns managed ku publication and append reconciliation; local activation happens only after an accepted result for the exact, durably persisted bytes while application signing is paused.

Parameters

options

RotateManagedOperationalKeyOptions

Returns

Promise<ManagedKeyRotationResult>

---

toArrayBuffer()

function toArrayBuffer(bytes): Uint8Array<ArrayBuffer>;

Defined in: packages/protocol/src/utils.ts:181

Returns a Uint8Array view over the same memory — no copy. Required because WebCrypto’s BufferSource only accepts ArrayBuffer-backed views, not the default Uint8Array that TypeScript infers.

Parameters

bytes

Uint8Array

Returns

Uint8Array<ArrayBuffer>

---

toBase64Url()

function toBase64Url(bytes): string;

Defined in: packages/protocol/src/utils.ts:138

Encodes a Uint8Array to unpadded base64url (RFC 7515 §2).

Parameters

bytes

Uint8Array

Returns

string

---

validateAgentStatus()

function validateAgentStatus(data): AgentStatus;

Defined in: packages/protocol/src/agent-status.ts:23

Validates the DNSid JSON status profile returned by the su endpoint.

Parameters

data

unknown

Returns

AgentStatus

---

validateDnsidConfig()

function validateDnsidConfig(config?): DnsidConfig;

Defined in: packages/protocol/src/identity-manager.ts:296

Validates and snapshots a DnsidConfig. Shared by every constructor and loader so all initialization paths apply identical defaults and rejections.

Parameters

config?

unknown = {}

Returns

DnsidConfig

---

verifyBilateralBinding()

function verifyBilateralBinding(
   event,
   record,
   currentEntityKey
): Promise<{
  initialOperationalThumbprint: string;
}>;

Defined in: packages/protocol/src/identity-manager.ts:1119

draft-01 step-5 bilateral binding check. ISSUANCE is bilateral: it is only valid when BOTH the accountable-entity record-signing key (ek) and the initial operational key (ku) signed the same canonical binding, and that binding corresponds to the TXT record and current key material.

Verifies, against key material recorded IN THE EVENT:

1. Each slot’s thumbprint equals jwkThumbprint(jwk) (the canonical binding only commits to the thumbprint, so the embedded JWK must be pinned to it).
2. entitySig under entityKey, and operationalSig under operationalKey.
3. Same DNSid FQDN and same gi as the record.
4. The ISSUANCE-recorded entity key is the key currently at ek.

It does NOT reject a rotated ku: the current operational key may be the initial key OR a key linked to it by KEY_ROTATION continuity. That linkage (and entity KEY_ROTATION linkage) is verified separately by LogReader.verifyOperationalContinuity, which runs unconditionally in the draft-01 path of verifyDomain. The recorded initial operational thumbprint is returned so the caller can hand it to that continuity check.

Parameters

event

IssuanceEvent

record

DnsIdTxtRecord

currentEntityKey

DnsIdJWK

Returns

Promise<{ initialOperationalThumbprint: string; }>

---

verifyWithKey()

function verifyWithKey(
   signingInput,
   signature,
   key,
   expectedAlg?
): Promise<boolean>;

Defined in: packages/protocol/src/utils.ts:228

Verifies a signing input against a raw signature using a public JWK. Returns true if the signature is valid, false otherwise.

Parameters

signingInput

string | Uint8Array<ArrayBufferLike>

signature

Uint8Array

key

DnsIdJWK

expectedAlg?

string

Returns

Promise<boolean>

---

waitForVerification()

function waitForVerification<T>(operation, signal): Promise<T>;

Defined in: packages/protocol/src/verification-budget.ts:43

Races cooperative work against cancellation, including already-aborted invocations.

Type Parameters

T

T

Parameters

operation

(signal) => Promise<T>

signal

AbortSignal

Returns

Promise<T>

---

withVerificationBudget()

function withVerificationBudget<T>(operation, options?): Promise<T>;

Defined in: packages/protocol/src/verification-budget.ts:10

Runs an invocation with a shared cancellation signal; child operations must not restart its budget.

Type Parameters

T

T

Parameters

operation

(signal) => Promise<T>

options?

VerificationOptions = {}

Returns

Promise<T>

References

awaitRegistryManagedPublication

Re-exports awaitRegistryManagedPublication

---

createHttpSignaturesProfile

Re-exports createHttpSignaturesProfile

---

createJoseProfile

Re-exports createJoseProfile

---

createWebBotAuthProfile

Re-exports createWebBotAuthProfile

---

DEFAULT_REGISTRY_URL

Re-exports DEFAULT_REGISTRY_URL

---

HttpSignaturesProfile

Re-exports HttpSignaturesProfile

---

JoseProfile

Re-exports JoseProfile

---

PreparedEventSubmissionError

Re-exports PreparedEventSubmissionError

---

publishClientControlledRecord

Re-exports publishClientControlledRecord

---

publishToRegistry

Re-exports publishToRegistry

---

RegistryClient

Re-exports RegistryClient

---

RegistryWorkflowError

Re-exports RegistryWorkflowError

---

WebBotAuthProfile

Re-exports WebBotAuthProfile

Classes

Documented on Core SDK: classes:

• ArgumentError
• DnsIdTxtRecord
• DomainLog
• DomainSnapshot
• IdentityManager
• InMemoryIdentityCache
• JWKS
• LogRegistry
• ManagedIssuanceActivationError
• ManagedIssuanceSubmissionError
• ManagedKeyRotationActivationError
• ManagedKeyRotationSubmissionError
• NoopLogReader
• ParseError
• ValidationError
• VerificationError
• VerifiedDomain

Interfaces

Documented on Core SDK: interfaces:

• AgentStatus
• C2spIssuanceEvent
• DelegationEvent
• DnsidConfig
• DnsIdJWK
• DNSResolver
• FetchResult
• IdentityCache
• IdentityConfig
• IdentityManagerDependencies
• IdentityResolver
• IssuanceEvent
• IssuanceKeySlot
• IssueManagedIdentityOptions
• JsonFetchOptions
• KeyProvider
• KeyRotationEvent
• Log
• LoggedStateEvidence
• LogReader
• ManagedIssuanceCoordination
• ManagedIssuanceRegistry
• ManagedIssuanceState
• ManagedKeyRotationRegistry
• ManagedKeyRotationResult
• MigrationEvent
• OperationalKeyRotationOptions
• OperationalKeyRotationResult
• ResumeManagedIssuanceOptions
• ResumeManagedOperationalKeyRotationOptions
• RetirementEvent
• RetryBackoffOptions
• RevocationEvent
• RotateManagedOperationalKeyOptions
• SDKConformance
• SigningIdentityManager
• TLSCertificate
• TransportConfig
• TrustedEntity
• TXTRecord
• VerificationConfig
• VerificationOptions