TypeScript: @dnsid-ai/oidc

DNSid OIDC federation helpers for server-side token minting and verification.

Install

npm install @dnsid-ai/oidc

For Node.js local key loading, also install the aggregate SDK:

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

Mint an OIDC access token from server code

Use mintOIDCToken() when an agent service needs to call another service, gateway, or tool with a DNSid OIDC bearer token.

import { LocalKeyProvider } from '@dnsid-ai/sdk/node';
import { mintOIDCToken } from '@dnsid-ai/oidc';

const agentDomain = process.env.DNSID_DOMAIN!;
const audience = process.env.AGENTCORE_GATEWAY_AUDIENCE!;
const issuer = process.env.DNSID_OIDC_ISSUER;

const keyProvider = await LocalKeyProvider.load(
  process.env.DNSID_KEY_STORE ?? '.dnsid/keys.json',
);

const token = await mintOIDCToken({
  domain: agentDomain,
  keyProvider,
  audience,
  scopes: ['openid', 'dnsid'],
  issuer,
  serverUrl: issuer ? undefined : process.env.DNSID_SERVER_URL,
  timeoutMs: 5000,
});

await fetch(process.env.AGENTCORE_GATEWAY_URL!, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${token.accessToken}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ input: 'status' }),
});

Configure either:

issuer for explicit OIDC issuer discovery, which uses the discovered same-origin token_endpoint.
serverUrl for DNSid CLI-compatible server mode, which discovers the issuer from the server but posts to <serverUrl>/token.
issuer plus tokenEndpoint to bypass discovery when both values are already trusted configuration.

scope accepts the CLI-style space-separated string. scopes accepts an array and joins it with spaces. Empty scope values are omitted so the DNSid server default applies.

Private JWK input

Applications with private JWK material can use privateJwk directly:

import { mintOIDCToken } from '@dnsid-ai/oidc';

const token = await mintOIDCToken({
  domain: 'agent.example',
  privateJwk,
  issuer: 'https://oidc.example',
  audience: 'https://gateway.example',
});

If the JWK has no kid, the SDK computes the RFC 7638 JWK thumbprint and uses that as the JWT header kid.

Verification boundaries

verifyOIDCToken(token, { issuer, audience, peerCert, timeoutMs, signal }) uses a 30-second overall default across discovery, JWKS and DNSid subject verification. Supply trusted current-peer evidence when the subject requires fl=mtls; it is forwarded on every invocation, including cache hits. Strict compact JSON parsing rejects duplicate members and malformed headers or NumericDates before discovery. Tokens are capped at 1 MiB, encoded headers at 16 KiB, and fetched JSON at 1 MiB. Expiration is rechecked after subject discovery without skew grace. Zero skew is respected; invalid explicit lifetimes fail. Injected transports/resolvers must honor cancellation and bounded-response contracts.

Server-side only

Do not mint DNSid OIDC tokens in browser or client code. The private key or signing provider must stay on trusted server infrastructure such as an AgentCore-hosted service, backend worker, KMS-backed signer, HSM, or equivalent server-side runtime.

Minting a token is not the trust decision. Receivers still verify the DNSid OIDC token, issuer, audience, signature, and DNSid subject status according to their verifier policy.

DNSid OIDC federation profile: minting OIDC access tokens from a DNSid identity (JWT bearer client assertions signed with the agent’s operational key) and verifying OIDC tokens back to DNSid identity records.

This package is deliberately NOT re-exported by the runtime-neutral root @dnsid-ai/sdk export because its default transport is Node-bound (SSRF-safe fetch backed by node:dns lookups). Import it directly from @dnsid-ai/oidc.

Security notes:

Never mint OIDC tokens in browser/client code — private keys stay server-side.
Passing a custom fetch replaces the safe default transport, so only inject trusted transports that enforce equivalent DNS/SSRF checks.

Classes

OAuthError

Defined in: packages/oidc/src/index.ts:236

OAuth 2.0 error returned by a token endpoint (e.g. invalid_grant), carrying the raw error and error_description members from the response body.

Extends

Error

Constructors

Constructor

new OAuthError(error?, errorDescription?): OAuthError;

Defined in: packages/oidc/src/index.ts:242

Parameters

error?

string

errorDescription?

string

Returns

OAuthError

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

Error.cause

error?

readonly optional error?: string;

