API reference

The /.well-known/id config

The /.well-known/id config a site publishes (prd.md §5), as wellknown.id's IdP reads it: its shape, and how it's found (DNS first, then HTTPS) and checked. A site's client_id is its domain; the config there says where sign-ins may return, how codes are redeemed, what the site declares about the data it keeps, and whether it accepts delegation.

Type Aliases

Discovery

type Discovery = object;

How configs are fetched: over HTTPS, and DNS TXT records.

Properties

PropertyType
fetchtypeof fetch
resolveTxt(name) => Promise<string[][]>

IdTokenAlg

type IdTokenAlg = typeof ID_TOKEN_ALGS[number];

Privacy

type Privacy = object;

What the organisation declares about the data it collects (PRD §5.2, §7.6): who's responsible, its privacy notice (pinned by version and SHA-256), what it collects and why, how long it keeps it, and where holders' erasure requests go. kivi reads it when the holder withdraws consent or asks for erasure.

Properties

PropertyTypeDescription
collects?string[]-
controller?string-
erasure_endpoint?string-
notice?object-
notice.sha256string-
notice.urlstring-
notice.versionstring-
purposes?string[]-
retention?string-
terms?stringIts terms of service (RFC 7591's tos_uri): FedCM's dialog links to it beside the notice.

PublicJwk

type PublicJwk = object;

A public key as a JWK (RFC 7517). Private members (d and the rest) are refused wherever a config gives one.

Indexable

[k: string]: unknown

Properties

PropertyType
crv?string
e?string
ktystring
n?string
x?string
y?string

RelyingParty

type RelyingParty = object;

One entry of relying_parties (§5.2), in OAuth client metadata's names (RFC 7591).

Properties

PropertyTypeDescription
client_name?stringThe name the sign-in pages show for the site.
id_token_signed_response_algIdTokenAlgHow the IdP signs this site's ID tokens (RFC 7591, OIDC Dynamic Client Registration): EdDSA (the default), Ed25519 (RFC 9864's name for the same signature), ES256 or RS256, for the libraries the site verifies with. One per domain: every entry of a config names the same, as they share a client_id.
jwks?objectThe site's public keys, for private_key_jwt.
jwks.keysPublicJwk[]-
logo_uri?stringAn HTTPS image the sign-in pages may show beside the name.
policy?stringA karu policy (§6) for this entry's sign-ins, beside the config's own.
redirect_urisstring[]The exact addresses sign-ins may return to: on the site's domain or its subdomains, HTTPS.
self_issued"allow" | "forbid"Whether this entry takes self-issued tokens straight from the holder's page (prd.md §4.11, §5.2): allow, or forbid (the default), when it then gets only codes, redeemed for ID tokens the IdP signs.
token_endpoint_auth_method"none" | "private_key_jwt"How the site redeems codes: none (a public client, with PKCE) or private_key_jwt (signed with a key in jwks).

WellknownConfig

type WellknownConfig = object;

A site's config, checked.

Properties

PropertyTypeDescription
delegation?DelegationWhether the site accepts delegation (prd.md §5.2, §7.13): sign-ins by someone a holder lets act for them, with the site's HPKE key grants are sealed to, the mailbox it reads them from, and what may be delegated there.
noticeMailbox?stringWhere the site's notices are (prd.md §4.12: an account's key and its successor commitment, filed once by the holder's wallet before the first sign-in): its security_events.mailbox, where it names one (an https URL).
policy?stringA karu policy (§6) for every sign-in at the site.
privacy?PrivacyWhat the site declares about the data it collects (§7.6).
relying_partiesRelyingParty[]Where sign-ins may return, and how (at least one).
source"dns" | "http"Where it was found: DNS wins when both are valid.
version1Always 1.

Variables

ID_TOKEN_ALGS

const ID_TOKEN_ALGS: readonly ["EdDSA", "Ed25519", "ES256", "RS256"];

The algorithms ID tokens are signed with, as a site's config may name them; the IdP holds a key for each.

Functions

discoveryFetch()

function discoveryFetch(): {
  (input, init?): Promise<Response>;
  (input, init?): Promise<Response>;
};

The fetch configs are discovered with (the unit tests' stand-in, when they set one): also how a grant's mailbox is asked (§7.13).

Returns

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

MDN Reference

Parameters
ParameterType
inputURL | RequestInfo
init?RequestInit
Returns

Promise<Response>

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

MDN Reference

Parameters
ParameterType
inputstring | URL | Request
init?RequestInit
Returns

Promise<Response>


jwkThumbprint()

function jwkThumbprint(jwk): string;

RFC 7638 SHA-256 JWK thumbprint, base64url without padding. Checks the key has what its type needs.

Parameters

ParameterType
jwkPublicJwk

Returns

string


normalizeClientId()

function normalizeClientId(input): string | undefined;

The canonical client_id for a domain (PRD §4.5): a bare, lowercase hostname, internationalised names in punycode, no port, path or trailing dot. https://{domain} and https://{domain}/ mean the same. Returns undefined for anything else.

Parameters

ParameterType
inputunknown

Returns

string | undefined


onDomain()

function onDomain(host, domain): boolean;

True when host is domain or one of its subdomains.

Parameters

ParameterType
hoststring
domainstring

Returns

boolean


parseConfig()

function parseConfig(doc, source): WellknownConfig;

Validates a decoded config document (JSON or CBOR) against schema version 1. Throws on anything invalid.

Parameters

ParameterType
docunknown
source"http" | "dns"

Returns

WellknownConfig


resolveConfig()

function resolveConfig(domain, d?): Promise<WellknownConfig>;

Resolves the config for domain, trying DNS and HTTP. DNS wins when both are valid (PRD §5.1). Throws with both failure reasons when neither yields a valid config.

Parameters

ParameterTypeDefault value
domainstringundefined
dDiscoverydefaultDiscovery

Returns

Promise<WellknownConfig>


resolveConfigCached()

function resolveConfigCached(domain, d?): Promise<WellknownConfig>;

resolveConfig, kept for a few minutes (§5.1 allows up to an hour).

Parameters

ParameterTypeDefault value
domainstringundefined
dDiscoverydefaultDiscovery

Returns

Promise<WellknownConfig>


txtResolver()

function txtResolver(servers?): (name) => Promise<string[][]>;

The resolver configs' TXT records are asked of: the system's, unless servers names others (DNS_SERVERS: host[:port], comma-separated, an IPv6 address in brackets). The e2e stack points it at a DNS server of its own (e2e/local/compose.yaml), and an operator may at a validating resolver. Names are looked up once, when first needed.

Parameters

ParameterTypeDefault value
serversstring | undefinedprocess.env.DNS_SERVERS

Returns

(name) => Promise<string[][]>


useDiscovery()

function useDiscovery(d): void;

The unit tests' stand-in for HTTP and DNS, wherever a config is fetched without one being passed.

Parameters

ParameterType
dDiscovery

Returns

void


validateClient()

function validateClient(
   clientId, 
   redirectUri, 
   d?
): Promise<{
  config: WellknownConfig;
  domain: string;
  rp: RelyingParty;
}>;

Client validation (PRD §4.5): the client_id is the RP's domain; its config must list the redirect_uri exactly, and the redirect_uri must be on that domain. The matching entry is the RP.

Parameters

ParameterType
clientIdstring
redirectUristring
d?Discovery

Returns

Promise<{ config: WellknownConfig; domain: string; rp: RelyingParty; }>