@starci/auth 0.5.0 → 0.6.0

package/dist/contracts/index.js

@@ -49,6 +49,10 @@ export const AUTH_ERROR_CODES = {
     EmailNotConfirmed: "IDENTITY_EMAIL_NOT_CONFIRMED",
     PasswordInvalid: "IDENTITY_PASSWORD_INVALID",
     ResetTokenInvalid: "IDENTITY_RESET_TOKEN_INVALID",
+    ProviderStateInvalid: "PASSPORT_PROVIDER_STATE_INVALID",
+    ProviderRejected: "PASSPORT_PROVIDER_REJECTED",
+    ProviderUnavailable: "PASSPORT_PROVIDER_UNAVAILABLE",
+    ProvidersInvalid: "PASSPORT_PROVIDERS_INVALID",
 };
 /** The kind of every code. */
 export const AUTH_ERROR_KINDS = {
@@ -67,6 +71,16 @@ export const AUTH_ERROR_KINDS = {
     [AUTH_ERROR_CODES.EmailNotConfirmed]: "forbidden",
     [AUTH_ERROR_CODES.PasswordInvalid]: "invalid",
     [AUTH_ERROR_CODES.ResetTokenInvalid]: "invalid",
+    [AUTH_ERROR_CODES.ProviderStateInvalid]: "unauthenticated",
+    [AUTH_ERROR_CODES.ProviderRejected]: "unauthenticated",
+    [AUTH_ERROR_CODES.ProviderUnavailable]: "unavailable",
+    [AUTH_ERROR_CODES.ProvidersInvalid]: "internal",
 };
 /** The facts both sides hold about a password. */
 export const PASSWORD_BOUNDS = { min: 8, max: 256, bcryptMaxBytes: 72 };
+/** The door that starts a sign-in provider's round trip (`/auth/<id>`); Google's is `AUTH_DOORS.google`. */
+export const providerDoor = (provider) => `/${AUTH_PREFIX}/${provider}`;
+/** The door a sign-in provider sends the browser back to (`/auth/<id>/callback`); Google's is `AUTH_DOORS.googleCallback`. */
+export const providerCallbackDoor = (provider) => `${providerDoor(provider)}/callback`;
+/** The contract of the full edition (OIDC algorithms, codes, claims and principal), merged into this entry. */
+export * from "./oidc.js";

package/dist/contracts/oidc.d.ts

@@ -0,0 +1,148 @@
+/**
+ * What both sides of an OIDC sign-in share: the algorithms a token may be signed with, the wire codes, the claim names and the
+ * shapes of the answers. The server module and the front-end client read these constants, so the two never drift.
+ */
+/** The signature algorithms a verifier may be pinned to: asymmetric only. `none` and every HMAC algorithm are not in the list and are refused at registration. */
+export declare const OIDC_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+/** One admitted signature algorithm. */
+export type OidcAlgorithm = (typeof OIDC_ALGORITHMS)[number];
+/** The algorithm list a registration pins when it names none: what Keycloak signs with by default. */
+export declare const OIDC_DEFAULT_ALGORITHMS: readonly OidcAlgorithm[];
+/** The `role` every verified principal carries, the one `@starci/auth` gives its principals, so a guard reads one value in both editions. */
+export declare const OIDC_ROLE = "authenticated";
+/**
+ * The wire code a verifier refuses a token with: the code `@starci/auth`'s verifier uses, so the guard and the filter that map it
+ * to a 401 are the same in both editions. The specific reason travels in the refusal's `detail.reason`, for the log, never for the client.
+ */
+export declare const OIDC_ACCESS_TOKEN_INVALID = "PASSPORT_ACCESS_TOKEN_INVALID";
+/**
+ * The codes of the errors the package throws: a provider that cannot be reached is `Unavailable`, a response that cannot be trusted is `Rejected`.
+ * The server-side grants add the four a sign-in, a sign-up and a social callback end with: `CredentialsRejected` (the provider refused the
+ * username and password, or the refresh token), `EmailRegistered` (the provider already holds the account), `PasswordInvalid` (its policy
+ * refuses the password) and `SocialRejected` (a code, nonce or state of a federated sign-in the provider or the check refused).
+ */
+export declare const OIDC_ERROR_CODES: {
+    readonly ConfigurationInvalid: "OIDC_CONFIGURATION_INVALID";
+    readonly Unavailable: "OIDC_UNAVAILABLE";
+    readonly Rejected: "OIDC_REJECTED";
+    readonly CredentialsRejected: "OIDC_CREDENTIALS_REJECTED";
+    readonly EmailRegistered: "OIDC_EMAIL_REGISTERED";
+    readonly PasswordInvalid: "OIDC_PASSWORD_INVALID";
+    readonly SocialRejected: "OIDC_SOCIAL_REJECTED";
+};
+/** One code a thrown OIDC error carries. */
+export type OidcErrorCode = (typeof OIDC_ERROR_CODES)[keyof typeof OIDC_ERROR_CODES];
+/** How a thrown code travels: the same families as `@starci/auth`'s error kinds. */
+export type OidcErrorKind = "invalid" | "unavailable" | "unauthenticated" | "credentials-rejected" | "email-registered" | "password-invalid" | "social-rejected";
+/** The kind of every thrown code. */
+export declare const OIDC_ERROR_KINDS: Readonly<Record<OidcErrorCode, OidcErrorKind>>;
+/** Why a token was refused: the reason a refusal's detail names. */
+export type OidcRefusalReason = "malformed" | "algorithm" | "unknown-key" | "signature" | "issuer" | "audience" | "authorized-party" | "expired" | "not-yet-valid" | "token-type" | "claims"
+/** A well-formed token of the right issuer whose claims an issuer preset's policy refuses (another repository, workflow or ref); `detail.claim` names it. */
+ | "policy";
+/** The claim names read beyond the registered ones. */
+export declare const OIDC_CLAIMS: {
+    readonly sessionId: "sid";
+    readonly tokenId: "jti";
+    readonly email: "email";
+    readonly emailVerified: "email_verified";
+    readonly name: "name";
+    readonly username: "preferred_username";
+    readonly authorizedParty: "azp";
+    readonly realmAccess: "realm_access";
+    readonly resourceAccess: "resource_access";
+    readonly tokenType: "typ";
+    readonly nonce: "nonce";
+};
+/** The most roles a token may carry and the longest a role may be: a token past either is refused, so a claim cannot grow without bound. */
+export declare const OIDC_ROLE_BOUNDS: {
+    readonly maxRoles: 128;
+    readonly maxLength: 256;
+};
+/** The longest `sub` a principal may have. */
+export declare const OIDC_SUBJECT_MAX_LENGTH = 255;
+/** The principal a verified access token stands for. Assignable to `@starci/auth`'s `AuthPrincipal`, with the roles the issuer granted. */
+export interface OidcPrincipal {
+    /** The account: the `sub` claim. */
+    readonly id: string;
+    /** Always `authenticated`: a guard that checks the role of the lite principal checks this one the same way. */
+    readonly role: typeof OIDC_ROLE;
+    /** The provider session: the `sid` claim, else the token id (`jti`), else the subject. */
+    readonly sessionId: string;
+    /** The verified `email` claim, when the token has one. */
+    readonly email?: string;
+    /** The display name, when the token has one. */
+    readonly name?: string;
+    /** The `preferred_username`, when the token has one. */
+    readonly username?: string;
+    /** The roles the issuer granted, from the realm and from the clients the registration maps, sorted and without repeats. */
+    readonly roles: readonly string[];
+    /** The issuer that signed the token. */
+    readonly issuer: string;
+    /** When the token stops being accepted. */
+    readonly expiresAt: Date;
+}
+/** The refusal of a verifier. */
+export interface OidcRefusal {
+    readonly kind: "refused";
+    readonly code: typeof OIDC_ACCESS_TOKEN_INVALID;
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+/** The result of a check that can refuse: the same two shapes as `@starci/auth`'s `Outcome`. */
+export type OidcOutcome<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | OidcRefusal;
+/**
+ * What a guard asks of an identity source: the principal of a bearer token, or a refusal. The same interface as
+ * `PrincipalVerifier` of `@starci/auth/server` (the package's own specs hold that this verifier is assignable to that one, and its principal to `AuthPrincipal`), so
+ * guards, `@Public` and `@Credential` do not change between editions.
+ */
+export interface PrincipalVerifier {
+    /** Verifies one token at one instant. A provider that cannot be reached throws an `OidcError` of kind `unavailable`; an untrusted token is a refusal. */
+    verify(token: string, now?: Date): Promise<OidcOutcome<OidcPrincipal>>;
+}
+/** What a completed authorization-code flow established, after the ID token passed signature, issuer, audience, expiry and nonce. */
+export interface OidcIdentity {
+    /** The issuer that signed the ID token. */
+    readonly issuer: string;
+    /** The verified account subject. */
+    readonly subject: string;
+    /** The roles the ID token carries. */
+    readonly roles: readonly string[];
+    /** The verified email, when the token has one. */
+    readonly email?: string;
+    /** The provider session, when the token names one. */
+    readonly sessionId?: string;
+    /** The verified token expiry, which bounds a local session. */
+    readonly expiresAt: Date;
+}
+/** The person a front-end session belongs to. */
+export interface OidcSessionUser {
+    /** The subject. */
+    readonly id: string;
+    /** The email, or empty text when the token has none. */
+    readonly email: string;
+}
+/** The kinds of failure a front-end call ends with. */
+export type OidcFailureKind = "refused" | "not-found" | "invalid" | "unavailable";
+/** The outcome of a front-end call: a value, or a failure carrying its kind and a code. The same shape as `AuthOutcome` of `@starci/auth/contracts`. */
+export type OidcClientOutcome<T> = {
+    readonly success: true;
+    readonly message: "ok";
+    readonly data: T;
+} | {
+    readonly success: false;
+    readonly message: OidcFailureKind;
+    readonly error: string;
+};
+/** The codes a front-end failure carries. */
+export declare const OIDC_CLIENT_CODES: {
+    readonly State: "OIDC_STATE_INVALID";
+    readonly Nonce: "OIDC_NONCE_INVALID";
+    readonly Issuer: "OIDC_ISSUER_MISMATCH";
+    readonly Provider: "OIDC_PROVIDER_REFUSED";
+    readonly Token: "OIDC_TOKEN_RESPONSE_INVALID";
+    readonly Transport: "OIDC_TRANSPORT";
+    readonly NoLogout: "OIDC_NO_LOGOUT_ENDPOINT";
+};

package/dist/contracts/oidc.js

@@ -0,0 +1,68 @@
+/**
+ * What both sides of an OIDC sign-in share: the algorithms a token may be signed with, the wire codes, the claim names and the
+ * shapes of the answers. The server module and the front-end client read these constants, so the two never drift.
+ */
+/** The signature algorithms a verifier may be pinned to: asymmetric only. `none` and every HMAC algorithm are not in the list and are refused at registration. */
+export const OIDC_ALGORITHMS = ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+/** The algorithm list a registration pins when it names none: what Keycloak signs with by default. */
+export const OIDC_DEFAULT_ALGORITHMS = ["RS256"];
+/** The `role` every verified principal carries, the one `@starci/auth` gives its principals, so a guard reads one value in both editions. */
+export const OIDC_ROLE = "authenticated";
+/**
+ * The wire code a verifier refuses a token with: the code `@starci/auth`'s verifier uses, so the guard and the filter that map it
+ * to a 401 are the same in both editions. The specific reason travels in the refusal's `detail.reason`, for the log, never for the client.
+ */
+export const OIDC_ACCESS_TOKEN_INVALID = "PASSPORT_ACCESS_TOKEN_INVALID";
+/**
+ * The codes of the errors the package throws: a provider that cannot be reached is `Unavailable`, a response that cannot be trusted is `Rejected`.
+ * The server-side grants add the four a sign-in, a sign-up and a social callback end with: `CredentialsRejected` (the provider refused the
+ * username and password, or the refresh token), `EmailRegistered` (the provider already holds the account), `PasswordInvalid` (its policy
+ * refuses the password) and `SocialRejected` (a code, nonce or state of a federated sign-in the provider or the check refused).
+ */
+export const OIDC_ERROR_CODES = {
+    ConfigurationInvalid: "OIDC_CONFIGURATION_INVALID",
+    Unavailable: "OIDC_UNAVAILABLE",
+    Rejected: "OIDC_REJECTED",
+    CredentialsRejected: "OIDC_CREDENTIALS_REJECTED",
+    EmailRegistered: "OIDC_EMAIL_REGISTERED",
+    PasswordInvalid: "OIDC_PASSWORD_INVALID",
+    SocialRejected: "OIDC_SOCIAL_REJECTED",
+};
+/** The kind of every thrown code. */
+export const OIDC_ERROR_KINDS = {
+    [OIDC_ERROR_CODES.ConfigurationInvalid]: "invalid",
+    [OIDC_ERROR_CODES.Unavailable]: "unavailable",
+    [OIDC_ERROR_CODES.Rejected]: "unauthenticated",
+    [OIDC_ERROR_CODES.CredentialsRejected]: "credentials-rejected",
+    [OIDC_ERROR_CODES.EmailRegistered]: "email-registered",
+    [OIDC_ERROR_CODES.PasswordInvalid]: "password-invalid",
+    [OIDC_ERROR_CODES.SocialRejected]: "social-rejected",
+};
+/** The claim names read beyond the registered ones. */
+export const OIDC_CLAIMS = {
+    sessionId: "sid",
+    tokenId: "jti",
+    email: "email",
+    emailVerified: "email_verified",
+    name: "name",
+    username: "preferred_username",
+    authorizedParty: "azp",
+    realmAccess: "realm_access",
+    resourceAccess: "resource_access",
+    tokenType: "typ",
+    nonce: "nonce",
+};
+/** The most roles a token may carry and the longest a role may be: a token past either is refused, so a claim cannot grow without bound. */
+export const OIDC_ROLE_BOUNDS = { maxRoles: 128, maxLength: 256 };
+/** The longest `sub` a principal may have. */
+export const OIDC_SUBJECT_MAX_LENGTH = 255;
+/** The codes a front-end failure carries. */
+export const OIDC_CLIENT_CODES = {
+    State: "OIDC_STATE_INVALID",
+    Nonce: "OIDC_NONCE_INVALID",
+    Issuer: "OIDC_ISSUER_MISMATCH",
+    Provider: "OIDC_PROVIDER_REFUSED",
+    Token: "OIDC_TOKEN_RESPONSE_INVALID",
+    Transport: "OIDC_TRANSPORT",
+    NoLogout: "OIDC_NO_LOGOUT_ENDPOINT",
+};

package/dist/oidc/admin.d.ts

@@ -0,0 +1,42 @@
+import type { OidcDiscovery } from "./discovery.js";
+import type { ResolvedOidcOptions } from "./options.js";
+/** The account a sign-up creates. */
+export interface OidcNewUser {
+    readonly email: string;
+    readonly username: string;
+    /** The first password; it is set permanent (not temporary) and is sent once. */
+    readonly password: string;
+}
+/** The account a sign-up created. */
+export interface OidcCreatedUser {
+    /** The provider's id of the account: the `sub` of its tokens. */
+    readonly subject: string;
+}
+/** The account an email belongs to. */
+export interface OidcFoundUser {
+    readonly subject: string;
+    readonly username: string;
+}
+/** The realm admin base, `<origin>/admin/realms/<realm>`, derived from a Keycloak issuer `<origin>[/<prefix>]/realms/<realm>`. */
+export declare const adminBaseOf: (issuer: string) => string;
+/**
+ * The provider's admin API as the registered client's service account (the client credentials grant, the token cached until it is about
+ * to expire): create an account, find one by email, set a password, end every session. The realm admin base is derived from the issuer.
+ * The service account needs the realm-management roles for users; a request it cannot make is `Rejected`. Nothing here logs a
+ * password or a token.
+ */
+export declare class OidcAdminClient {
+    #private;
+    constructor(options: ResolvedOidcOptions, discovery: OidcDiscovery);
+    /**
+     * Creates an enabled account with a permanent password. A taken email or username throws `EmailRegistered`; a password the realm's policy
+     * refuses throws `PasswordInvalid`.
+     */
+    createUser(input: OidcNewUser): Promise<OidcCreatedUser>;
+    /** The account whose email is exactly this one (case-insensitive), or null. */
+    findUserByEmail(email: string): Promise<OidcFoundUser | null>;
+    /** Sets a permanent password. A password the policy refuses throws `PasswordInvalid`. */
+    resetPassword(subject: string, password: string): Promise<void>;
+    /** Ends every session of the account at the provider, which also ends their refresh tokens. */
+    logoutAll(subject: string): Promise<void>;
+}

package/dist/oidc/admin.js

@@ -0,0 +1,139 @@
+import { OIDC_ERROR_CODES } from "../contracts/oidc.js";
+import { OidcError } from "./errors.js";
+import { isRecord, revealed } from "./primitives.js";
+import { send } from "./transport.js";
+/** A service-account token is renewed this long before it expires, so a request never carries one that dies in flight. */
+const TOKEN_MARGIN_MS = 10_000;
+const SECOND_MS = 1000;
+const rejected = () => new OidcError(OIDC_ERROR_CODES.Rejected);
+/** True when an answer's error text speaks of the password (the provider's policy refusing it), not of another field. */
+const speaksOfPassword = (body) => {
+    if (!isRecord(body))
+        return false;
+    return [body.error, body.errorMessage, body.error_description].some((field) => typeof field === "string" && /password/iu.test(field));
+};
+/** The last path segment of a `Location` address: the id the provider gave a created account. */
+const idOfLocation = (location) => {
+    if (location === undefined || !URL.canParse(location))
+        return undefined;
+    const segment = new URL(location).pathname
+        .split("/")
+        .filter((part) => part !== "")
+        .pop();
+    return segment === undefined ? undefined : decodeURIComponent(segment);
+};
+/** The realm admin base, `<origin>/admin/realms/<realm>`, derived from a Keycloak issuer `<origin>[/<prefix>]/realms/<realm>`. */
+export const adminBaseOf = (issuer) => {
+    const url = new URL(issuer);
+    const path = url.pathname.replace(/\/$/u, "");
+    const at = path.lastIndexOf("/realms/");
+    const realm = at < 0 ? "" : path.slice(at + "/realms/".length);
+    if (realm === "" || realm.includes("/"))
+        throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "issuer" } });
+    return `${url.origin}${path.slice(0, at)}/admin/realms/${realm}`;
+};
+/**
+ * The provider's admin API as the registered client's service account (the client credentials grant, the token cached until it is about
+ * to expire): create an account, find one by email, set a password, end every session. The realm admin base is derived from the issuer.
+ * The service account needs the realm-management roles for users; a request it cannot make is `Rejected`. Nothing here logs a
+ * password or a token.
+ */
+export class OidcAdminClient {
+    #options;
+    #discovery;
+    #held;
+    #pending;
+    constructor(options, discovery) {
+        this.#options = options;
+        this.#discovery = discovery;
+    }
+    /**
+     * Creates an enabled account with a permanent password. A taken email or username throws `EmailRegistered`; a password the realm's policy
+     * refuses throws `PasswordInvalid`.
+     */
+    async createUser(input) {
+        const response = await this.#call("POST", "/users", {
+            username: input.username,
+            email: input.email,
+            enabled: true,
+            emailVerified: false,
+            credentials: [{ type: "password", value: input.password, temporary: false }],
+        });
+        if (response.status === 409)
+            throw new OidcError(OIDC_ERROR_CODES.EmailRegistered);
+        if (response.status === 400 && speaksOfPassword(response.body))
+            throw new OidcError(OIDC_ERROR_CODES.PasswordInvalid);
+        if (response.status !== 201)
+            throw rejected();
+        const subject = idOfLocation(response.location) ?? (await this.#byUsername(input.username));
+        if (subject === undefined)
+            throw rejected();
+        return { subject };
+    }
+    /** The account whose email is exactly this one (case-insensitive), or null. */
+    async findUserByEmail(email) {
+        const users = await this.#search({ email, exact: "true" });
+        const wanted = email.toLowerCase();
+        const found = users.find((user) => user.email?.toLowerCase() === wanted);
+        return found === undefined ? null : { subject: found.id, username: found.username };
+    }
+    /** Sets a permanent password. A password the policy refuses throws `PasswordInvalid`. */
+    async resetPassword(subject, password) {
+        const response = await this.#call("PUT", `/users/${encodeURIComponent(subject)}/reset-password`, { type: "password", value: password, temporary: false });
+        if (response.status === 400)
+            throw new OidcError(OIDC_ERROR_CODES.PasswordInvalid);
+        if (response.status !== 204 && response.status !== 200)
+            throw rejected();
+    }
+    /** Ends every session of the account at the provider, which also ends their refresh tokens. */
+    async logoutAll(subject) {
+        const response = await this.#call("POST", `/users/${encodeURIComponent(subject)}/logout`);
+        if (response.status !== 204 && response.status !== 200)
+            throw rejected();
+    }
+    async #byUsername(username) {
+        const users = await this.#search({ username, exact: "true" });
+        return users.find((user) => user.username.toLowerCase() === username.toLowerCase())?.id;
+    }
+    async #search(query) {
+        const response = await this.#call("GET", `/users?${new URLSearchParams(query).toString()}`);
+        if (response.status !== 200 || !Array.isArray(response.body))
+            throw rejected();
+        const list = response.body;
+        return list.flatMap((entry) => isRecord(entry) && typeof entry.id === "string" && entry.id !== "" && typeof entry.username === "string"
+            ? [{ id: entry.id, username: entry.username, ...(typeof entry.email === "string" ? { email: entry.email } : {}) }]
+            : []);
+    }
+    /** One admin request with the service-account token; a 401 means the token died early, so it is renewed and the request is repeated once. */
+    async #call(method, path, body) {
+        const url = `${adminBaseOf(this.#options.issuer)}${path}`;
+        const attempt = async (renew) => send(this.#options, { method, url, headers: { authorization: `Bearer ${await this.#token(renew)}` }, ...(body === undefined ? {} : { body }) });
+        const first = await attempt(false);
+        return first.status === 401 ? attempt(true) : first;
+    }
+    #token(renew) {
+        const now = this.#options.clock.now().getTime();
+        if (!renew && this.#held !== undefined && this.#held.expiresAt - TOKEN_MARGIN_MS > now)
+            return Promise.resolve(this.#held.token);
+        this.#pending ??= this.#fetch().finally(() => {
+            this.#pending = undefined;
+        });
+        return this.#pending;
+    }
+    async #fetch() {
+        const client = this.#options.client;
+        if (client?.clientSecret === undefined)
+            throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "client.clientSecret" } });
+        const { tokenEndpoint } = await this.#discovery.get();
+        const response = await send(this.#options, {
+            method: "POST",
+            url: tokenEndpoint,
+            form: { grant_type: "client_credentials", client_id: client.clientId, client_secret: revealed(client.clientSecret) },
+        });
+        const answer = response.body;
+        if (response.status !== 200 || !isRecord(answer) || typeof answer.access_token !== "string" || typeof answer.expires_in !== "number" || !(answer.expires_in > 0))
+            throw rejected();
+        this.#held = { token: answer.access_token, expiresAt: this.#options.clock.now().getTime() + answer.expires_in * SECOND_MS };
+        return answer.access_token;
+    }
+}