Defined in: packages/oidc/src/index.ts:238

The RFC 6749 error code, when the endpoint provided one.

errorDescription?

readonly optional errorDescription?: string;

Defined in: packages/oidc/src/index.ts:240

Human-readable error description, when the endpoint provided one.

message

message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Error.message

name

name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1074

Inherited from

Error.name

stack?

optional stack?: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.stack

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:67

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

OIDCProfile

Defined in: packages/oidc/src/index.ts:443

DNSid OIDC federation profile for a single agent: mints client assertions, exchanges them for access tokens, and verifies inbound OIDC tokens back to DNSid identity records.

Token minting requires the agent’s private operational key — keep it server-side; never construct a profile in browser/client code.

Constructors

Constructor

new OIDCProfile(opts): OIDCProfile;

Defined in: packages/oidc/src/index.ts:461

Parameters

opts

OIDCProfileOptions

Returns

OIDCProfile

Throws

ArgumentError if domain is not a valid agent FQDN.

Methods

createOIDCAssertion()

createOIDCAssertion(opts): Promise<string>;

Defined in: packages/oidc/src/index.ts:485

Mints a signed JWT bearer client assertion for the given issuer (iss/sub/fqdn = agent domain, aud = issuer, fresh jti).

Parameters

opts

OIDCAssertionOptions

Returns

Promise<string>

Throws

ArgumentError if the issuer URL is invalid, the expiry is not positive or exceeds the maximum lifetime, or additionalClaims override a reserved claim.

Throws

ValidationError if the operational signing key is unsupported for JWS.

Throws

VerificationError (SignatureInvalid) if the produced signature does not verify against the active operational key.

discoverOIDCIssuer()

discoverOIDCIssuer(issuer, options?): Promise<OIDCDiscoveryDocument>;

Defined in: packages/oidc/src/index.ts:502

Fetches and validates the issuer’s discovery document. The document’s issuer must match exactly, and token_endpoint/jwks_uri must share the issuer’s origin.

Parameters

issuer

string

options?

VerificationOptions = {}

Returns

Promise<OIDCDiscoveryDocument>

Throws

ArgumentError if the issuer is not an exact HTTPS URL.

Throws

VerificationError if the fetch fails, redirects, or the document is invalid.

exchangeOIDCToken()

exchangeOIDCToken(opts): Promise<OIDCTokenResponse>;

Defined in: packages/oidc/src/index.ts:521

Discovers the issuer and performs the RFC 7523 JWT bearer exchange. When assertion is supplied it is presented as-is (its aud must exactly match the discovered issuer); otherwise a fresh assertion is minted.

Parameters

opts

OIDCTokenExchangeOptions

Returns

Promise<OIDCTokenResponse>

The normalized token response.

Throws

ArgumentError if audience is missing or a supplied assertion is not a valid JWT addressed to the issuer.

Throws

VerificationError if discovery or transport fails, or the response is malformed.

Throws

OAuthError if the token endpoint returns an OAuth error response.

getOIDCToken()

getOIDCToken(opts): Promise<OIDCTokenResponse>;

Defined in: packages/oidc/src/index.ts:552

Like OIDCProfile.exchangeOIDCToken but always mints a fresh assertion, ignoring any supplied one.

Parameters

opts

OIDCTokenExchangeOptions

Returns

Promise<OIDCTokenResponse>

verifyOIDCToken()

verifyOIDCToken(token, opts): Promise<VerifiedOIDCSubject>;

Defined in: packages/oidc/src/index.ts:573

Verifies an OIDC token end-to-end: issuer allow-list, exact audience match, header and claim hygiene, signature against the issuer’s published JWKS (restricted to allowedTokenAlgorithms), and timestamp checks with the configured clock skew. Unless verifyDnsidSubject is false, the token subject is then verified as a DNSid identity record via the profile’s identityResolver.

Parameters

token

string

opts

VerifyOIDCTokenOptions

Returns

Promise<VerifiedOIDCSubject>

The verified subject, claims, and (unless skipped) the DNSid verification result for the subject domain.

Throws

ArgumentError if the issuer URL is invalid or audience is missing.

Throws

VerificationError with a VerificationCode (RecordInvalid, SignatureInvalid, or TLSError) identifying the first check that failed — including when the issuer is not in allowedIssuers, or when subject verification is requested without an identityResolver.

