Type Aliases
Discovery
type Discovery = object;
How configs are fetched: over HTTPS, and DNS TXT records.
Properties
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
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
| Property | Type | Description |
|---|---|---|
client_name? | string | The name the sign-in pages show for the site. |
id_token_signed_response_alg | IdTokenAlg | How 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? | object | The site's public keys, for private_key_jwt. |
jwks.keys | PublicJwk[] | - |
logo_uri? | string | An HTTPS image the sign-in pages may show beside the name. |
policy? | string | A karu policy (§6) for this entry's sign-ins, beside the config's own. |
redirect_uris | string[] | 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
| Property | Type | Description |
|---|---|---|
delegation? | Delegation | Whether 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? | string | Where 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? | string | A karu policy (§6) for every sign-in at the site. |
privacy? | Privacy | What the site declares about the data it collects (§7.6). |
relying_parties | RelyingParty[] | Where sign-ins may return, and how (at least one). |
source | "dns" | "http" | Where it was found: DNS wins when both are valid. |
version | 1 | Always 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>;
Parameters
| Parameter | Type |
|---|---|
input | URL | RequestInfo |
init? | RequestInit |
Returns
Promise<Response>
(input, init?): Promise<Response>;
Parameters
| Parameter | Type |
|---|---|
input | string | 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
| Parameter | Type |
|---|---|
jwk | PublicJwk |
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
| Parameter | Type |
|---|---|
input | unknown |
Returns
string | undefined
onDomain()
function onDomain(host, domain): boolean;
True when host is domain or one of its subdomains.
Parameters
| Parameter | Type |
|---|---|
host | string |
domain | string |
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
| Parameter | Type |
|---|---|
doc | unknown |
source | "http" | "dns" |
Returns
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
| Parameter | Type | Default value |
|---|---|---|
domain | string | undefined |
d | Discovery | defaultDiscovery |
Returns
Promise<WellknownConfig>
resolveConfigCached()
function resolveConfigCached(domain, d?): Promise<WellknownConfig>;
resolveConfig, kept for a few minutes (§5.1 allows up to an hour).
Parameters
| Parameter | Type | Default value |
|---|---|---|
domain | string | undefined |
d | Discovery | defaultDiscovery |
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
| Parameter | Type | Default value |
|---|---|---|
servers | string | undefined | process.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
| Parameter | Type |
|---|---|
d | Discovery |
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
| Parameter | Type |
|---|---|
clientId | string |
redirectUri | string |
d? | Discovery |
Returns
Promise<{
config: WellknownConfig;
domain: string;
rp: RelyingParty;
}>