The /.well-known/id config

#Type Aliases

#Discovery

type Discovery = object;

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

#Properties

#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

#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

#RelyingParty

type RelyingParty = object;

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

#Properties

#WellknownConfig

type WellknownConfig = object;

A site's config, checked.

#Properties

#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

#Returns

Promise<Response>

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

MDN Reference

#Parameters

#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

#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

#Returns

string | undefined

#onDomain()

function onDomain(host, domain): boolean;

True when host is domain or one of its subdomains.

#Parameters

#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

#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

#Returns

Promise<WellknownConfig>

#resolveConfigCached()

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

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

#Parameters

#Returns

Promise<WellknownConfig>

#useDiscovery()

function useDiscovery(d): void;

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

#Parameters

#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

#Returns

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