@starci/auth 0.5.0 → 0.6.0

package/dist/server/providers/oauth-state.d.ts

@@ -0,0 +1,47 @@
+import type { HttpRequest } from "../http.js";
+import type { AuthClock, AuthIds } from "../ports.js";
+import type { AuthTokens } from "../tokens.js";
+/** How long one provider round trip may take, in milliseconds. */
+export declare const OAUTH_STATE_TTL_MS = 600000;
+/** The state cookie of a provider when its options name none: `auth_<id>_state` (Google's is `auth_google_state`). */
+export declare const oauthStateCookie: (provider: string) => string;
+/** Where one provider's round trip is kept. */
+export interface OAuthStateOptions {
+    /** The provider id, signed into the state as its purpose (`p`), so a state of one provider never passes another's callback. */
+    readonly provider: string;
+    /** The cookie that carries the round trip. */
+    readonly cookie: string;
+    /** The only path the cookie is sent to: the provider's door (`/auth/<id>`), which its callback sits under. */
+    readonly path: string;
+    /** The origin of the web app: an absolute return address is kept only on it. */
+    readonly returnOrigin: string;
+}
+/** What a state store needs. */
+export interface OAuthStateDeps {
+    readonly tokens: AuthTokens;
+    readonly clock: AuthClock;
+    readonly ids: AuthIds;
+    readonly state: OAuthStateOptions;
+}
+type StoreDone = (error: Error | null, handle?: string) => void;
+type VerifyDone = (error: Error | null, verifier?: unknown, context?: unknown) => void;
+/**
+ * The state store passport-oauth2 calls for `state` and PKCE without a server session, for any provider: the handle (echoed as
+ * `state`), the code verifier and the landing path travel in a signed, httpOnly cookie that only the provider's door path receives,
+ * and the handle is compared on return. The landing path is a same-site path only, so the callback can never redirect off the web
+ * origin. The signed value is `{ w: handle, u: verifier, r: landing, e: expiry, p: provider }` under the HMAC key `AuthTokens.signState`
+ * derives, so Google's cookie is the one 0.5.0 wrote, byte for byte in shape.
+ */
+export declare class OAuthStateClient {
+    #private;
+    constructor(deps: OAuthStateDeps);
+    /** The name of the state cookie. */
+    get cookieName(): string;
+    /** The provider this store keeps round trips of. */
+    get provider(): string;
+    /** Called by passport-oauth2 on the outbound leg (the five-argument PKCE form). */
+    store(req: HttpRequest, verifier: string, _state: unknown, _meta: unknown, done: StoreDone): void;
+    /** Called by passport-oauth2 on the return leg (the meta form, since this method takes four arguments): the cookie must be ours, unexpired, of this provider and carry the same handle as `state`. */
+    verify(req: HttpRequest, providedState: string, _meta: unknown, done: VerifyDone): void;
+}
+export {};

package/dist/server/providers/oauth-state.js