package/dist/oidc/broker.d.ts

@@ -0,0 +1,57 @@
+import type { OidcAdminClient, OidcCreatedUser, OidcFoundUser, OidcNewUser } from "./admin.js";
+import type { OidcClient } from "./client.js";
+import type { OidcTokenClient } from "./grants.js";
+/** What a sign-in, a refresh or a social callback answers: the account, its roles and email, and the provider session's refresh token. No access token. */
+export interface OidcBrokerSession {
+    readonly subject: string;
+    readonly roles: readonly string[];
+    readonly email: string | null;
+    readonly refreshToken: string;
+    readonly refreshExpiresAt: Date;
+}
+/** The proof values of a federated sign-in the app owns, and the identity provider the realm brokers. */
+export interface OidcSocialRequest {
+    /** The alias of the identity provider in the realm (`google`, `github`), sent as `kc_idp_hint`. */
+    readonly provider: string;
+    readonly state: string;
+    readonly nonce: string;
+    /** The S256 challenge of the PKCE verifier the app keeps (`pkceChallenge`). */
+    readonly codeChallenge: string;
+}
+/** The callback of a federated sign-in, with the proof values the app kept. */
+export interface OidcSocialCallback {
+    readonly code: string;
+    readonly codeVerifier: string;
+    readonly nonce: string;
+}
+/**
+ * The one facade an app binds its identity port to when Keycloak sits behind the back end: the password grant, the refresh and the
+ * revocation of the provider session; the federated sign-in (the authorization address with `kc_idp_hint` and the code exchange); and the
+ * account administration (create, find by email, reset the password, end every session). The tokens stay on the server: a session answer
+ * carries the verified account, the refresh token and its expiry, never an access token.
+ *
+ * Failures are `OidcError`s: `unavailable` (the provider is down or throttling), `credentials-rejected` (a bad password or a dead refresh
+ * token), `email-registered`, `password-invalid` and `social-rejected` (a code, nonce or state the provider or the check refused).
+ */
+export declare class OidcBroker {
+    #private;
+    constructor(tokens: OidcTokenClient, client: OidcClient | null, admin: OidcAdminClient);
+    /** Signs in with a username or email and a password. */
+    passwordGrant(identifier: string, password: string): Promise<OidcBrokerSession>;
+    /** Renews a session from its refresh token; the answer holds the rotated refresh token. */
+    refresh(refreshToken: string): Promise<OidcBrokerSession>;
+    /** Ends the provider session of a refresh token. */
+    revoke(refreshToken: string): Promise<void>;
+    /** The address the browser goes to for a federated sign-in at the identity provider `provider`. */
+    socialAuthorizationUrl(input: OidcSocialRequest): Promise<string>;
+    /** Exchanges the code of a federated sign-in once. A code, nonce or answer the provider or the check refuses throws `social-rejected`; an outage stays `unavailable`. */
+    exchangeSocialCode(input: OidcSocialCallback): Promise<OidcBrokerSession>;
+    /** Creates an account with a permanent password. */
+    createUser(input: OidcNewUser): Promise<OidcCreatedUser>;
+    /** The account an email belongs to, or null. */
+    findUserByEmail(email: string): Promise<OidcFoundUser | null>;
+    /** Sets a permanent password. */
+    resetPassword(subject: string, password: string): Promise<void>;
+    /** Ends every provider session of the account. */
+    logoutAll(subject: string): Promise<void>;
+}

