@starci/auth-oidc 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.1 - 2026-11-03
+
+- Changed: requires `@starci/auth` 0.2.1 (the raced refresh gets its own successor cookie; `SessionTokens.cookieKept` is gone). Nothing of this package reads it.
+
+## 0.1.0 - 2026-11-03
+
+The OIDC client of a full StarCi app (Keycloak) in one package, behind the `PrincipalVerifier` interface of `@starci/auth`. Lifted from the Keycloak integration of the first full app and generalised: no product names, every setting a typed option, no environment read.
+
+- Added: `@starci/auth-oidc/server`, the NestJS module `OidcModule.register` / `registerAsync` (and `createOidc` without Nest). `OidcDiscovery` reads the discovery document of the exact issuer and trusts its endpoints only on the issuer's origin over https. `OidcKeys` fetches the JWKS, caches it, refreshes it on an unknown `kid` at most once per cooldown, rejects private and symmetric keys and keeps the cached keys through a provider outage. `OidcTokenVerifier` pins the algorithms before any key is looked up and checks issuer, audience, expiry and not-before. `OidcPrincipalVerifier` implements `PrincipalVerifier`: the principal has the shape of `@starci/auth`'s with the roles the issuer granted, an ID or refresh token presented as a bearer is refused, and a provider outage throws an `unavailable` error instead of refusing. `OidcClient` is the authorization code flow of a registered client: S256 PKCE, state, nonce, one code exchange, ID token verification, RP-initiated logout.
+- Added: `@starci/auth-oidc/client`, `createOidcClient`: PKCE redirect, callback, `restore` (a `prompt=none` redirect), one shared refresh with refresh-ahead and backoff, the tokens in memory only, signed out only on a 401, a 403 or a 400 `invalid_grant`, a stable snapshot, an event listener and logout.
+- Changed: the client keeps no copy of the session snapshot or of the refresh-race guard: it imports `createSessionStore` and `createSingleFlight` from `@starci/auth/client` and requires `@starci/auth` 0.2.0.
+- Added: `@starci/auth-oidc/contracts` and `@starci/auth-oidc/testing` (`FakeOidcIssuer`: discovery, JWKS with rotation, access and ID token minting a spec can bend, the token endpoint with PKCE and rotating refresh tokens, failure injection, an in-memory port and a socket).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 starci183
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @starci/auth-oidc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The sign-in of a full StarCi app: the OIDC client of its identity provider (Keycloak), behind the same `PrincipalVerifier` interface as `@starci/auth` (the lite edition), so the guards, `@Public` and `@Credential` of an app do not change between editions. One package, four entries.
+
+| entry | holds |
+|---|---|
+| `@starci/auth-oidc/server` | `OidcModule.register` / `registerAsync` (also `createOidc` without Nest): issuer discovery, the provider's JWKS with caching and rotation, the token verifier (algorithm pinned, issuer, audience, expiry, `typ`), `OidcPrincipalVerifier`, role mapping, and `OidcClient`, the authorization code flow (PKCE S256, state, nonce, code exchange, ID token verification, RP-initiated logout) |
+| `@starci/auth-oidc/client` | `createOidcClient`: the browser half of a public client: PKCE redirect, callback, one shared refresh, the access token in memory, sign-out only when the provider ends the session |
+| `@starci/auth-oidc/contracts` | algorithms, wire codes, claim names, the principal and the outcome shapes both sides read |
+| `@starci/auth-oidc/testing` | `FakeOidcIssuer`: discovery, JWKS, token minting, the token endpoint and failure injection, in memory or on a socket, so an app tests without Keycloak |
+
+An app reaches the package only through `integrations/keycloak` (back end) and `modules/auth/client.ts` (front end); the lint refuses `jose` and every other JWT library in an app.
+
+## Back end
+
+```ts
+OidcModule.registerAsync({
+    isGlobal: true,
+    inject: [HTTP_CLIENT, CLOCK],
+    useFactory: (http: HttpClient, clock: Clock) => ({
+        ...parsedOptions, // issuer, audience, client registration, role mapping, from the app's config loader
+        http: { request: (request) => http.request({ correlationId: "identity-keycloak", ...request }) },
+        clock,
+    }),
+})
+```
+
+The package reads no environment. The app parses its settings (BE-CONFIG-2) and passes typed options; the client secret is passed as a `{ reveal(): string }` holder or text and revealed only for the token request. Every provider request goes through the `OidcHttp` port, so the app's bounded HTTP client (`platform/http`) is the one door; without the port the platform `fetch` is used with the request's deadline.
+
+| a bearer token | is checked by |
+|---|---|
+| the algorithm | pinned to `algorithms` (`RS256`) before any key is looked up; `none`, HMAC and unlisted algorithms are refused |
+| the key | the JWKS of the discovered `jwks_uri`, selected by `kid`; cached 10 minutes; an unknown `kid` refreshes it at most once per 30 seconds (rotation); an unreachable provider keeps the cached keys for 24 hours |
+| issuer, audience, expiry, not-before | the registration and the clock, with a clock skew of 5 seconds |
+| the token type | an ID token or a refresh token presented as a bearer is refused (`typ` must be `Bearer`) |
+| the roles | `realm_access.roles`, `resource_access.<client>.roles` of the mapped clients and the mapped flat claims; a claim of the wrong shape or past 128 roles refuses the token |
+
+`verify` answers `{ kind: "ok", value: OidcPrincipal }` or `{ kind: "refused", code: "PASSPORT_ACCESS_TOKEN_INVALID", detail: { reason } }` (the code `@starci/auth` refuses with; the reason is for the log). A provider that cannot be asked and has nothing cached throws an `OidcError` of kind `unavailable`, which the app maps to a 503, never a 401: an identity-provider outage does not sign anyone out.
+
+Endpoints a discovery document advertises are trusted only on the issuer's origin, over https, without credentials; `http:` is admitted only with `allowInsecureHttp` (a developer machine or a test double).
+
+### The glue in an app
+
+`integrations/keycloak` (slot `be.integrations.keycloak`) is declaration only, five files; no unit spec sits beside them (the proof is the integration spec of `src/tests/integration/keycloak/`, which drives an outage with `FakeOidcIssuer`, and the guard's own spec):
+
+| file | holds |
+|---|---|
+| `keycloak.options.ts` | the typed registered client (`issuer`, `audience`, `clientId`, `clientSecret: Secret`, `callbackUri`, `postLogoutUri`, `timeoutMs`) |
+| `keycloak.config.ts` | `parseKeycloakConfig(env: EnvSource)`: `env.url`, `env.string`, `env.secret`, `env.int`; no default address or credential |
+| `keycloak.decorators.ts` | the token of the package's verifier (`OIDC_PRINCIPAL_VERIFIER`), which `domain/identity` provides under its own `ACCESS_TOKEN_VERIFIER` |
+| `keycloak.registration.ts` | `keycloakModule(options, { isGlobal })` = `OidcModule.registerAsync` over `HTTP_CLIENT` and `CLOCK`, the `http` option adapting `HttpClient.request` with its correlation id |
+| `index.ts` | what the rest of the app reads: the config parser, the module function, the token and the package's `PrincipalVerifier` and `OidcPrincipal` types |
+
+`AuthGuard` of `domain/identity` reads the bearer token and asks the injected `PrincipalVerifier`, exactly as the lite guard asks `@starci/auth`'s: a verified principal is left on the request, a refusal is `IDENTITY_UNAUTHENTICATED`, and an `unavailable` error is not caught (the errors filter maps its kind to a 503).
+
+## Front end
+
+```ts
+// modules/auth/client.ts: the one instance
+export const auth = createOidcClient({ issuer: () => issuer(), clientId: "web", redirectUri: () => `${origin()}/auth/callback`, postLogoutRedirectUri: () => origin() })
+```
+
+`signIn()` redirects to the provider; the callback page calls `completeSignIn(window.location.href)`; `restore()` signs in again without a page after a reload (a `prompt=none` redirect, tried once); `accessToken()`, `renew()`, `headers()`, `subscribe`, `getSnapshot`, `watch` and `signOut()` have the shape of the `@starci/auth/client` session surface. The refresh token lives in memory with the access token and never in storage; a refresh ends the session only on a 401, a 403 or a 400 `invalid_grant`, and a 429, a 5xx or a lost connection is retried with backoff.
+
+## Tests
+
+`npm test` typechecks (including the assignability of the verifier and the client to the `@starci/auth` interfaces), lints, and runs the `node:test` specs under 90% line coverage. The suite needs `@starci/auth` built next to it (`file:../auth`).
+
+```ts
+const issuer = await FakeOidcIssuer.create({ audience: "api" })
+const moduleRef = await Test.createTestingModule({ imports: [OidcModule.register(issuer.options({ callbackUri }))] }).compile()
+const token = await issuer.mintAccessToken({ sub: "user-1", roles: ["member"] })
+issuer.setDown(true) // the provider is unreachable: verification throws an unavailable error
+```

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export { createOidcClient } from "./oidc-client.js";
+export type { OidcAuthClient, OidcClientOptions, OidcEvent, OidcListener, OidcSignedIn, OidcSnapshot, OidcStorage } from "./oidc-client.js";
+export { sameSitePath } from "./pkce.js";
+export { OIDC_CLIENT_CODES } from "../contracts/index.js";
+export type { OidcClientOutcome, OidcFailureKind, OidcSessionUser } from "../contracts/index.js";

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export { createOidcClient } from "./oidc-client.js";
+export { sameSitePath } from "./pkce.js";
+export { OIDC_CLIENT_CODES } from "../contracts/index.js";

package/dist/client/oidc-client.d.ts

@@ -0,0 +1,85 @@
+import type { SessionEvent, SessionListener, SessionSnapshot } from "@starci/auth/client";
+import type { OidcClientOutcome, OidcSessionUser } from "../contracts/index.js";
+/** The event a listener hears: the same four as `AuthEvent` of `@starci/auth/client`. */
+export type OidcEvent = SessionEvent;
+/** Called on every sign-in, sign-out and token refresh with the id of the person (null when signed out). */
+export type OidcListener = SessionListener;
+/** What a view reads: loading until the first answer, then signed in or out. The object changes only when the session does. */
+export type OidcSnapshot = SessionSnapshot<OidcSessionUser>;
+/** The small part of `Storage` the client needs: the transaction of one redirect lives here (and a sign-in hint), never a token. */
+export interface OidcStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The options of the client. */
+export interface OidcClientOptions {
+    /** The issuer (the realm address). */
+    readonly issuer: string | (() => string);
+    /** The registered public client. */
+    readonly clientId: string;
+    /** The exact registered redirect address, the page that calls `completeSignIn`. */
+    readonly redirectUri: string | (() => string);
+    /** The exact registered address the provider returns to after logout; without it sign-out only forgets the session here. */
+    readonly postLogoutRedirectUri?: string | (() => string) | undefined;
+    /** The requested scope (`openid`). */
+    readonly scope?: string | undefined;
+    /** The fetch to use (the global one when absent). */
+    readonly fetch?: typeof fetch | undefined;
+    /** Where the transaction of a redirect is kept: `sessionStorage` when the platform has it, else memory. */
+    readonly storage?: OidcStorage | undefined;
+    /** Takes the browser to an address (`location.assign`). */
+    readonly navigate?: ((url: string) => void) | undefined;
+    /** Refresh this long before the token really expires, so a request never carries a dying one (15 seconds). */
+    readonly refreshAheadMs?: number | undefined;
+    /** Tries a refresh makes before it gives up on a busy or unreachable provider (4). */
+    readonly retryAttempts?: number | undefined;
+    /** The base of the linear backoff between tries, in milliseconds (400). */
+    readonly retryBaseMs?: number | undefined;
+    /** The clock in milliseconds (`Date.now`). */
+    readonly now?: (() => number) | undefined;
+    /** The pause between tries (a timer). */
+    readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+/** What a finished sign-in answers: the person and where the page was going. */
+export interface OidcSignedIn {
+    readonly user: OidcSessionUser;
+    /** The same-site path `signIn` was asked to return to, or `/`. */
+    readonly returnTo: string;
+}
+/** The OIDC client of a front end: the access token lives in this closure's memory only, never in storage or a cookie. */
+export interface OidcAuthClient {
+    /** Takes the browser to the provider's login page (authorization code flow, PKCE S256, state, nonce). `prompt: "none"` asks without showing a page. */
+    signIn(options?: {
+        readonly returnTo?: string;
+        readonly prompt?: "none" | "login";
+    }): Promise<OidcClientOutcome<true>>;
+    /** Finishes the flow on the redirect page: checks the state and the issuer, exchanges the code once and keeps the grant. */
+    completeSignIn(callbackUrl: string): Promise<OidcClientOutcome<OidcSignedIn>>;
+    /** Signs in again without a page when this browser signed in before and holds no session now (a reload): a `prompt=none` redirect, tried once. */
+    restore(): Promise<OidcClientOutcome<"redirected" | "skipped">>;
+    /** Forgets the session and takes the browser to the provider's logout address. */
+    signOut(): Promise<void>;
+    /** Refreshes with the refresh token held in memory. Overlapping calls share one refresh. `undefined` when it cannot be refreshed. */
+    renew(): Promise<string | undefined>;
+    /** The access token of the current session, refreshed when missing or about to expire; `undefined` when signed out. */
+    accessToken(): Promise<string | undefined>;
+    /** The held access token without any request. */
+    peek(): string | undefined;
+    /** The signed-in person, or null when signed out. */
+    user(): Promise<OidcSessionUser | null>;
+    /** The `Authorization` header of the current session (an empty object when signed out). */
+    headers(): Promise<Record<string, string>>;
+    /** Forgets the session. */
+    drop(): void;
+    /** Listens to auth events; the first answer comes from a refresh. Answers the function that stops listening. */
+    subscribe(listener: OidcListener): () => void;
+    /** The current snapshot (stable between changes). */
+    getSnapshot: () => OidcSnapshot;
+    /** The snapshot for server rendering: always loading. */
+    getServerSnapshot: () => OidcSnapshot;
+    /** Calls `onChange` when the snapshot changes (the shape `useSyncExternalStore` takes). */
+    watch: (onChange: () => void) => () => void;
+}
+/** Creates the one OIDC client of a front end (one instance, like the event stream). */
+export declare const createOidcClient: (options: OidcClientOptions) => OidcAuthClient;

package/dist/client/oidc-client.js

@@ -0,0 +1,304 @@
+import { createSessionStore, createSingleFlight } from "@starci/auth/client";
+import { OIDC_CLIENT_CODES } from "../contracts/index.js";
+import { challengeOf, claimsOf, randomText, sameSitePath, textOf } from "./pkce.js";
+const TRANSACTION_KEY = "starci.oidc.tx.";
+const HINT_KEY = "starci.oidc.hint";
+const SILENT_KEY = "starci.oidc.silent";
+const TRANSACTION_TTL_MS = 600_000;
+const MILLISECONDS = 1000;
+/** The answers of a prompt-less request that mean "sign in on a page", not a failure. */
+const SILENT_ANSWERS = ["login_required", "interaction_required", "consent_required", "account_selection_required"];
+const failure = (kind, code) => ({ success: false, message: kind, error: code });
+const success = (data) => ({ success: true, message: "ok", data });
+const recordOf = (value) => (typeof value === "object" && value !== null ? Object.fromEntries(Object.entries(value)) : {});
+const grantOf = (body) => {
+    const fields = recordOf(body);
+    const { access_token: accessToken, expires_in: expiresIn, refresh_token: refreshToken, id_token: idToken, token_type: type } = fields;
+    if (typeof accessToken !== "string" || accessToken === "" || typeof expiresIn !== "number" || typeof type !== "string" || type.toLowerCase() !== "bearer")
+        return undefined;
+    return { accessToken, expiresIn, refreshToken: textOf(refreshToken), idToken: textOf(idToken) };
+};
+const memoryStorage = () => {
+    const held = new Map();
+    return {
+        getItem: (key) => held.get(key) ?? null,
+        setItem: (key, value) => {
+            held.set(key, value);
+        },
+        removeItem: (key) => {
+            held.delete(key);
+        },
+    };
+};
+const isStorage = (value) => typeof value === "object" && value !== null && "getItem" in value && "setItem" in value && "removeItem" in value;
+const platformStorage = () => {
+    try {
+        const candidate = Reflect.get(globalThis, "sessionStorage");
+        return isStorage(candidate) ? candidate : memoryStorage();
+    }
+    catch {
+        return memoryStorage();
+    }
+};
+const platformNavigate = (url) => {
+    const location = Reflect.get(globalThis, "location");
+    const assign = typeof location === "object" && location !== null ? Reflect.get(location, "assign") : undefined;
+    if (typeof assign === "function" && typeof location === "object")
+        Reflect.apply(assign, location, [url]);
+};
+const timerPause = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(() => {
+        clearTimeout(timer);
+        resolve();
+    }, ms);
+});
+const parseTransaction = (raw) => {
+    if (raw === null)
+        return undefined;
+    try {
+        const fields = recordOf(JSON.parse(raw));
+        const { verifier, nonce, returnTo, at } = fields;
+        return typeof verifier === "string" && typeof nonce === "string" && typeof returnTo === "string" && typeof at === "number" ? { verifier, nonce, returnTo, at } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Creates the one OIDC client of a front end (one instance, like the event stream). */
+export const createOidcClient = (options) => {
+    const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+    const storage = options.storage ?? platformStorage();
+    const navigate = options.navigate ?? platformNavigate;
+    const refreshAheadMs = options.refreshAheadMs ?? 15_000;
+    const attemptsMax = options.retryAttempts ?? 4;
+    const retryBaseMs = options.retryBaseMs ?? 400;
+    const now = options.now ?? Date.now;
+    const pause = options.sleep ?? timerPause;
+    const scope = options.scope ?? "openid";
+    const valueOf = (value) => (typeof value === "string" ? value : value());
+    let token;
+    let refreshToken;
+    let idToken;
+    let expiresAt = 0;
+    let announced = false;
+    let user = null;
+    let discovered;
+    // The snapshot, the listeners and the watchers are the session store of @starci/auth/client, the one every provider's client shares.
+    const store = createSessionStore({
+        announced: () => announced,
+        announce: () => {
+            announced = true;
+        },
+        held: () => token !== undefined,
+        userId: () => user?.id ?? null,
+        renew: () => renew(),
+        refreshing: () => flight.running(),
+    });
+    const userOf = (grant) => {
+        const { sub, email } = claimsOf(grant.idToken ?? grant.accessToken);
+        return typeof sub === "string" ? { id: sub, email: typeof email === "string" ? email : "" } : null;
+    };
+    const keep = (grant, event) => {
+        token = grant.accessToken;
+        // A refresh answers a new refresh token when the provider rotates; one that does not leaves the held one valid.
+        refreshToken = grant.refreshToken ?? refreshToken;
+        idToken = grant.idToken ?? idToken;
+        expiresAt = now() + grant.expiresIn * MILLISECONDS;
+        announced = true;
+        user = userOf(grant);
+        storage.setItem(HINT_KEY, "1");
+        store.signedIn(user);
+        store.emit(event, user?.id ?? null);
+    };
+    const drop = () => {
+        const had = token !== undefined;
+        token = undefined;
+        refreshToken = undefined;
+        idToken = undefined;
+        expiresAt = 0;
+        announced = true;
+        user = null;
+        store.signedOut();
+        if (had)
+            store.emit("SIGNED_OUT", null);
+    };
+    function refreshEvent() {
+        if (!announced)
+            return "INITIAL_SESSION";
+        return token === undefined ? "SIGNED_IN" : "TOKEN_REFRESHED";
+    }
+    const discover = () => {
+        discovered ??= (async () => {
+            const response = await fetcher(`${valueOf(options.issuer).replace(/\/$/u, "")}/.well-known/openid-configuration`, { headers: { accept: "application/json" } });
+            const document = recordOf(await response.json().catch(() => undefined));
+            const { authorization_endpoint: authorization, token_endpoint: tokenEndpoint, end_session_endpoint: endSession, issuer } = document;
+            if (!response.ok || issuer !== valueOf(options.issuer) || typeof authorization !== "string" || typeof tokenEndpoint !== "string")
+                throw new Error(OIDC_CLIENT_CODES.Provider);
+            return { authorization, token: tokenEndpoint, endSession: typeof endSession === "string" ? endSession : undefined };
+        })().catch((cause) => {
+            discovered = undefined;
+            throw cause;
+        });
+        return discovered;
+    };
+    const tokenRequest = async (form) => {
+        const { token: endpoint } = await discover();
+        const response = await fetcher(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams({ client_id: options.clientId, ...form }).toString(),
+        });
+        return { status: response.status, body: await response.json().catch(() => undefined) };
+    };
+    /** True when the answer to a refresh says the session is over: the provider refused the refresh token (401, 403, or 400 `invalid_grant`). A 429, a 5xx or a lost connection never ends a session. */
+    const endsSession = (status, body) => status === 401 || status === 403 || (status === 400 && recordOf(body).error === "invalid_grant");
+    const requestRefresh = async (attempt = 1) => {
+        const retry = async () => {
+            await pause(retryBaseMs * attempt);
+            return requestRefresh(attempt + 1);
+        };
+        const held = refreshToken;
+        if (held === undefined) {
+            drop();
+            return undefined;
+        }
+        try {
+            const answer = await tokenRequest({ grant_type: "refresh_token", refresh_token: held });
+            if (answer.status === 200) {
+                const grant = grantOf(answer.body);
+                if (grant === undefined)
+                    return undefined;
+                keep(grant, refreshEvent());
+                return grant.accessToken;
+            }
+            if (endsSession(answer.status, answer.body)) {
+                storage.removeItem(HINT_KEY);
+                drop();
+                return undefined;
+            }
+            if ((answer.status === 429 || answer.status >= 500) && attempt < attemptsMax)
+                return await retry();
+            return undefined;
+        }
+        catch {
+            return attempt < attemptsMax ? retry() : undefined;
+        }
+    };
+    // Many requests answered 401 together refresh once: the others await the one in flight.
+    const flight = createSingleFlight(() => requestRefresh());
+    const renew = () => flight.run();
+    const accessToken = async () => (token !== undefined && expiresAt - refreshAheadMs > now() ? token : renew());
+    const signIn = async (input = {}) => {
+        try {
+            const { authorization } = await discover();
+            const state = randomText();
+            const nonce = randomText();
+            const verifier = randomText();
+            const transaction = { verifier, nonce, returnTo: sameSitePath(input.returnTo, "/"), at: now() };
+            storage.setItem(TRANSACTION_KEY + state, JSON.stringify(transaction));
+            const url = new URL(authorization);
+            url.search = new URLSearchParams({
+                response_type: "code",
+                client_id: options.clientId,
+                redirect_uri: valueOf(options.redirectUri),
+                scope,
+                state,
+                nonce,
+                code_challenge: await challengeOf(verifier),
+                code_challenge_method: "S256",
+                ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+            }).toString();
+            navigate(url.toString());
+            return success(true);
+        }
+        catch {
+            return failure("unavailable", OIDC_CLIENT_CODES.Transport);
+        }
+    };
+    const completeSignIn = async (callbackUrl) => {
+        const query = new URL(callbackUrl).searchParams;
+        const state = query.get("state") ?? "";
+        const key = TRANSACTION_KEY + state;
+        const transaction = state === "" ? undefined : parseTransaction(storage.getItem(key));
+        storage.removeItem(key);
+        storage.removeItem(SILENT_KEY);
+        if (transaction === undefined || now() - transaction.at > TRANSACTION_TTL_MS)
+            return failure("invalid", OIDC_CLIENT_CODES.State);
+        const refusal = query.get("error");
+        if (refusal !== null) {
+            if (SILENT_ANSWERS.includes(refusal))
+                storage.removeItem(HINT_KEY);
+            drop();
+            return failure("refused", refusal);
+        }
+        const issuer = query.get("iss");
+        if (issuer !== null && issuer !== valueOf(options.issuer))
+            return failure("invalid", OIDC_CLIENT_CODES.Issuer);
+        const code = query.get("code");
+        if (code === null || code === "")
+            return failure("invalid", OIDC_CLIENT_CODES.Token);
+        try {
+            const answer = await tokenRequest({ grant_type: "authorization_code", code, redirect_uri: valueOf(options.redirectUri), code_verifier: transaction.verifier });
+            const grant = answer.status === 200 ? grantOf(answer.body) : undefined;
+            if (grant === undefined)
+                return failure(answer.status >= 500 ? "unavailable" : "refused", answer.status >= 500 ? OIDC_CLIENT_CODES.Transport : OIDC_CLIENT_CODES.Provider);
+            if (grant.idToken !== undefined && claimsOf(grant.idToken).nonce !== transaction.nonce)
+                return failure("invalid", OIDC_CLIENT_CODES.Nonce);
+            keep(grant, "SIGNED_IN");
+            return user === null ? failure("invalid", OIDC_CLIENT_CODES.Token) : success({ user, returnTo: transaction.returnTo });
+        }
+        catch {
+            return failure("unavailable", OIDC_CLIENT_CODES.Transport);
+        }
+    };
+    const restore = async () => {
+        if (token !== undefined || storage.getItem(HINT_KEY) !== "1" || storage.getItem(SILENT_KEY) === "1")
+            return success("skipped");
+        storage.setItem(SILENT_KEY, "1");
+        const started = await signIn({ prompt: "none", returnTo: currentPath() });
+        if (started.success)
+            return success("redirected");
+        storage.removeItem(SILENT_KEY);
+        return started;
+    };
+    const currentPath = () => {
+        const location = Reflect.get(globalThis, "location");
+        const pathname = typeof location === "object" && location !== null ? Reflect.get(location, "pathname") : undefined;
+        return typeof pathname === "string" ? pathname : "/";
+    };
+    const signOut = async () => {
+        const hint = idToken;
+        const target = options.postLogoutRedirectUri;
+        storage.removeItem(HINT_KEY);
+        const endpoint = await discover().then((found) => found.endSession, () => undefined);
+        drop();
+        if (endpoint === undefined || target === undefined)
+            return;
+        const url = new URL(endpoint);
+        url.search = new URLSearchParams({
+            client_id: options.clientId,
+            post_logout_redirect_uri: valueOf(target),
+            ...(hint === undefined ? {} : { id_token_hint: hint }),
+        }).toString();
+        navigate(url.toString());
+    };
+    return {
+        signIn,
+        completeSignIn,
+        restore,
+        signOut,
+        renew,
+        accessToken,
+        peek: () => token,
+        user: async () => ((await accessToken()) === undefined ? null : user),
+        headers: async () => {
+            const held = await accessToken();
+            return held === undefined ? {} : { authorization: `Bearer ${held}` };
+        },
+        drop,
+        subscribe: store.subscribe,
+        getSnapshot: store.getSnapshot,
+        getServerSnapshot: store.getServerSnapshot,
+        watch: store.watch,
+    };
+};

package/dist/client/pkce.d.ts

@@ -0,0 +1,15 @@
+/** base64url of bytes, without padding. */
+export declare const bytesToBase64Url: (bytes: Uint8Array) => string;
+/** 256 unpredictable bits as base64url: a state, a nonce or a PKCE verifier (43 characters, inside the 43 to 128 RFC 7636 asks). */
+export declare const randomText: () => string;
+/** The S256 challenge of a PKCE verifier: base64url(SHA-256(verifier)). */
+export declare const challengeOf: (verifier: string) => Promise<string>;
+/** Non-empty text, else undefined. */
+export declare const textOf: (value: unknown) => string | undefined;
+/**
+ * The claims of a token read WITHOUT checking its signature. For display only (who is signed in): the front end trusts no claim for a
+ * decision, the back end verifies every token it is sent.
+ */
+export declare const claimsOf: (token: string) => Readonly<Record<string, unknown>>;
+/** A same-site path (one leading slash, no line break), else the fallback path: a return address never leaves the site. */
+export declare const sameSitePath: (value: unknown, fallback: string) => string;

package/dist/client/pkce.js

@@ -0,0 +1,29 @@
+/** base64url of bytes, without padding. */
+export const bytesToBase64Url = (bytes) => btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+/** 256 unpredictable bits as base64url: a state, a nonce or a PKCE verifier (43 characters, inside the 43 to 128 RFC 7636 asks). */
+export const randomText = () => bytesToBase64Url(crypto.getRandomValues(new Uint8Array(32)));
+/** The S256 challenge of a PKCE verifier: base64url(SHA-256(verifier)). */
+export const challengeOf = async (verifier) => bytesToBase64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+/** Non-empty text, else undefined. */
+export const textOf = (value) => (typeof value === "string" && value !== "" ? value : undefined);
+/**
+ * The claims of a token read WITHOUT checking its signature. For display only (who is signed in): the front end trusts no claim for a
+ * decision, the back end verifies every token it is sent.
+ */
+export const claimsOf = (token) => {
+    const payload = token.split(".")[1];
+    if (payload === undefined)
+        return {};
+    try {
+        const text = new TextDecoder().decode(Uint8Array.from(atob(payload.replaceAll("-", "+").replaceAll("_", "/")), (char) => char.charCodeAt(0)));
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? Object.fromEntries(Object.entries(parsed)) : {};
+    }
+    catch {
+        return {};
+    }
+};
+const SAME_SITE_PATH = /^\/(?![/\\])/u;
+const LINE_BREAK = /[\r\n]/u;
+/** A same-site path (one leading slash, no line break), else the fallback path: a return address never leaves the site. */
+export const sameSitePath = (value, fallback) => typeof value === "string" && SAME_SITE_PATH.test(value) && !LINE_BREAK.test(value) ? value : fallback;