@@ -0,0 +1,74 @@
+import { cookieValue, sameSitePath, sameValue } from "../primitives.js";
+/** How long one provider round trip may take, in milliseconds. */
+export const OAUTH_STATE_TTL_MS = 600_000;
+/** The state cookie of a provider when its options name none: `auth_<id>_state` (Google's is `auth_google_state`). */
+export const oauthStateCookie = (provider) => `auth_${provider}_state`;
+/**
+ * The state store passport-oauth2 calls for `state` and PKCE without a server session, for any provider: the handle (echoed as
+ * `state`), the code verifier and the landing path travel in a signed, httpOnly cookie that only the provider's door path receives,
+ * and the handle is compared on return. The landing path is a same-site path only, so the callback can never redirect off the web
+ * origin. The signed value is `{ w: handle, u: verifier, r: landing, e: expiry, p: provider }` under the HMAC key `AuthTokens.signState`
+ * derives, so Google's cookie is the one 0.5.0 wrote, byte for byte in shape.
+ */
+export class OAuthStateClient {
+    #tokens;
+    #clock;
+    #ids;
+    #state;
+    constructor(deps) {
+        this.#tokens = deps.tokens;
+        this.#clock = deps.clock;
+        this.#ids = deps.ids;
+        this.#state = deps.state;
+    }
+    /** The name of the state cookie. */
+    get cookieName() {
+        return this.#state.cookie;
+    }
+    /** The provider this store keeps round trips of. */
+    get provider() {
+        return this.#state.provider;
+    }
+    /** Called by passport-oauth2 on the outbound leg (the five-argument PKCE form). */
+    store(req, verifier, _state, _meta, done) {
+        const handle = this.#ids.next();
+        const signed = this.#tokens.signState({
+            w: handle,
+            u: verifier,
+            r: this.#landingOf(req),
+            e: this.#clock.now().getTime() + OAUTH_STATE_TTL_MS,
+            p: this.#state.provider,
+        });
+        req.res?.cookie(this.#state.cookie, signed, {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: this.#state.path,
+            maxAge: OAUTH_STATE_TTL_MS,
+        });
+        done(null, handle);
+    }
+    /** The same-site path to land on: the requested return address when it is a path, or an absolute address on the web origin; else the root. */
+    #landingOf(req) {
+        const { returnTo, next } = req.query ?? {};
+        const wanted = typeof returnTo === "string" ? returnTo : next;
+        if (typeof wanted !== "string")
+            return "/";
+        if (!URL.canParse(wanted))
+            return sameSitePath(wanted, "/");
+        const url = new URL(wanted);
+        return url.origin === this.#state.returnOrigin ? sameSitePath(`${url.pathname}${url.search}`, "/") : "/";
+    }
+    /** Called by passport-oauth2 on the return leg (the meta form, since this method takes four arguments): the cookie must be ours, unexpired, of this provider and carry the same handle as `state`. */
+    verify(req, providedState, _meta, done) {
+        const header = req.headers.cookie;
+        const raw = cookieValue(Array.isArray(header) ? header.join("; ") : (header ?? ""), this.#state.cookie);
+        req.res?.clearCookie(this.#state.cookie, { httpOnly: true, secure: true, sameSite: "lax", path: this.#state.path });
+        const state = raw === "" ? null : this.#tokens.verifyState(raw, this.#clock.now());
+        if (state?.p !== this.#state.provider || typeof providedState !== "string" || !sameValue(state.w, providedState)) {
+            done(null, false, { message: "state" });
+            return;
+        }
+        done(null, state.u, { next: sameSitePath(state.r, "/") });
+    }
+}

package/dist/server/providers/provider.d.ts

@@ -0,0 +1,58 @@
+import type { Strategy } from "passport";
+import type { AuthErrorCode } from "../../contracts/index.js";
+import type { AuthAuthenticator, AuthSubject, ProviderProfile } from "../ports.js";
+import type { OAuthStateClient } from "./oauth-state.js";
+/** The codes a provider's doors refuse with: the provider is not configured, its round trip cannot be proved, or it refused the person. */
+export interface ProviderCodes {
+    readonly unavailable: AuthErrorCode;
+    readonly stateInvalid: AuthErrorCode;
+    readonly rejected: AuthErrorCode;
+}
+/** The codes of every provider but Google, which keeps the codes 0.5.0 answered with. */
+export declare const PROVIDER_CODES: ProviderCodes;
+/** What the module hands a provider to build its passport strategy. */
+export interface ProviderContext {
+    /** The app's sign-in decisions. */
+    readonly authenticator: AuthAuthenticator;
+    /** The state store of this provider's round trip (handle, PKCE verifier and landing path in a signed cookie). */
+    readonly state: OAuthStateClient;
+}
+/**
+ * One way to sign in through a third party (Google, GitHub, a next one): the whole of it lives in one file that calls `defineProvider`,
+ * and an app lists it in `AuthModule.register({ providers: [...] })`. The module gives it a state store, builds its passport strategy,
+ * registers the strategy under `id`, and the doors run `/auth/<id>` and `/auth/<id>/callback` for it.
+ */
+export interface SignInProvider<TOptions = unknown, TRaw = unknown> {
+    /** The provider id: the passport strategy name, the state purpose and the door segment. Lower-case letters, digits and dashes. */
+    readonly id: string;
+    /** The provider's options (client id, secret, callback address), typed and parsed by the app. */
+    readonly options: TOptions;
+    /** The cookie that carries one round trip (`auth_<id>_state` unless the options name one). */
+    readonly stateCookie: string;
+    /** The path that cookie is sent to: the provider's door (`/auth/<id>`). */
+    readonly statePath: string;
+    /** Extra parameters of the consent redirect (Google's `prompt: select_account`). */
+    readonly authorizeParams: Readonly<Record<string, string>>;
+    /** The codes its doors refuse with. */
+    readonly codes: ProviderCodes;
+    /** The facts the app needs from what the provider answered; an account without a subject is refused. */
+    readonly profileOf: (raw: TRaw) => ProviderProfile;
+    /** Builds the passport strategy (`state` and PKCE through `context.state`); the module registers it with passport under `id`. */
+    readonly strategy: (context: ProviderContext) => Strategy;
+}
+/** Any provider, whatever its options and raw profile: what `AuthModule.register` lists. */
+export type AnySignInProvider = SignInProvider<unknown, never>;
+/** What `defineProvider` takes: the id, the options, the profile mapping and the strategy, with the rest defaulted. */
+export interface ProviderDefinition<TOptions, TRaw> {
+    readonly id: string;
+    readonly options: TOptions;
+    readonly stateCookie?: string | undefined;
+    readonly authorizeParams?: Readonly<Record<string, string>> | undefined;
+    readonly codes?: ProviderCodes | undefined;
+    readonly profileOf: (raw: TRaw) => ProviderProfile;
+    readonly strategy: (context: ProviderContext) => Strategy;
+}
+/** A provider from its definition: the id is checked (it becomes a door path, a cookie name and a passport name), the state cookie, its path and the codes are defaulted. */
+export declare const defineProvider: <TOptions, TRaw>(definition: ProviderDefinition<TOptions, TRaw>) => SignInProvider<TOptions, TRaw>;
+/** Signs in the person a provider other than Google established, through the app's `signInWithProvider`; an app that has none refuses the provider. */
+export declare const signInWithProvider: (authenticator: AuthAuthenticator, profile: ProviderProfile) => Promise<AuthSubject>;

package/dist/server/providers/provider.js

@@ -0,0 +1,32 @@
+import { AUTH_ERROR_CODES, providerDoor } from "../../contracts/index.js";
+import { AuthError } from "../errors.js";
+import { oauthStateCookie } from "./oauth-state.js";
+/** The codes of every provider but Google, which keeps the codes 0.5.0 answered with. */
+export const PROVIDER_CODES = {
+    unavailable: AUTH_ERROR_CODES.ProviderUnavailable,
+    stateInvalid: AUTH_ERROR_CODES.ProviderStateInvalid,
+    rejected: AUTH_ERROR_CODES.ProviderRejected,
+};
+const PROVIDER_ID = /^[a-z][a-z0-9-]{0,31}$/u;
+/** A provider from its definition: the id is checked (it becomes a door path, a cookie name and a passport name), the state cookie, its path and the codes are defaulted. */
+export const defineProvider = (definition) => {
+    if (!PROVIDER_ID.test(definition.id))
+        throw new AuthError(AUTH_ERROR_CODES.ProvidersInvalid, { context: { reason: "a provider id is lower-case letters, digits and dashes", id: definition.id } });
+    return {
+        id: definition.id,
+        options: definition.options,
+        stateCookie: definition.stateCookie ?? oauthStateCookie(definition.id),
+        statePath: providerDoor(definition.id),
+        authorizeParams: definition.authorizeParams ?? {},
+        codes: definition.codes ?? PROVIDER_CODES,
+        profileOf: definition.profileOf,
+        strategy: definition.strategy,
+    };
+};
+/** Signs in the person a provider other than Google established, through the app's `signInWithProvider`; an app that has none refuses the provider. */
+export const signInWithProvider = (authenticator, profile) => {
+    if (authenticator.signInWithProvider === undefined) {
+        return Promise.reject(new AuthError(AUTH_ERROR_CODES.ProviderUnavailable, { context: { provider: profile.provider, reason: "the authenticator has no signInWithProvider" } }));
+    }
+    return authenticator.signInWithProvider(profile);
+};

package/dist/server/providers/registry.d.ts

@@ -0,0 +1,30 @@
+import type { Strategy } from "passport";
+import type { AuthOptions } from "../options.js";
+import type { AuthAuthenticator, AuthClock, AuthIds } from "../ports.js";
+import type { AuthTokens } from "../tokens.js";
+import { OAuthStateClient } from "./oauth-state.js";
+import type { AnySignInProvider } from "./provider.js";
+/**
+ * The providers of one registration, in order: Google from the `google` option of 0.5.0 when it is set, then `providers`. Two
+ * providers with one id (Google both as the option and in the list) are a configuration error, never a silent pick.
+ */
+export declare const providersOf: (options: Pick<AuthOptions, "google" | "providers">) => readonly AnySignInProvider[];
+/** One provider as the module runs it: its definition, its state store and its passport strategy (registered under its id). */
+export interface ProviderEntry {
+    readonly provider: AnySignInProvider;
+    readonly state: OAuthStateClient;
+    readonly strategy: Strategy;
+}
+/** What building the providers needs. */
+export interface ProviderRuntimeDeps {
+    readonly providers: readonly AnySignInProvider[];
+    readonly authenticator: AuthAuthenticator;
+    readonly tokens: AuthTokens;
+    readonly clock: AuthClock;
+    readonly ids: AuthIds;
+    readonly returnOrigin: string;
+    /** The Google state store the module already holds (`AUTH_GOOGLE_STATE`), reused for the Google provider. */
+    readonly googleState?: OAuthStateClient | undefined;
+}
+/** Builds each provider's state store and strategy and registers the strategy with passport under the provider id. */
+export declare const buildProviders: (deps: ProviderRuntimeDeps) => ReadonlyMap<string, ProviderEntry>;

package/dist/server/providers/registry.js

@@ -0,0 +1,37 @@
+import passport from "passport";
+import { AUTH_ERROR_CODES } from "../../contracts/index.js";
+import { AuthError } from "../errors.js";
+import { GOOGLE_PROVIDER_ID, google } from "./google.js";
+import { OAuthStateClient } from "./oauth-state.js";
+/**
+ * The providers of one registration, in order: Google from the `google` option of 0.5.0 when it is set, then `providers`. Two
+ * providers with one id (Google both as the option and in the list) are a configuration error, never a silent pick.
+ */
+export const providersOf = (options) => {
+    const listed = [...(options.google ? [google(options.google)] : []), ...(options.providers ?? [])];
+    const seen = new Set();
+    for (const provider of listed) {
+        if (seen.has(provider.id))
+            throw new AuthError(AUTH_ERROR_CODES.ProvidersInvalid, { context: { reason: "two providers share an id", id: provider.id } });
+        seen.add(provider.id);
+    }
+    return listed;
+};
+/** Builds each provider's state store and strategy and registers the strategy with passport under the provider id. */
+export const buildProviders = (deps) => {
+    const entries = new Map();
+    for (const provider of deps.providers) {
+        const reuse = provider.id === GOOGLE_PROVIDER_ID && deps.googleState?.cookieName === provider.stateCookie ? deps.googleState : undefined;
+        const state = reuse ??
+            new OAuthStateClient({
+                tokens: deps.tokens,
+                clock: deps.clock,
+                ids: deps.ids,
+                state: { provider: provider.id, cookie: provider.stateCookie, path: provider.statePath, returnOrigin: deps.returnOrigin },
+            });
+        const strategy = provider.strategy({ authenticator: deps.authenticator, state });
+        passport.use(provider.id, strategy);
+        entries.set(provider.id, { provider, state, strategy });
+    }
+    return entries;
+};

package/dist/server/strategies.d.ts

@@ -1,11 +1,7 @@
-import { Strategy as GoogleStrategy } from "passport-google-oauth20";
-import type { Profile } from "passport-google-oauth20";
 import { Strategy as LocalStrategy } from "passport-local";
-import type { GoogleStateClient } from "./google-state.js";
-import type { GoogleOptions } from "./options.js";
-import type { AuthAuthenticator, AuthSubject, GoogleProfile } from "./ports.js";
-/** The facts the app needs from a Google profile; an account without a subject is refused. */
-export declare const googleProfileOf: (profile: Profile) => GoogleProfile;
+import type { AuthAuthenticator, AuthSubject } from "./ports.js";
+/** The Google strategy and its profile mapping live with the Google provider; named here as 0.5.0 did. */
+export { PassportGoogleStrategy, googleProfileOf } from "./providers/google.js";
 declare const PassportLocalStrategy_base: new (...args: [] | [options: import("passport-local").IStrategyOptionsWithRequest] | [options: import("passport-local").IStrategyOptions]) => LocalStrategy & {
     validate(...args: any[]): unknown;
 };
@@ -16,14 +12,3 @@ export declare class PassportLocalStrategy extends PassportLocalStrategy_base {
     /** Called by passport with the posted pair; answers the person or throws the app's refusal. */
     validate(email: string, password: string): Promise<AuthSubject>;
 }
-declare const PassportGoogleStrategy_base: new (...args: [options: import("passport-google-oauth20").StrategyOptionsWithRequest] | [options: import("passport-google-oauth20").StrategyOptions] | [options: import("passport-google-oauth20").StrategyOptions] | [options: import("passport-google-oauth20").StrategyOptionsWithRequest]) => GoogleStrategy & {
-    validate(...args: any[]): unknown;
-};
-/** The Google OAuth 2.0 strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
-export declare class PassportGoogleStrategy extends PassportGoogleStrategy_base {
-    #private;
-    constructor(google: GoogleOptions, authenticator: AuthAuthenticator, state: GoogleStateClient);
-    /** Called by passport with Google's profile; answers the person the app stands it for. */
-    validate(_accessToken: string, _refreshToken: string, profile: Profile): Promise<AuthSubject>;
-}
-export {};

