TypeScript: @dnsid-ai/jose

DNSid JOSE profile helpers for JWT and JWS workflows.

This package builds on @dnsid-ai/protocol contracts and does not perform DNS or HTTPS transport itself. Provide an identity resolver and key provider directly, or construct the profile from a signing IdentityManager.

Install

npm install @dnsid-ai/jose @dnsid-ai/protocol

Example

import { createJoseProfile } from '@dnsid-ai/jose';

const joseProfile = createJoseProfile({
  domain: 'agent.example',
  keyProvider,
  identityResolver,
});

Verification

A verification-only profile may omit domain and keyProvider:

const verifier = createJoseProfile({ identityResolver });
await verifier.verifyJWT(token, {
  expectedAudience: 'service.example', // trusted configuration, never token-derived
  peerCert, // trusted current application peer; required for fl=mtls
  timeoutMs: 5000,
  signal,
});
await verifier.verifyJWS(jws, { peerCert, signal });

Both helpers default to a 30-second overall deadline and pass cancellation to identity discovery. Compact tokens are limited to 1 MiB and encoded headers to 16 KiB before decoding. Duplicate JSON members, unsupported critical/unencoded headers, and incorrectly typed claims are rejected before discovery. Expiration has no skew grace and is checked again after verification; fractional NumericDates and explicit zero clock skew are supported. Explicit invalid lifetimes are errors. fl=logchk remains caller-owned operation policy.

@dnsid-ai/sdk also re-exports this package as jose and exports JoseProfile / createJoseProfile directly.

DNSid JOSE profile helpers for JWT/JWS workflows.

Builds on the narrow contracts from @dnsid-ai/protocol (KeyProvider, IdentityResolver) to sign and verify compact JWTs and detached-style JWS objects whose signers are identified by DNSid agent domains. This package performs no DNS or HTTPS transport itself — callers supply an identity resolver and key provider, or build the profile from a signing IdentityManager via JoseProfile.fromIdentityManager.

Classes

JoseProfile

Defined in: jose/src/index.ts:110

JOSE JWT/JWS helpers built on narrow DNSid core contracts.

Signs on behalf of the local agent domain (via its KeyProvider) and verifies inbound tokens by resolving the issuer’s DNSid identity (via its IdentityResolver). Performs no DNS or HTTPS transport itself.

Constructors

Constructor

new JoseProfile(opts): JoseProfile;

Defined in: jose/src/index.ts:134

Parameters

opts

JoseProfileOptions

Returns

JoseProfile

Throws

ArgumentError if opts.domain is not a valid agent FQDN.

Methods

createJWS()

createJWS(payload): Promise<string>;

Defined in: jose/src/index.ts:343

Signs an arbitrary byte payload as a compact JWS with typ: "jose". The header kid is the compound form <domain>#<kid> so verifiers can locate the signer without out-of-band context.

Parameters

payload

Uint8Array

Returns

Promise<string>

The compact JWS serialization (header.payload.signature).

Throws

ArgumentError if the operational signing key’s kid contains #.

createJWT()

createJWT(opts): Promise<string>;

Defined in: jose/src/index.ts:157

Creates a signed compact JWT with iss/sub set to the local domain, aud set to the normalized audience, and a fresh jti. The header carries the operational key’s alg and bare kid (no domain prefix).

Parameters

opts

CreateJWTInput

Returns

Promise<string>

The compact JWT serialization (header.payload.signature).

Throws

ArgumentError if the audience is missing or not a valid FQDN, if expiry exceeds the configured max lifetime, or if additionalClaims would override a reserved claim.

verifyJWS()

verifyJWS(jws, options?): Promise<VerifyJWSResult>;

Defined in: jose/src/index.ts:381

Verifies a compact JWS whose header kid is the compound <domain>#<kid> form produced by createJWS.

Parses the compound kid, resolves and verifies the signer’s DNSid identity, matches the key in the signer’s JWKS, enforces the APPLICATION_JOSE_ALGS allowlist and alg/key consistency, and verifies the signature. Unlike verifyJWT, the payload is opaque — no claims are inspected.

Parameters

jws

string

options?

VerificationOptions & object = {}

Returns

Promise<VerifyJWSResult>

The raw payload bytes and the signer’s verified identity.

Throws

VerificationError with VerificationCode.RecordInvalid for a malformed JWS; with VerificationCode.SignatureInvalid for a missing/invalid kid, unknown key, disallowed or mismatched alg, or a bad signature. Identity resolution errors propagate unchanged.

verifyJWT()

verifyJWT(jwt, options?): Promise<VerifiedDomain>;

Defined in: jose/src/index.ts:217

Verifies an inbound compact JWT issued by a remote DNSid agent.

Checks structure, sub === iss, that the local domain appears in aud, time claims (iat required and not in the future, exp required, within the max lifetime, not expired, optional nbf), then resolves the issuer’s DNSid identity, matches the header kid against the issuer’s JWKS, enforces the APPLICATION_JOSE_ALGS allowlist and alg/key consistency, and verifies the signature.

Parameters

jwt

string

options?

VerificationOptions & object = {}

Returns

Promise<VerifiedDomain>

The issuer’s verified DNSid identity.

Throws

VerificationError with VerificationCode.RecordInvalid for malformed tokens, claim violations, or issuer resolution argument failures; with VerificationCode.SignatureInvalid for missing/unknown kid, disallowed or mismatched alg, or a bad signature. Resolver errors other than ArgumentError propagate unchanged.

fromIdentityManager()

static fromIdentityManager(identityManager, jose?): JoseProfile;

Defined in: jose/src/index.ts:116

Builds a profile from a signing IdentityManager, reusing its domain, key provider, and identity resolution.

Parameters

identityManager

SigningIdentityManager

jose?

JoseProfileConfig