package/dist/oidc/broker.js

@@ -0,0 +1,77 @@
+import { OIDC_ERROR_CODES } from "../contracts/oidc.js";
+import { OidcError } from "./errors.js";
+const session = (grant) => ({
+    subject: grant.subject,
+    roles: grant.roles,
+    email: grant.email,
+    refreshToken: grant.refreshToken,
+    refreshExpiresAt: grant.refreshExpiresAt,
+});
+/**
+ * The one facade an app binds its identity port to when Keycloak sits behind the back end: the password grant, the refresh and the
+ * revocation of the provider session; the federated sign-in (the authorization address with `kc_idp_hint` and the code exchange); and the
+ * account administration (create, find by email, reset the password, end every session). The tokens stay on the server: a session answer
+ * carries the verified account, the refresh token and its expiry, never an access token.
+ *
+ * Failures are `OidcError`s: `unavailable` (the provider is down or throttling), `credentials-rejected` (a bad password or a dead refresh
+ * token), `email-registered`, `password-invalid` and `social-rejected` (a code, nonce or state the provider or the check refused).
+ */
+export class OidcBroker {
+    #tokens;
+    #client;
+    #admin;
+    constructor(tokens, client, admin) {
+        this.#tokens = tokens;
+        this.#client = client;
+        this.#admin = admin;
+    }
+    /** Signs in with a username or email and a password. */
+    async passwordGrant(identifier, password) {
+        return session(await this.#tokens.passwordGrant(identifier, password));
+    }
+    /** Renews a session from its refresh token; the answer holds the rotated refresh token. */
+    async refresh(refreshToken) {
+        return session(await this.#tokens.refresh(refreshToken));
+    }
+    /** Ends the provider session of a refresh token. */
+    async revoke(refreshToken) {
+        await this.#tokens.revoke(refreshToken);
+    }
+    /** The address the browser goes to for a federated sign-in at the identity provider `provider`. */
+    async socialAuthorizationUrl(input) {
+        return this.#registered().authorization({ state: input.state, nonce: input.nonce, challenge: input.codeChallenge, idpHint: input.provider });
+    }
+    /** Exchanges the code of a federated sign-in once. A code, nonce or answer the provider or the check refuses throws `social-rejected`; an outage stays `unavailable`. */
+    async exchangeSocialCode(input) {
+        const rejected = new OidcError(OIDC_ERROR_CODES.SocialRejected);
+        const identity = await this.#registered()
+            .exchange({ code: input.code, verifier: input.codeVerifier, nonce: input.nonce })
+            .catch((cause) => {
+            throw cause instanceof OidcError && cause.code === OIDC_ERROR_CODES.Rejected ? rejected : cause;
+        });
+        if (identity.refreshToken === undefined || identity.refreshExpiresAt === undefined)
+            throw rejected;
+        return { subject: identity.subject, roles: identity.roles, email: identity.email ?? null, refreshToken: identity.refreshToken, refreshExpiresAt: identity.refreshExpiresAt };
+    }
+    /** Creates an account with a permanent password. */
+    createUser(input) {
+        return this.#admin.createUser(input);
+    }
+    /** The account an email belongs to, or null. */
+    findUserByEmail(email) {
+        return this.#admin.findUserByEmail(email);
+    }
+    /** Sets a permanent password. */
+    resetPassword(subject, password) {
+        return this.#admin.resetPassword(subject, password);
+    }
+    /** Ends every provider session of the account. */
+    logoutAll(subject) {
+        return this.#admin.logoutAll(subject);
+    }
+    #registered() {
+        if (this.#client === null)
+            throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "client" } });
+        return this.#client;
+    }
+}

