TypeScript: @dnsid-ai/protocol

Protocol core for DNSid TypeScript packages.

Use this package when you want the DNSid protocol engine and contracts without runtime-specific defaults.

Responsibilities

IdentityManager
DNSid TXT record parsing, validation, serialization, and canonicalization
JWKS validation and JWK thumbprints
Protocol data types and strict protocol status validation
DNS, fetch, cache, key-provider, and log contracts
Common DNSid errors and verification primitives

This package intentionally does not include Node DNS/HTTPS transport, local filesystem key storage, environment-variable loading, registry-specific lifecycle behavior, or profile-specific conveniences.

Install

npm install @dnsid-ai/protocol

Example

import { IdentityManager } from '@dnsid-ai/protocol';

// config is data only; runtime objects are injected as dependencies.
const idm = new IdentityManager(
  {
    identity,                                  // omit for a verification-only manager
    verification: { dnssecMode: 'required', trustedEntities: [{ governanceId: 'agent.example' }] },
  },
  { keyProvider, entityKeyProvider, logRegistry, dnsResolver, cache, fetchJson },
);

verification.trustedEntities is an optional counterparty allowlist checked on every verifyDomain return (including cache hits) after protocol verification. Entries match the verified record’s governance ID exactly; optional entityKeyThumbprints pin the current record-signing key. Omit it to make no acceptance decision; [] denies all. A denial raises VerificationError with code CounterpartyNotAccepted carrying only the observed verifiedGovernanceId/verifiedEntityKeyThumbprint.

The core has no default DNS or HTTPS implementation, so config.transport settings are rejected here; use @dnsid-ai/sdk/node, which consumes them for its defaults.

For ergonomic Node.js defaults, use @dnsid-ai/sdk/node with @dnsid-ai/transport.

Verification context and limits

verifyDomain(domain, peerCert?, { timeoutMs?, signal? }) has a 30-second whole-operation default. Each coalesced caller retains its deadline; shared identity work also has a 30-second cap and is canceled when its last caller leaves. DNS, HTTPS redirects, and lifecycle evidence share the remaining budget. Injected resolvers, fetchers, and log factories must honor the supplied signal, keep trust configuration immutable, and bound their responses before allocation. Native system DNS work may finish in the background under the platform’s finite resolver retry limits; canceled verification does not proceed or populate caches. TXT input is limited to 65,535 characters/1,024 chunks; JWKS and status fetches request 256 KiB and 16 KiB limits respectively.

Injected caches are namespaced per manager, never shared by domain alone. Configuration and log-method selection are snapshotted at construction; use a new manager for changed trust policy. DNS expiry starts at lookup acquisition, not verification completion. Status refresh never extends it, zero-TTL answers are never reused, and DNS/TLS/key-age bounds are checked before returning.

High-value operation log checks

verifyDomain() validates the bilateral ISSUANCE binding for every identity. If the verified record advertises fl=logchk, the application must additionally perform a current non-revocation check before relying on the identity for an operation it classifies as high value or irreversible:

const verified = await idm.verifyDomain('agent.example');
if (verified.requiresLogCheck()) {
  const evidence = await verified.verifyNonRevocation();
  console.log(evidence.logReference, evidence.freshnessTime);
}

Operation classification remains application policy. Call verifyNonRevocation() regardless of the advertised flag when local policy requires it. The returned evidence identifies the verified history bounds, completeness mechanism, checkpoint, and freshness boundary; it does not contain the events. Log unavailability or stale evidence fails the check closed.

Protocol core for the DNSid TypeScript monorepo.

@dnsid-ai/protocol provides the DNSid protocol engine and contracts: TXT identity record parsing/validation/canonicalization, JWKS validation and thumbprints, the IdentityManager verification and lifecycle engine, transparency log contracts, strict agent status validation, and common DNSid error types.

The package is runtime-neutral: DNS resolution, JSON fetching, key storage/signing, and caching are injected through the DNSResolver, JsonFetcher, KeyProvider, and IdentityCache interfaces. Node conveniences live in @dnsid-ai/sdk/node, registry workflows in @dnsid-ai/registry.

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

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

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

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

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

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: 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

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>

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:

Each slot’s thumbprint equals jwkThumbprint(jwk) (the canonical binding only commits to the thumbprint, so the embedded JWK must be pinned to it).
entitySig under entityKey, and operationalSig under operationalKey.
Same DNSid FQDN and same gi as the record.
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

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>

Classes

Documented on Protocol core: classes:

Interfaces

Documented on Protocol core: interfaces:

Known Systems AI, Inc. is an affiliate of Identity Digital that solves identity fragmentation for the AI agent economy. As agents become more autonomous and interoperable, they introduce risk and security challenges existing systems weren't designed for—starting with a consistent way to verify ownership across organizational boundaries. Known Systems AI, Inc. combines Identity Digital's DNS expertise with an Immutable Log to establish a global coordination layer for AI agent identity, and participates in open standards communities, including the Linux Foundation. For more information, visit DNSid.ai.