fromIdentityManager()

static fromIdentityManager(identityManager, oidc?): OIDCProfile;

Defined in: packages/oidc/src/index.ts:445

Builds a profile sharing an identity manager’s domain, operational key provider, and identity resolver.

Parameters

Mints OIDC access tokens for a DNSid agent via the RFC 7523 JWT bearer grant: signs a client assertion with the agent’s operational key, then exchanges it at the issuer’s token endpoint.

Server-side only — requires the agent’s private operational key. Prefer a long-lived minter over repeated mintOIDCToken calls when minting more than once against the same issuer.

Constructors

Constructor

new OIDCTokenMinter(opts): OIDCTokenMinter;

Defined in: packages/oidc/src/index.ts:309

Parameters

opts

OIDCTokenMinterOptions

Returns

OIDCTokenMinter

Throws

ArgumentError if domain is not a valid agent FQDN, the endpoint options mix modes (see OIDCTokenEndpointOptions), or timeoutMs is not a positive number.

Methods

createAssertion()

createAssertion(opts): Promise<string>;

Defined in: packages/oidc/src/index.ts:342

Mints a signed JWT bearer client assertion for the given issuer (iss/sub/fqdn = agent domain, aud = issuer, fresh jti).

Parameters

opts

OIDCAssertionOptions

Returns

Promise<string>

Throws

ArgumentError if the issuer URL is invalid, the expiry is not positive or exceeds the maximum lifetime, or additionalClaims override a reserved claim.

Throws

ValidationError if the operational signing key is unsupported for JWS.

Throws

VerificationError (SignatureInvalid) if the produced signature does not verify against the active operational key.

mintToken()

mintToken(opts): Promise<OIDCTokenResponse>;

Defined in: packages/oidc/src/index.ts:360

Resolves the token endpoint (per the configured or per-call endpoint mode), mints a fresh assertion, and performs the JWT bearer token exchange.

Parameters

opts

OIDCTokenMintOptions

Returns

Promise<OIDCTokenResponse>

The normalized token response.

Throws

ArgumentError if audience is missing or the options are inconsistent.

Throws

VerificationError if discovery or transport fails, the target resolves to an unsafe address, or the response is malformed.

Throws

OAuthError if the token endpoint returns an OAuth error response.

Interfaces

CreateOIDCTokenMinterOptions

Defined in: packages/oidc/src/index.ts:185

Options for createOIDCTokenMinter: provide exactly one of keyProvider or privateJwk.

Extends

Omit<OIDCTokenMinterOptions, "keyProvider">

Properties

allowHttpLoopbackIssuer?

optional allowHttpLoopbackIssuer?: boolean;

Defined in: packages/oidc/src/index.ts:181

Permit plain-HTTP loopback issuers (localhost, 127.x, ::1) for local testing. Defaults to false.

Inherited from

OIDCTokenMinterOptions.allowHttpLoopbackIssuer

assertionLifetime?

optional assertionLifetime?: number;

Defined in: packages/oidc/src/index.ts:175

Lifetime of minted client assertions, in seconds. Defaults to 300.

Inherited from

OIDCTokenMinterOptions.assertionLifetime

defaultScope?

optional defaultScope?: string;

Defined in: packages/oidc/src/index.ts:173

Scope used when a mint call does not specify one. Defaults to ‘openid’.

Inherited from

OIDCTokenMinterOptions.defaultScope

discoveryUrl?

optional discoveryUrl?: string;

Defined in: packages/oidc/src/index.ts:159

Explicit discovery document URL; only valid alongside issuer or serverUrl.

Inherited from

OIDCTokenEndpointOptions.discoveryUrl

domain

domain: string;

Defined in: packages/oidc/src/index.ts:167

Agent FQDN; becomes the iss/sub/fqdn claims of minted assertions.

Inherited from

OIDCTokenMinterOptions.domain

fetch?

optional fetch?: {
  (input, init?): Promise<Response>;
  (input, init?): Promise<Response>;
};

Defined in: packages/oidc/src/index.ts:171

Custom fetch replaces the SSRF-safe Node default; inject only trusted/test transports with equivalent DNS safety.

Call Signature

(input, init?): Promise<Response>;

MDN Reference

Parameters

input

URL | RequestInfo

init?

RequestInit

Returns