package/dist/oidc/client.d.ts

@@ -0,0 +1,58 @@
+import type { OidcIdentity } from "../contracts/oidc.js";
+import type { OidcDiscovery } from "./discovery.js";
+import type { ResolvedOidcOptions } from "./options.js";
+import type { OidcTokenVerifier } from "./tokens.js";
+/** The proof values the app owns and sends to the authorization endpoint. */
+export interface OidcAuthorization {
+    /** One-use transaction state. */
+    readonly state: string;
+    /** Binds the ID token to the browser transaction. */
+    readonly nonce: string;
+    /** The base64url SHA-256 digest of the retained PKCE verifier (`pkceChallenge`). */
+    readonly challenge: string;
+    /** `none`, `login`, `consent` or `select_account`, when the flow must not (or must) show a login page. */
+    readonly prompt?: "none" | "login" | "consent" | "select_account" | undefined;
+    /** The alias of an identity provider the realm brokers (`google`), sent as `kc_idp_hint` so the provider skips its own login page for it. */
+    readonly idpHint?: string | undefined;
+}
+/** A claimed callback, exchanged exactly once. */
+export interface OidcExchange {
+    /** The transient authorization code; never returned to the browser. */
+    readonly code: string;
+    /** The retained PKCE verifier. */
+    readonly verifier: string;
+    /** The nonce retained with the transaction. */
+    readonly nonce: string;
+    /** The `iss` of the authorization response, when the provider sent one; a supplied issuer must equal the configured one. */
+    readonly issuer?: string | undefined;
+}
+/** What a completed code exchange established: the identity, and the provider's refresh token when it issued one. The refresh token stays on the server. */
+export interface OidcExchangeResult extends OidcIdentity {
+    /** The refresh token of the provider session; absent when the provider issued none or none that can be dated. */
+    readonly refreshToken?: string;
+    /** When the refresh token stops being accepted; present with `refreshToken`. */
+    readonly refreshExpiresAt?: Date;
+}
+/** The address a browser is sent to for RP-initiated logout. */
+export interface OidcLogout {
+    /** Sent as `id_token_hint` when the app retained the ID token. */
+    readonly idTokenHint?: string | undefined;
+    /** Sent as `state`. */
+    readonly state?: string | undefined;
+}
+/**
+ * The authorization code flow of one registered client: it builds the authorization address (S256 PKCE, nonce, state), exchanges a
+ * code once at the token endpoint and verifies the ID token (signature, issuer, audience = the client, expiry, nonce) before it answers
+ * an identity, and builds the RP-initiated logout address. It never logs a provider token; the refresh token a code exchange answers is for the
+ * server's own store, never for a browser.
+ */
+export declare class OidcClient {
+    #private;
+    constructor(options: ResolvedOidcOptions, discovery: OidcDiscovery, tokens: OidcTokenVerifier);
+    /** The address the browser goes to for the registered code flow. */
+    authorization(input: OidcAuthorization): Promise<string>;
+    /** Exchanges a claimed code once, then verifies the ID token and answers the identity it asserts. */
+    exchange(input: OidcExchange): Promise<OidcExchangeResult>;
+    /** The RP-initiated logout address of the registered client. */
+    logout(input?: OidcLogout): Promise<string>;
+}