Optional JOSE-specific limits (max lifetime, clock skew).

Returns

JoseProfile

Interfaces

CreateJWTInput

Defined in: jose/src/index.ts:93

Input to JoseProfile.createJWT. Alias of JWTOptions.

Extends

• JWTOptions

Properties

additionalClaims?

optional additionalClaims?: Record<string, unknown>;

Defined in: jose/src/index.ts:48

Extra claims merged into the payload. Must not override the reserved claims iss, sub, aud, iat, exp, or jti.

Inherited from

JWTOptions.additionalClaims

audience

audience: string;

Defined in: jose/src/index.ts:38

Intended recipient’s DNSid agent FQDN. Becomes the aud claim (normalized).

Inherited from

JWTOptions.audience

expiry?

optional expiry?: number;

Defined in: jose/src/index.ts:43

Token lifetime in seconds (exp = iat + expiry). Default: DEFAULT_JWT_EXPIRY_SECONDS. Must not exceed the profile’s maxLifetime.

Inherited from

JWTOptions.expiry

---

JoseProfileConfig

Defined in: jose/src/index.ts:73

Tunable verification and issuance limits for a JoseProfile.

Properties

clockSkew?

optional clockSkew?: number;

Defined in: jose/src/index.ts:77

Allowed clock skew in seconds when checking JWT iat and nbf. Default: 60.

maxLifetime?

optional maxLifetime?: number;

Defined in: jose/src/index.ts:75

Maximum accepted JWT lifetime (exp - iat) in seconds. Default: 900.

---

JoseProfileOptions

Defined in: jose/src/index.ts:81

Construction options for JoseProfile / createJoseProfile.

Properties

domain?

optional domain?: string;

Defined in: jose/src/index.ts:83

Local DNSid identity FQDN.

identityResolver

identityResolver: IdentityResolver;

Defined in: jose/src/index.ts:87

Resolves and verifies remote DNSid identities when verifying inbound JWTs/JWS.

jose?

optional jose?: JoseProfileConfig;

Defined in: jose/src/index.ts:89

Optional JOSE-specific limits. Defaults: 900s max lifetime, 60s clock skew.

keyProvider?

optional keyProvider?: KeyProvider;

Defined in: jose/src/index.ts:85

Signs outgoing JWTs/JWS. Omit for a verification-only profile.

---

JWTOptions

Defined in: jose/src/index.ts:36

Options controlling the claims of a JWT created by JoseProfile.createJWT.

Extended by

• CreateJWTInput

Properties

additionalClaims?

optional additionalClaims?: Record<string, unknown>;

Defined in: jose/src/index.ts:48

Extra claims merged into the payload. Must not override the reserved claims iss, sub, aud, iat, exp, or jti.

audience

audience: string;

Defined in: jose/src/index.ts:38

Intended recipient’s DNSid agent FQDN. Becomes the aud claim (normalized).

expiry?

optional expiry?: number;

Defined in: jose/src/index.ts:43

Token lifetime in seconds (exp = iat + expiry). Default: DEFAULT_JWT_EXPIRY_SECONDS. Must not exceed the profile’s maxLifetime.

---

VerifyJWSResult

Defined in: jose/src/index.ts:96

Result of a successful JoseProfile.verifyJWS call.

Properties

payload

payload: Uint8Array;

Defined in: jose/src/index.ts:98

The decoded (base64url) JWS payload bytes, exactly as signed.

verifiedDomain

verifiedDomain: VerifiedDomain;

Defined in: jose/src/index.ts:100

The signer’s verified DNSid identity, resolved from the kid header’s domain.

Type Aliases

ApplicationJoseAlg

type ApplicationJoseAlg = typeof APPLICATION_JOSE_ALGS[number];

Defined in: jose/src/index.ts:62

Union of the algorithm identifiers in APPLICATION_JOSE_ALGS.

Variables

APPLICATION_JOSE_ALGS

const APPLICATION_JOSE_ALGS: readonly ["EdDSA", "ES256", "ES384", "ES512", "RS256", "RS384", "RS512", "PS256", "PS384", "PS512"];

Defined in: jose/src/index.ts:56

JOSE signature algorithms accepted at the application layer. A JWT/JWS whose alg header is outside this allowlist is rejected during verification (notably none and all HMAC algorithms are excluded).

---

DEFAULT_JWT_EXPIRY_SECONDS

const DEFAULT_JWT_EXPIRY_SECONDS: number;

Defined in: jose/src/index.ts:65

Default JWT lifetime in seconds (15 minutes) when JWTOptions.expiry is omitted.

Functions

createJoseProfile()

function createJoseProfile(opts): JoseProfile;

Defined in: jose/src/index.ts:458

Creates a JoseProfile for DNSid JWT/JWS workflows.

Primary entry point of this package. Equivalent to new JoseProfile(opts); use JoseProfile.fromIdentityManager to build from a signing IdentityManager instead.

Parameters

opts

JoseProfileOptions

Returns

JoseProfile

Throws

ArgumentError if opts.domain is not a valid agent FQDN.

Example

import { createJoseProfile } from '@dnsid-ai/jose';

const joseProfile = createJoseProfile({
  domain: 'agent.example',
  keyProvider,
  identityResolver,
});

const jwt = await joseProfile.createJWT({ audience: 'peer.example' });
const verifiedDomain = await peerProfile.verifyJWT(jwt);
console.log(verifiedDomain.domain); // 'agent.example'

---

fromBase64Url()

function fromBase64Url(b64): Uint8Array;

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

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

Parameters

b64

string

Returns

Uint8Array

---

parseKeyId()

function parseKeyId(keyId): object;

Defined in: 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.

---

toBase64Url()

function toBase64Url(bytes): string;

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

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

Parameters

bytes

Uint8Array

Returns

string