Promise<Response>

Call Signature

(input, init?): Promise<Response>;

MDN Reference

Parameters

input

string | URL | Request

init?

RequestInit

Returns

Promise<Response>

Inherited from

OIDCTokenMinterOptions.fetch

issuer?

optional issuer?: string;

Defined in: packages/oidc/src/index.ts:155

Exact HTTPS issuer root URL — no path, query, fragment, or trailing slash. Mutually exclusive with serverUrl.

Inherited from

OIDCTokenEndpointOptions.issuer

keyProvider?

optional keyProvider?: KeyProvider;

Defined in: packages/oidc/src/index.ts:187

Provider of the agent’s operational key. Mutually exclusive with privateJwk.

maxAssertionLifetime?

optional maxAssertionLifetime?: number;

Defined in: packages/oidc/src/index.ts:177

Upper bound on any requested assertion lifetime, in seconds. Defaults to 900.

Inherited from

OIDCTokenMinterOptions.maxAssertionLifetime

privateJwk?

optional privateJwk?: OIDCPrivateJWK;

Defined in: packages/oidc/src/index.ts:189

Raw private JWK to sign with, wrapped in an in-memory provider. Mutually exclusive with keyProvider.

serverUrl?

optional serverUrl?: string;

Defined in: packages/oidc/src/index.ts:157

Base server URL used to derive the discovery document and token endpoint. Mutually exclusive with issuer.

Inherited from

OIDCTokenEndpointOptions.serverUrl

timeoutMs?

optional timeoutMs?: number;

Defined in: packages/oidc/src/index.ts:179

Timeout for discovery and token-endpoint requests, in milliseconds. Defaults to 10000.

Inherited from

OIDCTokenMinterOptions.timeoutMs

tokenEndpoint?

optional tokenEndpoint?: string;

Defined in: packages/oidc/src/index.ts:161

Explicit token endpoint URL; requires issuer, must share its origin, and bypasses discovery.

Inherited from

OIDCTokenEndpointOptions.tokenEndpoint

OIDCAssertionOptions

Defined in: packages/oidc/src/index.ts:83

Options for minting a JWT bearer client assertion.

Properties

additionalClaims?

optional additionalClaims?: Record<string, unknown>;

Defined in: packages/oidc/src/index.ts:89

Extra claims to embed. Must not override reserved claims (iss, sub, aud, iat, exp, jti, fqdn).

expiry?

optional expiry?: number;

Defined in: packages/oidc/src/index.ts:87

Assertion lifetime in seconds; overrides the configured default, capped by maxAssertionLifetime.

issuer

issuer: string;

Defined in: packages/oidc/src/index.ts:85

OIDC issuer the assertion is addressed to; becomes the aud claim.

OIDCDiscoveryDocument

Defined in: packages/oidc/src/index.ts:96

The subset of an OIDC discovery document (.well-known/openid-configuration) this package relies on. Additional members are preserved as-is.

Indexable

[key: string]: unknown

Properties

issuer

issuer: string;

Defined in: packages/oidc/src/index.ts:97

jwks_uri

jwks_uri: string;

Defined in: packages/oidc/src/index.ts:99

token_endpoint

token_endpoint: string;

Defined in: packages/oidc/src/index.ts:98

OIDCPrivateJWK

Defined in: packages/oidc/src/index.ts:139

A private JWK used to sign client assertions without a full key provider. Must carry the private d member; keep it server-side only.

Extends

Omit<DnsIdJWK, "kid">

Indexable

[key: string]: unknown

[key: number]: unknown

Properties

d

d: string;

Defined in: packages/oidc/src/index.ts:142

Private key material (base64url).

kid?

optional kid?: string;

Defined in: packages/oidc/src/index.ts:144

Key id published on the derived public key; defaults to the RFC 7638 thumbprint.

kty

kty: string;

Defined in: packages/oidc/src/index.ts:140

OIDCProfileConfig

Defined in: packages/oidc/src/index.ts:49

Tunable OIDC policy for an OIDCProfile. All members are optional; defaults noted per member.

Properties

allowedIssuers?

optional allowedIssuers?: string[];

Defined in: packages/oidc/src/index.ts:61

Exact issuer URLs verifyOIDCToken() accepts. When absent or empty, verification always fails.

allowedTokenAlgorithms?

optional allowedTokenAlgorithms?: string[];