package/dist/server/strategies.js

@@ -1,25 +1,7 @@
 import { PassportStrategy } from "@nestjs/passport";
-import { Strategy as GoogleStrategy } from "passport-google-oauth20";
 import { Strategy as LocalStrategy } from "passport-local";
-import { AUTH_ERROR_CODES } from "../contracts/index.js";
-import { AuthError } from "./errors.js";
-import { revealed } from "./primitives.js";
-const verifiedOf = (profile) => {
-    const claim = profile._json.email_verified;
-    return claim === true || claim === "true";
-};
-/** The facts the app needs from a Google profile; an account without a subject is refused. */
-export const googleProfileOf = (profile) => {
-    if (profile.id === "")
-        throw new AuthError(AUTH_ERROR_CODES.GoogleRejected);
-    return {
-        subject: profile.id,
-        email: profile.emails?.[0]?.value ?? null,
-        emailVerified: verifiedOf(profile),
-        name: profile.displayName === "" ? null : profile.displayName,
-        picture: profile.photos?.[0]?.value ?? null,
-    };
-};
+/** The Google strategy and its profile mapping live with the Google provider; named here as 0.5.0 did. */
+export { PassportGoogleStrategy, googleProfileOf } from "./providers/google.js";
 /** The email and password strategy; the app decides whether the pair is right. */
 export class PassportLocalStrategy extends PassportStrategy(LocalStrategy, "local") {
     #authenticator;
@@ -32,24 +14,3 @@ export class PassportLocalStrategy extends PassportStrategy(LocalStrategy, "loca
         return this.#authenticator.verifyPassword(email, password);
     }
 }
