@wellknown-id/wallet/self-issued

#Classes

#SelfIssuedError

Why a self-issued token was refused (its message says what was wrong).

#Extends

• Error

#Constructors

#Constructor

new SelfIssuedError(message?): SelfIssuedError;

#Parameters

#Returns

SelfIssuedError

#Inherited from

Error.constructor

#Constructor

new SelfIssuedError(message?, options?): SelfIssuedError;

#Parameters

#Returns

SelfIssuedError

#Inherited from

Error.constructor

#Type Aliases

#SelfIssuedClaims

type SelfIssuedClaims = object;

What a self-issued token says: the holder's key at the site (iss = sub) answering nonce for aud.

#Properties

#Variables

#SELF_ISSUED_LIFETIME_S

const SELF_ISSUED_LIFETIME_S: 120 = 120;

A proof's lifetime (Ben, 2026-10-01), and the longest a verifier accepts, whatever exp says.

#SELF_ISSUED_SKEW_S

const SELF_ISSUED_SKEW_S: 30 = 30;

How far apart the signer's and the verifier's clocks may be.

#SELF_ISSUED_TYP

const SELF_ISSUED_TYP: "wellknown-self-issued+jwt" = 'wellknown-self-issued+jwt';

The token's JOSE typ (RFC 8725 §3.11, explicit typing): the same site key signs succession statements (§4.9).

#Functions

#didUrl()

function didUrl(did): string;

The DID URL of a did:key's only key: did:key:z…#z…

#Parameters

#Returns

string

#jwkFromDidKey()

function jwkFromDidKey(did): JsonWebKey;

The public JWK a did:key names: P-256 decompressed here (WebCrypto imports only whole points), or Ed25519.

#Parameters

#Returns

JsonWebKey

#nonceFor()

function nonceFor(verifier): Promise<string>;

S256(verifier), as PKCE (RFC 7636 §4.2) computes a code_challenge: a direct token's nonce.

#Parameters

#Returns

Promise<string>

#peekNonce()

function peekNonce(token): string | undefined;

The token's nonce, unverified: the IdP finds the challenge it answers by it (and spends it) before verifying. Undefined if the token can't be read.

#Parameters

#Returns

string | undefined

#signSelfIssued()

function signSelfIssued(key, o): Promise<string>;

Signs a self-issued token with key (the persona's key for the site aud): ES256 for a P-256 did:key, EdDSA for Ed25519; sign returns the raw signature (r||s for ES256). Call it just before the token is sent. now: milliseconds (Date.now(), or the IdP's clock as its challenge said).

#Parameters

#Returns

Promise<string>

#verifySelfIssued()

function verifySelfIssued(token, o): Promise<SelfIssuedClaims>;

Verifies a self-issued token for aud (the client_id), answering nonce (the IdP's challenge, or the site's) or verifier (a site's backend: the nonce is S256 of it). Checks, in order: the compact form, typ (so no succession statement or other JWT a site key signs passes), alg against the did:key's type, kid a key of iss, iss = sub = a did:key, the signature, aud, the nonce, iat and exp with SELF_ISSUED_SKEW_S of skew, and a lifetime of at most SELF_ISSUED_LIFETIME_S. Throws SelfIssuedError saying what's wrong; returns the claims. Single use is the caller's: the IdP spends its challenge, a site its nonce.

#Parameters

#Returns

Promise<SelfIssuedClaims>