Defined in: packages/oidc/src/index.ts:63

JWS algorithms accepted on inbound OIDC tokens. Defaults to [‘RS256’].

allowHttpLoopbackIssuer?

optional allowHttpLoopbackIssuer?: boolean;

Defined in: packages/oidc/src/index.ts:65

Permit plain-HTTP loopback issuers (localhost, 127.x, ::1) for local testing. Defaults to false.

assertionLifetime?

optional assertionLifetime?: number;

Defined in: packages/oidc/src/index.ts:53

Lifetime of minted client assertions, in seconds. Defaults to 300.

clockSkew?

optional clockSkew?: number;

Defined in: packages/oidc/src/index.ts:57

Clock skew tolerated when validating token timestamps, in seconds. Defaults to 30.

defaultScope?

optional defaultScope?: string;

Defined in: packages/oidc/src/index.ts:51

Scope requested when a token exchange does not specify one. Defaults to ‘openid’.

fetchTimeoutMs?

optional fetchTimeoutMs?: number;

Defined in: packages/oidc/src/index.ts:59

Timeout for discovery, JWKS, and token-endpoint requests, in milliseconds. Defaults to 10000.

maxAssertionLifetime?

optional maxAssertionLifetime?: number;

Defined in: packages/oidc/src/index.ts:55

Upper bound on any requested assertion lifetime, in seconds. Defaults to 900.

OIDCProfileOptions

Defined in: packages/oidc/src/index.ts:69

Constructor options for OIDCProfile.

Properties

domain

domain: string;

Defined in: packages/oidc/src/index.ts:71

Agent FQDN; becomes the iss/sub/fqdn claims of minted assertions.

fetch?

optional fetch?: {
  (input, init?): Promise<Response>;
  (input, init?): Promise<Response>;
};

Defined in: packages/oidc/src/index.ts:77

Custom fetch replaces the SSRF-safe Node default; inject only trusted/test transports with equivalent DNS safety.

Call Signature

(input, init?): Promise<Response>;

MDN Reference

Parameters

input

URL | RequestInfo

init?

RequestInit

Returns

Promise<Response>

Call Signature

(input, init?): Promise<Response>;

MDN Reference

Parameters

input

string | URL | Request

init?

RequestInit

Returns

Promise<Response>

identityResolver?

optional identityResolver?: IdentityResolver;

Defined in: packages/oidc/src/index.ts:75

Resolver used by verifyOIDCToken() to verify token subjects as DNSid identity records.

keyProvider?

optional keyProvider?: KeyProvider;

Defined in: packages/oidc/src/index.ts:73

Provider used to sign client assertions. Omit for a verification-only profile.

oidc?

optional oidc?: OIDCProfileConfig;

Defined in: packages/oidc/src/index.ts:79

OIDC policy overrides; see OIDCProfileConfig.

OIDCTokenEndpointOptions

Defined in: packages/oidc/src/index.ts:153

Selects how the token endpoint is located. Exactly one mode applies: issuer (discovery at the issuer root), serverUrl (discovery relative to a base URL, token endpoint at serverUrl + ‘/token’), or tokenEndpoint (explicit endpoint; requires issuer, must share its origin, skips discovery).

Properties

discoveryUrl?

optional discoveryUrl?: string;

Defined in: packages/oidc/src/index.ts:159

Explicit discovery document URL; only valid alongside issuer or serverUrl.

issuer?

optional issuer?: string;

Defined in: packages/oidc/src/index.ts:155

Exact HTTPS issuer root URL — no path, query, fragment, or trailing slash. Mutually exclusive with serverUrl.

serverUrl?

optional serverUrl?: string;

Defined in: packages/oidc/src/index.ts:157

Base server URL used to derive the discovery document and token endpoint. Mutually exclusive with issuer.

tokenEndpoint?

optional tokenEndpoint?: string;

Defined in: packages/oidc/src/index.ts:161

Explicit token endpoint URL; requires issuer, must share its origin, and bypasses discovery.

OIDCTokenExchangeOptions

Defined in: packages/oidc/src/index.ts:104

Options for OIDCProfile.exchangeOIDCToken() and getOIDCToken().

Properties

assertion?

optional assertion?: string;

Defined in: packages/oidc/src/index.ts:112