-/** The Google OAuth 2.0 strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
-export class PassportGoogleStrategy extends PassportStrategy(GoogleStrategy, "google") {
-    #authenticator;
-    constructor(google, authenticator, state) {
-        super({
-            clientID: google.clientId,
-            clientSecret: revealed(google.clientSecret),
-            callbackURL: google.callbackUrl,
-            scope: ["openid", "email", "profile"],
-            state: true,
-            pkce: true,
-        });
-        this.#authenticator = authenticator;
-        // passport-oauth2 types describe only its session stores; the stateless PKCE store replaces the one it built.
-        Object.assign(this, { _stateStore: state });
-    }
-    /** Called by passport with Google's profile; answers the person the app stands it for. */
-    validate(_accessToken, _refreshToken, profile) {
-        return this.#authenticator.signInWithGoogle(googleProfileOf(profile));
-    }
-}

package/dist/server/verifier.d.ts

@@ -3,7 +3,7 @@ import type { AuthClock, AuthPrincipal } from "./ports.js";
 import type { AuthTokens } from "./tokens.js";
 /**
  * What `domain/identity` asks of an identity source: the principal of a bearer token, or a refusal. The lite edition's source is
- * `AuthPrincipalVerifier`; the full edition's is the OIDC verifier of `@starci/auth-oidc` behind this same interface, so guards,
+ * `AuthPrincipalVerifier`; the full edition's is the OIDC verifier of `@starci/auth/oidc` behind this same interface, so guards,
  * `@Public` and `@Credential` do not change between editions.
  */
 export interface PrincipalVerifier {

package/dist/testing/index.d.ts

@@ -1,5 +1,8 @@
 import type { AuthOptions, SigningKeyOptions } from "../server/options.js";
 import type { AccountDirectory, AccountStanding, AuthClock, AuthIds, NewSession, RateCounter, RefreshTokenRecord, SessionStore, SessionTransaction } from "../server/ports.js";
+/** The fake OIDC issuer of the full edition (Keycloak-shaped discovery, JWKS, token and admin endpoints), for the specs of an `integrations/keycloak` glue. */
+export { FakeOidcIssuer } from "./oidc.js";
+export type { FakeFailure, FakeOidcIssuerOptions, FakeRequest, FakeSeededUser, FakeTokenClaims, FakeUser, MintOverrides } from "./oidc.js";
 /** A generated Ed25519 key pair as the PEM texts the options take. */
 export interface TestKeyPair {
     readonly privateKey: string;

package/dist/testing/index.js

@@ -1,4 +1,6 @@
 import { generateKeyPairSync, randomUUID } from "node:crypto";
+/** The fake OIDC issuer of the full edition (Keycloak-shaped discovery, JWKS, token and admin endpoints), for the specs of an `integrations/keycloak` glue. */
+export { FakeOidcIssuer } from "./oidc.js";
 /** Generates an Ed25519 key pair (PKCS#8 private PEM, SPKI public PEM). */
 export const generateTestKeyPair = () => {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");

package/dist/testing/oidc.d.ts

@@ -0,0 +1,175 @@
+import type { JWK } from "jose";
+import type { OidcHttp, OidcHttpRequest, OidcHttpResponse, OidcOptions } from "../oidc/options.js";
+import type { OidcClock } from "../oidc/primitives.js";
+/** The claims of a token the fake issuer mints. */
+export interface FakeTokenClaims {
+    /** The subject (`user-1`). */
+    readonly sub?: string | undefined;
+    readonly email?: string | undefined;
+    readonly name?: string | undefined;
+    readonly username?: string | undefined;
+    /** The realm roles (`realm_access.roles`). */
+    readonly roles?: readonly string[] | undefined;
+    /** The client roles (`resource_access.<client>.roles`). */
+    readonly clientRoles?: Readonly<Record<string, readonly string[]>> | undefined;
+    /** The provider session (`sid`); one is generated when absent. */
+    readonly sessionId?: string | undefined;
+    /** Further claims, copied as they are. */
+    readonly extra?: Readonly<Record<string, unknown>> | undefined;
+}
+/** What a spec bends in one token to prove a refusal. */
+export interface MintOverrides {
+    /** The `iss` claim (the issuer's own when absent). */
+    readonly issuer?: string | undefined;
+    /** The `aud` claim (the issuer's `audience`, else its client id). */
+    readonly audience?: string | readonly string[] | undefined;
+    /** Seconds the token lives from `issuedAt` (the issuer's access TTL). Negative mints an expired token. */
+    readonly expiresInSeconds?: number | undefined;
+    /** The `iat` instant (the clock's now). */
+    readonly issuedAt?: Date | undefined;
+    /** The `nbf` instant. */
+    readonly notBefore?: Date | undefined;
+    /** The `kid` header: a text, or `null` to omit it (the signing key's id when absent). */
+    readonly kid?: string | null | undefined;
+    /** `foreign` signs with a key the issuer does not publish. */
+    readonly signer?: "current" | "foreign" | undefined;
+    /** The `typ` claim (`Bearer` for an access token, `ID` for an ID token). */
+    readonly type?: string | undefined;
+}
+/** The options of a fake issuer. */
+export interface FakeOidcIssuerOptions {
+    /** The realm segment of the issuer address (`test`). */
+    readonly realm?: string | undefined;
+    /** The origin of an in-memory issuer (`https://idp.test`); ignored with `listen`. */
+    readonly origin?: string | undefined;
+    /** The registered client id (`test-client`). */
+    readonly clientId?: string | undefined;
+    /** The client secret the token endpoint requires; none makes the client public. */
+    readonly clientSecret?: string | undefined;
+    /** The audience of access tokens (the client id). */
+    readonly audience?: string | undefined;
+    /** The signature algorithm (`RS256`). */
+    readonly algorithm?: "RS256" | "ES256" | undefined;
+    /** The clock token times are read from (the system clock). */
+    readonly clock?: OidcClock | undefined;
+    /** How long an access token lives, in seconds (300). */
+    readonly accessTtlSeconds?: number | undefined;
+    /** Serves the issuer over a real HTTP socket on 127.0.0.1, for a browser or a process that cannot use the in-memory port. */
+    readonly listen?: boolean | undefined;
+    /** How long a refresh token lives, in seconds (1800); answered as `refresh_expires_in`. */
+    readonly refreshTtlSeconds?: number | undefined;
+    /** The aliases of the identity providers the realm brokers; an authorization address with another `kc_idp_hint` is refused. Any alias is admitted when absent. */
+    readonly identityProviders?: readonly string[] | undefined;
+    /** Whether the discovery document advertises a `revocation_endpoint` (true); false makes a client fall back to the end-session endpoint. */
+    readonly revocation?: boolean | undefined;
+    /** The shortest password the realm's policy admits (8); a shorter one is refused as Keycloak refuses it. */
+    readonly minPasswordLength?: number | undefined;
+}
+/** An account of the fake realm, for the password grant and the admin API. */
+export interface FakeUser {
+    /** The account id: the `sub` of its tokens (generated when absent). */
+    readonly id?: string | undefined;
+    readonly username: string;
+    readonly email?: string | undefined;
+    readonly name?: string | undefined;
+    /** The realm roles its tokens carry. */
+    readonly roles?: readonly string[] | undefined;
+    /** False makes the password grant refuse the account (true). */
+    readonly enabled?: boolean | undefined;
+}
+/** A seeded account as the issuer holds it: its id is set. */
+export type FakeSeededUser = FakeUser & {
+    readonly id: string;
+};
+/** What a failure injection does to the next requests. */
+export type FakeFailure = {
+    readonly status: number;
+} | "network";
+/** A recorded request, for a spec to count what the code under test asked. */
+export interface FakeRequest {
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * A fake OIDC provider that behaves like Keycloak for what the package uses: the discovery document, the JWKS, the token endpoint (authorization
+ * code with PKCE, refresh token with rotation) and the logout endpoint, with keys that rotate and tokens a spec can bend (expired, wrong
+ * audience, wrong issuer, unknown key, foreign signature). Its `http` is an in-memory `OidcHttp` (no socket, no port), so an app's spec registers
+ * the module against it and needs no Keycloak; `listen: true` serves the same issuer on a real socket for a browser.
+ */
+export declare class FakeOidcIssuer {
+    #private;
+    readonly clientId: string;
+    private constructor();
+    /** Creates an issuer with one signing key, and starts its socket when `listen` is set. */
+    static create(options?: FakeOidcIssuerOptions): Promise<FakeOidcIssuer>;
+    /** The exact issuer: the `iss` claim and the `issuer` of the discovery document. */
+    get issuer(): string;
+    /** The in-memory outbound port: answers like the issuer's endpoints, with the failures the spec injected. */
+    get http(): OidcHttp;
+    /**
+     * Moves the issuer to another origin (`https://127.0.0.1:41001`), for a host that serves it on an address it only knows after it listens, as a
+     * test-world fake does. Tokens minted afterwards carry the new `iss` and the discovery document names the new endpoints; the keys stay.
+     */
+    rebase(origin: string): void;
+    /** Answers one request as the issuer's endpoints do (the request's URL is under the issuer's address); a host that serves the issuer itself calls this from its listener. */
+    serve(request: OidcHttpRequest): Promise<OidcHttpResponse>;
+    /** The same endpoints as a `fetch`, for a front-end client under test (the browser client takes a `fetch`, not an `OidcHttp`). */
+    get fetch(): typeof fetch;
+    /** The requests the issuer has answered, oldest first. */
+    get requests(): readonly FakeRequest[];
+    /** The `kc_idp_hint` of every authorization address `authorize` has played, oldest first (an address without a hint adds nothing). */
+    get idpHints(): readonly string[];
+    /** Adds an account the password grant admits (by username or email) and the admin API lists. Answers it with its id. */
+    seedUser(user: FakeUser & {
+        readonly password: string;
+    }): FakeSeededUser;
+    /** The account with this id, username or email (case-insensitive), as the issuer holds it now; undefined when there is none. */
+    findUser(identifier: string): FakeSeededUser | undefined;
+    /** True when the account's current password is this one. */
+    passwordMatches(identifier: string, password: string): boolean;
+    /** How many refresh tokens the issuer holds that can still be used. */
+    get liveRefreshTokens(): number;
+    /** How many requests asked this path (`/protocol/openid-connect/certs`, `/.well-known/openid-configuration`). */
+    count(path: string): number;
+    /** The issuer and key set addresses an issuer preset takes as `endpoints` to stand this double in for Google or GitHub Actions. */
+    endpoints(): {
+        readonly issuer: string;
+        readonly jwksUri: string;
+    };
+    /** The options a registration against this issuer takes: the issuer, the audience, the in-memory port, the clock, and the client when `callbackUri` is given. */
+    options(overrides?: Partial<OidcOptions> & {
+        readonly callbackUri?: string;
+        readonly postLogoutUri?: string;
+    }): OidcOptions;
+    /** The discovery document. */
+    metadata(): Readonly<Record<string, unknown>>;
+    /** The published key set: every key of the ring. */
+    jwks(): {
+        readonly keys: readonly JWK[];
+    };
+    /** The `kid` of the key that signs now. */
+    get keyId(): string;
+    /** Rotates the signing key: a new key signs from now on. The old keys stay published (so tokens already minted verify) unless `keepOld` is false. Answers the new `kid`. */
+    rotateKeys(options?: {
+        readonly keepOld?: boolean;
+    }): Promise<string>;
+    /** Mints an access token for the claims, signed by the current key unless an override bends it. */
+    mintAccessToken(claims?: FakeTokenClaims, overrides?: MintOverrides): Promise<string>;
+    /** Mints an ID token for the client, carrying the nonce of the transaction. */
+    mintIdToken(claims?: FakeTokenClaims, nonce?: string, overrides?: MintOverrides): Promise<string>;
+    /**
+     * Plays the browser of a code flow: reads the authorization address the code under test built, registers a one-use code for the claims, and
+     * answers the address the provider would redirect the browser to (the redirect address with `code`, `state` and `iss`).
+     */
+    authorize(authorizationUrl: string, claims?: FakeTokenClaims): string;
+    /** Makes the next `count` requests fail: with an HTTP status, or as a lost connection. */
+    failNext(failure?: FakeFailure, count?: number): void;
+    /** Bends every ID token the token endpoint mints from now on (an empty object restores them). */
+    bendIdTokens(overrides?: MintOverrides): void;
+    /** Ends every refresh token the issuer holds, as an administrator signing the person out of the provider would: the next refresh answers `invalid_grant`. */
+    revokeRefreshTokens(): void;
+    /** While down, every request fails as a lost connection (an outage); `false` brings the issuer back. */
+    setDown(down: boolean): void;
+    /** Stops the socket, when there is one. */
+    close(): Promise<void>;
+}