Pre-minted client assertion to present; its aud must exactly match the issuer. Minted fresh when absent.

audience

audience: string;

Defined in: packages/oidc/src/index.ts:108

Audience (aud) requested for the access token.

issuer

issuer: string;

Defined in: packages/oidc/src/index.ts:106

Exact OIDC issuer URL to exchange against.

scope?

optional scope?: string;

Defined in: packages/oidc/src/index.ts:110

Space-delimited scope; defaults to the configured defaultScope, then ‘openid’.

OIDCTokenMinterOptions

Defined in: packages/oidc/src/index.ts:165

Constructor options for OIDCTokenMinter.

Extends

OIDCTokenEndpointOptions

Properties

allowHttpLoopbackIssuer?

optional allowHttpLoopbackIssuer?: boolean;

Defined in: packages/oidc/src/index.ts:181

Permit plain-HTTP loopback issuers (localhost, 127.x, ::1) for local testing. Defaults to false.

assertionLifetime?

optional assertionLifetime?: number;

Defined in: packages/oidc/src/index.ts:175

Lifetime of minted client assertions, in seconds. Defaults to 300.

defaultScope?

optional defaultScope?: string;

Defined in: packages/oidc/src/index.ts:173

Scope used when a mint call does not specify one. Defaults to ‘openid’.

discoveryUrl?

optional discoveryUrl?: string;

Defined in: packages/oidc/src/index.ts:159

Explicit discovery document URL; only valid alongside issuer or serverUrl.

Inherited from

OIDCTokenEndpointOptions.discoveryUrl

domain

domain: string;

Defined in: packages/oidc/src/index.ts:167

Agent FQDN; becomes the iss/sub/fqdn claims of minted assertions.

fetch?

optional fetch?: {
  (input, init?): Promise<Response>;
  (input, init?): Promise<Response>;
};

Defined in: packages/oidc/src/index.ts:171

Custom fetch replaces the SSRF-safe Node default; inject only trusted/test transports with equivalent DNS safety.

Call Signature

(input, init?): Promise<Response>;

MDN Reference

Parameters

input

URL | RequestInfo

init?

RequestInit

Returns

Promise<Response>

Call Signature

(input, init?): Promise<Response>;

MDN Reference

Parameters

input

string | URL | Request

init?

RequestInit

Returns

Promise<Response>

issuer?

optional issuer?: string;

Defined in: packages/oidc/src/index.ts:155

Exact HTTPS issuer root URL — no path, query, fragment, or trailing slash. Mutually exclusive with serverUrl.

Inherited from

OIDCTokenEndpointOptions.issuer

keyProvider

keyProvider: KeyProvider;

Defined in: packages/oidc/src/index.ts:169

Provider of the agent’s operational key, used to sign client assertions.

maxAssertionLifetime?

optional maxAssertionLifetime?: number;

Defined in: packages/oidc/src/index.ts:177

Upper bound on any requested assertion lifetime, in seconds. Defaults to 900.

serverUrl?

optional serverUrl?: string;

Defined in: packages/oidc/src/index.ts:157

Base server URL used to derive the discovery document and token endpoint. Mutually exclusive with issuer.

Inherited from

OIDCTokenEndpointOptions.serverUrl

timeoutMs?

optional timeoutMs?: number;

Defined in: packages/oidc/src/index.ts:179

Timeout for discovery and token-endpoint requests, in milliseconds. Defaults to 10000.

tokenEndpoint?

optional tokenEndpoint?: string;

Defined in: packages/oidc/src/index.ts:161

Explicit token endpoint URL; requires issuer, must share its origin, and bypasses discovery.

Inherited from

OIDCTokenEndpointOptions.tokenEndpoint

OIDCTokenMintOptions

Defined in: packages/oidc/src/index.ts:193

Per-call options for OIDCTokenMinter.mintToken(). Endpoint members override the minter’s defaults.

Extends

OIDCTokenEndpointOptions

Properties

additionalAssertionClaims?

optional additionalAssertionClaims?: Record<string, unknown>;

Defined in: packages/oidc/src/index.ts:201

Extra claims for the client assertion. Must not override reserved claims (iss, sub, aud, iat, exp, jti, fqdn).

audience

audience: string;

Defined in: packages/oidc/src/index.ts:195

Audience (aud) requested for the access token.

discoveryUrl?

optional discoveryUrl?: string;

Defined in: packages/oidc/src/index.ts:159

Explicit discovery document URL; only valid alongside issuer or serverUrl.

Inherited from

OIDCTokenEndpointOptions.discoveryUrl

issuer?

optional issuer?: string;

Defined in: packages/oidc/src/index.ts:155

Exact HTTPS issuer root URL — no path, query, fragment, or trailing slash. Mutually exclusive with serverUrl.

Inherited from

OIDCTokenEndpointOptions.issuer

scope?

optional scope?: string;

Defined in: packages/oidc/src/index.ts:197

Space-delimited scope string. Mutually exclusive with scopes.

scopes?

optional scopes?: readonly string[];

Defined in: packages/oidc/src/index.ts:199

Individual scope values, joined with spaces. Mutually exclusive with scope.

serverUrl?

optional serverUrl?: string;

Defined in: packages/oidc/src/index.ts:157

Base server URL used to derive the discovery document and token endpoint. Mutually exclusive with issuer.

Inherited from

OIDCTokenEndpointOptions.serverUrl

tokenEndpoint?

optional tokenEndpoint?: string;

Defined in: packages/oidc/src/index.ts:161

Explicit token endpoint URL; requires issuer, must share its origin, and bypasses discovery.

Inherited from

OIDCTokenEndpointOptions.tokenEndpoint

OIDCTokenResponse

Defined in: packages/oidc/src/index.ts:116

A successful token-endpoint response, normalized to camelCase members.

Properties

accessToken

accessToken: string;

Defined in: packages/oidc/src/index.ts:118

The issued access token.

expiresIn?

optional expiresIn?: number;

Defined in: packages/oidc/src/index.ts:124

Token lifetime in seconds, when the issuer provided one.

idToken?

optional idToken?: string;

Defined in: packages/oidc/src/index.ts:120

ID token, when the issuer returned one.

issuer?

optional issuer?: string;

Defined in: packages/oidc/src/index.ts:128

Issuer the token was obtained from.

raw

raw: unknown;

Defined in: packages/oidc/src/index.ts:132

Raw JSON body of the token response.

scope?

optional scope?: string;

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

Scope actually granted, when the issuer reported it.

tokenEndpoint?

optional tokenEndpoint?: string;

Defined in: packages/oidc/src/index.ts:130

Token endpoint the exchange was performed against.

tokenType

tokenType: string;

Defined in: packages/oidc/src/index.ts:122

Token type as reported by the issuer; always Bearer (case preserved).

VerifiedOIDCSubject

Defined in: packages/oidc/src/index.ts:219

Result of a successful OIDCProfile.verifyOIDCToken() call.

Properties

audience

audience: string;

Defined in: packages/oidc/src/index.ts:225

Audience the token was verified against.

claims

claims: JWTPayload;

Defined in: packages/oidc/src/index.ts:229

The signature-verified JWT claims.

issuer

issuer: string;

Defined in: packages/oidc/src/index.ts:221

Issuer that signed the token.

subject

subject: string;

Defined in: packages/oidc/src/index.ts:223

Token subject — the agent FQDN for DNSid-federated tokens.

verifiedDomain?

optional verifiedDomain?: VerifiedDomain;

Defined in: packages/oidc/src/index.ts:227

DNSid verification result for the subject; absent when verifyDnsidSubject is false.

VerifyOIDCTokenOptions

Defined in: packages/oidc/src/index.ts:208

Options for OIDCProfile.verifyOIDCToken().

Extends

VerificationOptions

Properties

audience

audience: string;

Defined in: packages/oidc/src/index.ts:212

Audience the token must be addressed to (exact match).

issuer

issuer: string;

Defined in: packages/oidc/src/index.ts:210

Exact issuer URL the token must have been issued by; must appear in the profile’s allowedIssuers.

peerCert?

optional peerCert?: TLSCertificate;

Defined in: packages/oidc/src/index.ts:215

signal?

optional signal?: AbortSignal;

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

Inherited from

VerificationOptions.signal

timeoutMs?

optional timeoutMs?: number;

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

Overall invocation budget, including all discovery and evidence. Default: 30 seconds.

Inherited from

VerificationOptions.timeoutMs

verifyDnsidSubject?

optional verifyDnsidSubject?: boolean;

Defined in: packages/oidc/src/index.ts:214

Set false to skip verifying the token subject as a DNSid identity record. Defaults to true.

Type Aliases

MintOIDCTokenOptions

type MintOIDCTokenOptions = CreateOIDCTokenMinterOptions & OIDCTokenMintOptions;

Defined in: packages/oidc/src/index.ts:205

Combined options for the one-shot mintOIDCToken.

Functions

createOIDCKeyProviderFromJWK()

function createOIDCKeyProviderFromJWK(privateJwk): Promise<KeyProvider>;

Defined in: packages/oidc/src/index.ts:431

Wraps a raw private JWK in an in-memory KeyProvider suitable for signing OIDC assertions. Derives the public key, kid (RFC 7638 thumbprint), and alg when absent. The provider is signing-only: key generation, activation, and supersession are not supported.

Parameters

privateJwk

OIDCPrivateJWK

Returns

Promise<KeyProvider>

Throws

ArgumentError if the JWK is not an object with a non-empty d member.

Throws

ValidationError if the key type/curve is unsupported for signing.

createOIDCProfile()

function createOIDCProfile(opts): OIDCProfile;

Defined in: packages/oidc/src/index.ts:669

Creates an OIDCProfile.

Parameters

opts

OIDCProfileOptions

Returns

OIDCProfile

Throws

ArgumentError if domain is not a valid agent FQDN.

Example

import { LocalKeyProvider } from '@dnsid-ai/sdk/node';
import { createOIDCProfile } from '@dnsid-ai/oidc';

const profile = createOIDCProfile({
  domain: 'agent.example',
  keyProvider: await LocalKeyProvider.load('.dnsid/keys.json', true),
  oidc: { allowedIssuers: ['https://issuer.example'] },
});
const token = await profile.getOIDCToken({
  issuer: 'https://issuer.example',
  audience: 'https://api.example',
});

createOIDCTokenMinter()

function createOIDCTokenMinter(opts): Promise<OIDCTokenMinter>;

Defined in: packages/oidc/src/index.ts:389

Creates an OIDCTokenMinter, resolving the signing key from either a KeyProvider or a raw private JWK.

Parameters

opts

CreateOIDCTokenMinterOptions

Returns

Promise<OIDCTokenMinter>

Throws

ArgumentError if neither or both of keyProvider/privateJwk are given, the private JWK is invalid, or the minter options are invalid.

decodeOIDCClaims()

function decodeOIDCClaims(token): Record<string, unknown>;

Defined in: packages/oidc/src/index.ts:1331

Decodes a JWT’s claims WITHOUT verifying its signature. Use only for inspection or logging — never for authorization decisions; use OIDCProfile.verifyOIDCToken() for those.

Parameters

token

string

Returns

Record<string, unknown>

The decoded claims object.

Throws

VerificationError (RecordInvalid) if the token is not a decodable JWT whose payload is a JSON object.

mintOIDCToken()

function mintOIDCToken(opts): Promise<OIDCTokenResponse>;

Defined in: packages/oidc/src/index.ts:417

One-shot convenience: creates a minter and mints a single OIDC access token via the JWT bearer grant. Server-side only — never mint tokens in browser/client code. See OIDCTokenMinter.mintToken() for thrown errors.

Parameters

opts

MintOIDCTokenOptions

Returns

Promise<OIDCTokenResponse>

Example

import { LocalKeyProvider } from '@dnsid-ai/sdk/node';
import { mintOIDCToken } from '@dnsid-ai/oidc';

const keyProvider = await LocalKeyProvider.load('.dnsid/keys.json', true);
const token = await mintOIDCToken({
  domain: 'agent.example',
  keyProvider,
  issuer: 'https://issuer.example',
  audience: 'https://api.example',
  scopes: ['openid', 'dnsid'],
});
console.log(token.accessToken);

validateExactOIDCIssuer()

function validateExactOIDCIssuer(issuer, allowHttpLoopbackIssuer?): string;

Defined in: packages/oidc/src/index.ts:1023

Validates that an issuer is an exact absolute URL — no query, fragment, or trailing slash — using HTTPS (or plain-HTTP loopback when explicitly allowed).

Parameters

issuer

string

allowHttpLoopbackIssuer?

boolean = false

Returns

string

The validated issuer string, unchanged.

Throws

ArgumentError if the issuer does not meet these requirements.

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.