@starci/auth 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.6.0 - 2026-11-09
+
+One auth package for both editions: the OIDC sign-in of `@starci/auth-oidc` moves in, and the lite sign-in providers become pluggable. Every 0.5.0 export, option, door, cookie and code is unchanged.
+
+- Added: `@starci/auth/oidc`, everything `@starci/auth-oidc/server` held (discovery, JWKS, the token verifier, `OidcPrincipalVerifier`, roles, refresh, `OidcClient`, `OidcTokenClient`, `OidcAdminClient`, `OidcBroker`, `OidcModule`, `createOidc`) and the OIDC contract; the injection tokens keep their `Symbol.for("@starci/auth-oidc/...")` names. `@starci/auth/client/oidc` is `createOidcClient`; `@starci/auth/contracts` also carries the OIDC contract; `@starci/auth/testing` also carries `FakeOidcIssuer` (one `FakeClock` for both), which gains `endpoints()`.
+- Added: issuer presets in `@starci/auth/oidc`: `IssuerPreset` (issuer and aliases, pinned algorithms, a required audience, a pinned key set or discovery, required claims, `identityOf`) and `createIssuerVerifier`; `keycloakIssuer` (and `keycloakOptions`, the trust half of an `OidcModule` registration), `googleIssuer` (Google ID tokens, both spellings of `accounts.google.com`, Google's key set, a verified address, optionally a Workspace domain) and `githubActionsIssuer` (GitHub Actions OIDC: `https://token.actions.githubusercontent.com`, a required audience, the repository by name and by `sub`, optionally its id, the workflow files of `workflow_ref` and the refs), the CI attestation port of a full app. A refusal by a preset's policy is reason `policy` with the `claim` (a new `OidcRefusalReason`). `TokenExpectations.issuer` admits an issuer's aliases; `OidcKeys` takes any `OidcKeySource`; `principalOf` is the principal mapping the verifier and the Keycloak preset share.
+- Added: pluggable sign-in providers in `@starci/auth/server`: `SignInProvider` and `defineProvider` (id, options, state cookie, consent parameters, codes, `profileOf`, the passport strategy), `AuthOptions.providers`, `google(options)` and `github(options)` (passport-oauth2 against GitHub's OAuth app endpoints with `state` and PKCE, `read:user user:email`, the numeric account id as subject and the primary verified address), `OAuthStateClient` (the state store of 0.5.0 generalised to any provider: cookie `auth_<id>_state` on `/auth/<id>`, purpose `p: <id>`), `providersOf`, `buildProviders` and the token `AUTH_PROVIDERS`. `AuthDoors.beginProvider(id)` and `completeProvider(id)`, `AuthFlows.begin(id)` and `complete(id)`; `providerDoor`, `providerCallbackDoor` and `ProviderRedirect` in the contracts; `AuthAuthenticator.signInWithProvider` (optional, needed for a provider other than Google) with `ProviderProfile`; the codes `PASSPORT_PROVIDER_STATE_INVALID`, `PASSPORT_PROVIDER_REJECTED`, `PASSPORT_PROVIDER_UNAVAILABLE` and `PASSPORT_PROVIDERS_INVALID` (Google named both as the option and in the list, two providers with one id, an id that cannot be a door path).
+- Changed: `AuthOptions.google` may be absent (null and absent both mean no Google client). The Google round trip is the `google` provider: the same doors, the same `auth_google_state` cookie on `/auth/google` with the same signed value, the same `PASSPORT_GOOGLE_*` codes and the same `auth.google-sign-in-failed` event; `GoogleStateClient`, `GOOGLE_STATE_*`, `DEFAULT_GOOGLE_STATE_COOKIE`, `googleProfileOf` and `GoogleOptions` keep their names (now from `server/providers/google.ts`; `server/google-state.ts` is gone). A lite app's `AuthModule.register` needs no change and the migrations are the same files.
+- Changed: `jose` (6.2.12) serves both editions from this package; new dependency `passport-oauth2` 1.8.0 (already installed under `passport-google-oauth20`), dev dependency `@types/passport-oauth2` 1.8.0. The build stays ES modules with `.js` declarations, as both packages built.
+- Specs: every spec of `@starci/auth-oidc` passes in its new place (`src/oidc`, `src/client/oidc`, `src/testing/oidc.spec.ts`, `src/oidc/compat.spec.ts`); `src/server/providers/registry.spec.ts` (Google, GitHub and a stub third provider defined in one call and run end to end through the doors; the order, the defaults, the refusals), `github.spec.ts` (the profile), `oauth-state.spec.ts` (the Google cookie byte for byte as 0.5.0 wrote it; one provider's state never passes another's callback), `src/oidc/issuers/issuers.spec.ts` (each preset against the fake issuer; GitHub Actions: a valid run, another audience, another repository, an expired token, the pins). `npm run typecheck` also checks the OIDC tree with `--isolatedDeclarations` (`tsconfig.isolated.json`), as `@starci/auth-oidc` did.
+
+## 0.5.0 - 2026-11-08
+
+- Changed: `AuthError` extends `DomainError<AuthErrorCode>` of `@starci/common` (new dependency); its name, codes, constructor, `kind`, `context` and `cause` are unchanged, and it gains `params` (always empty).
+- Changed: the package's own non-array object guard is `isPlainRecord` of `@starci/common`.
+- Changed: requires `@starci/common` 1.0.1 (exact), the one copy an app installs, so `DomainError` stays one class (this version had not reached npm).
+
 ## 0.4.0 - 2026-11-04
 
 - Added: `RefreshCookieOptions.domains`: the refresh cookie's `Domain` follows the request host (its `Host` header without the port). A host equal to a listed domain, or ending in `.` and one, takes the longest that fits; any other host takes `domain`, else stays host-only, so one api signs in on localhost (host-only) and on a tunnel origin (its parent domain).

package/README.md

@@ -1,18 +1,27 @@
 # @starci/auth
 
-The sign-in of a lite StarCi app: one package, four entries.
+The sign-in of a StarCi app, for both editions: one package, eight entries. Lite apps issue their own identity (`./server`); full apps
+verify their identity provider's tokens (`./oidc`). Every provider and issuer lives here, so a new one is one file.
 
-| entry | holds |
-|---|---|
-| `@starci/auth/server` | the NestJS module (`AuthModule.register` / `registerAsync`), the token signer and verifier (EdDSA, multi-key JWKS), rotating sessions, the sign-in budget, the refresh cookie, the passport flows and the doors that run them |
-| `@starci/auth/client` | `createAuthClient`: access token in memory, one shared refresh, signed out only on 401 or 403 |
-| `@starci/auth/client/react` | `AuthProvider`, `useAuthSession`, `useAuthClient`, `useWhenSignedIn`, `useCooldown` (context and hooks over the client; no visual) |
-| `@starci/auth/contracts` | door paths, wire codes, claim names and answer shapes both sides read |
-| `@starci/auth/testing` | test keys, a fake clock, in-memory stores, `testAuthOptions` |
+| entry | edition | holds |
+|---|---|---|
+| `@starci/auth/server` | lite | the NestJS module (`AuthModule.register` / `registerAsync`), the token signer and verifier (EdDSA, multi-key JWKS), rotating sessions, the sign-in budget, the refresh cookie, the passport flows, the sign-in providers (`google`, `github`, `defineProvider`) and the doors that run them |
+| `@starci/auth/oidc` | full | `OidcModule.register` / `registerAsync` (also `createOidc` without Nest): issuer discovery, the provider's JWKS with caching and rotation, the token verifier, `OidcPrincipalVerifier`, role mapping, `OidcClient` (authorization code flow with PKCE, state and nonce), `OidcTokenClient`, `OidcAdminClient`, `OidcBroker`, and the issuer presets (`keycloakIssuer`, `googleIssuer`, `githubActionsIssuer`, `createIssuerVerifier`) |
+| `@starci/auth/client` | lite | `createAuthClient`: access token in memory, one shared refresh, signed out only on 401 or 403 |
+| `@starci/auth/client/oidc` | full | `createOidcClient`: the browser half of a public OIDC client (PKCE redirect, callback, one shared refresh, the token in memory) |
+| `@starci/auth/client/react` | lite | `AuthProvider`, `useAuthSession`, `useAuthClient`, `useWhenSignedIn`, `useCooldown` (context and hooks over the client; no visual) |
+| `@starci/auth/contracts` | both | door paths, wire codes, claim names and answer shapes both sides read, and the OIDC contract (algorithms, codes, claims, principal) |
+| `@starci/auth/testing` | both | test keys, a fake clock, in-memory stores, `testAuthOptions`, and `FakeOidcIssuer` (discovery, JWKS, token, revocation and admin endpoints, in memory or on a socket) |
+| `@starci/auth/migrations/*` | lite | the session tables (`identity-sessions.sql`, `identity-refresh-raced-successors.sql`) |
+
+An app reaches the package only through its glue: `integrations/passport` (lite) and `integrations/keycloak` (full) in the back end,
+`modules/auth/client.ts` in the front end (R328, `BE_AUTH_PASSPORT_OWNER`). The lint refuses `passport*`, `jose`, `bcryptjs`, `@nestjs/jwt`
+and every other JWT library in an app, and the retired `@starci/auth-oidc` everywhere.
 
-An app reaches the package only through `integrations/passport` (back end) and `modules/auth/client.ts` (front end); the lint refuses `passport*`, `jose`, `bcryptjs` and `@nestjs/jwt` in an app.
+The lite server throws one error class, `AuthError`; the OIDC side throws `OidcError`. Both are `DomainError`s of `@starci/common` whose
+`code` is a wire code, with the `kind` they travel as.
 
-## Back end
+## Lite: the back end
 
 ```ts
 AuthModule.registerAsync({
@@ -23,17 +32,99 @@ AuthModule.registerAsync({
 })
 ```
 
-The package reads no environment. The app parses its settings (BE-CONFIG-2) and passes typed options; secrets are passed as `{ reveal(): string }` holders or text. The app implements `SessionStore` over the tables of `migrations/identity-sessions.sql` (an app whose baseline holds the 0.2.0 tables adds `migrations/identity-refresh-raced-successors.sql`), `AccountDirectory` over its account doors (in a StarCi lite app, the managed `persistence/account-doors.port.ts` over the SECURITY DEFINER `be_auth_*` functions of the baseline), `RateCounter` over its shared counter, and `AuthAuthenticator` (the password and Google decisions) using `AuthPasswords` and `SignInBudget.counted` from the module.
+The package reads no environment. The app parses its settings (BE-CONFIG-2) and passes typed options; secrets are passed as `{ reveal(): string }` holders or text. The app implements `SessionStore` over the tables of `migrations/identity-sessions.sql` (an app whose baseline holds the 0.2.0 tables adds `migrations/identity-refresh-raced-successors.sql`), `AccountDirectory` over its account doors (in a StarCi lite app, the managed `persistence/account-doors.port.ts` over the SECURITY DEFINER `be_auth_*` functions of the baseline), `RateCounter` over its shared counter, and `AuthAuthenticator` (the password and provider decisions) using `AuthPasswords` and `SignInBudget.counted` from the module.
 
 Key rotation: list the new key first with its private key, keep the old key with its public key only, deploy, and drop the old key once its access tokens have expired. Every listed key verifies and is published by `AuthSessions.jwks()`.
 
+### Sign-in providers
+
+```ts
+import { github, google } from "@starci/auth/server"
+
+AuthModule.register({ ...options, google: null, providers: [google({ clientId, clientSecret, callbackUrl }), github({ clientId, clientSecret, callbackUrl })] })
+```
+
+Each provider is served at `/auth/<id>` (`AuthDoors.beginProvider(id, exchange)`) and `/auth/<id>/callback` (`completeProvider`), with
+`state` and PKCE (S256) kept in a signed, httpOnly cookie `auth_<id>_state` sent only to `/auth/<id>`, and a same-site landing path. The
+`google` option of 0.5.0 still works and means `providers: [google(options.google)]`; naming Google both ways is `PASSPORT_PROVIDERS_INVALID`.
+Google keeps its doors (`beginGoogle`, `completeGoogle`), its cookie (`auth_google_state`, the same signed `{ w, u, r, e, p: "google" }`
+value) and its codes (`PASSPORT_GOOGLE_*`). Google calls `AuthAuthenticator.signInWithGoogle(profile)`; every other provider calls
+`signInWithProvider(profile)` with a `ProviderProfile` (`provider`, `subject`, `email`, `emailVerified`, `name`, `picture`).
+
+GitHub (`github(...)`, an OAuth app) asks for `read:user user:email`, takes the numeric account id as the subject (never the login) and the
+primary verified address from `/user/emails`; a public address only is passed as unverified.
+
+A next provider is one file that calls `defineProvider({ id, options, profileOf, strategy })`: `strategy(context)` builds a passport
+strategy that keeps its round trip in `context.state` (an `OAuthStateClient`) and signs in through `signInWithProvider(context.authenticator, profile)`;
+the module registers it under `id` and the doors serve it.
+
+## Full: the back end
+
+```ts
+OidcModule.registerAsync({
+    isGlobal: true,
+    inject: [HTTP_CLIENT, CLOCK],
+    useFactory: (http: HttpClient, clock: Clock) => ({
+        ...keycloakOptions({ origin, realm, audience }), // or the parsed issuer, audience and role mapping
+        client: parsedClient,
+        http: { request: (request) => http.request({ correlationId: "identity-keycloak", ...request }) },
+        clock,
+    }),
+})
+```
+
+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 the lite verifier 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. 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).
+
+`OidcBroker` (token `OIDC_BROKER`) is the one facade an app that keeps Keycloak behind its back end binds its identity port to: `passwordGrant`, `refresh`, `revoke`, `socialAuthorizationUrl` (`kc_idp_hint`), `exchangeSocialCode`, `createUser`, `findUserByEmail`, `resetPassword`, `logoutAll` (the realm admin API as the client's service account). The injection tokens keep their 0.2.0 names (`Symbol.for("@starci/auth-oidc/...")`), so an app's providers resolve them unchanged.
+
+### Issuer presets
+
+A preset is the trust of one issuer as data plus one claim mapping (`IssuerPreset`: issuer and its aliases, pinned algorithms, required
+audience, where the keys are, required claims, `identityOf`); `createIssuerVerifier(preset, { http, clock })` verifies a token against it.
+A refusal names its `reason` (`audience`, `expired`, `signature`, `claims`, `policy` with the `claim` the policy refused, ...).
+
+| preset | verifies | yields |
+|---|---|---|
+| `keycloakIssuer({ origin, realm, audience, roles? })` | realm access tokens, keys from the realm's discovery document | the `OidcPrincipal` of the module's verifier |
+| `googleIssuer({ clientId, hostedDomain?, requireVerifiedEmail? })` | Google ID tokens (`https://accounts.google.com` or `accounts.google.com`, RS256, Google's pinned key set), a verified address unless told otherwise | `GoogleIdentity`: the lite `GoogleProfile` with `hostedDomain` |
+| `githubActionsIssuer({ audience, repository, repositoryId?, workflows?, refs? })` | GitHub Actions OIDC tokens (`https://token.actions.githubusercontent.com`, RS256, GitHub's pinned key set); the audience is required, the repository must match (and `sub` must name it), optionally the repository id, the workflow files of `workflow_ref` and the refs | `GitHubActionsRun`: repository, workflow, workflow path, ref, sha, run id, attempt, actor, event, environment |
+
+The CI attestation of a full app (a workflow run proving which repository, workflow, ref and commit it is) composes `githubActionsIssuer`
+inside `integrations/keycloak`; there is no separate integration for it.
+
 ## Front end
 
 ```ts
 // modules/auth/client.ts: the one instance
-export const auth = createAuthClient({ apiOrigin: () => apiOrigin() })
+export const auth = createAuthClient({ apiOrigin: () => apiOrigin() }) // lite
+export const auth = createOidcClient({ issuer: () => issuer(), clientId: "web", redirectUri: () => `${origin()}/auth/callback`, postLogoutRedirectUri: () => origin() }) // full
 ```
 
+The OIDC client's `signIn()` redirects to the provider; the callback page calls `completeSignIn(window.location.href)`; `restore()` signs in again without a page after a reload; `accessToken()`, `renew()`, `headers()`, `subscribe`, `getSnapshot`, `watch` and `signOut()` have the shape of the lite session surface.
+
+## Migrating from `@starci/auth-oidc`
+
+`@starci/auth-oidc` 0.3.0 is a deprecated re-export of this package. `starci app codemod auth-merge` (a dry run; `--execute` writes) rewrites
+`@starci/auth-oidc` and `@starci/auth-oidc/server` to `@starci/auth/oidc`, `/client` to `@starci/auth/client/oidc`, `/contracts` to
+`@starci/auth/oidc`, `/testing` to `@starci/auth/testing`, and the dependency in every package.json to `@starci/auth`.
+
 ## Tests
 
-`npm test` typechecks, lints and runs the `node:test` specs under 90% line coverage.
+`npm test` typechecks (the OIDC tree also under `--isolatedDeclarations`, `tsconfig.isolated.json`), lints and runs the `node:test` specs
+under 90% line coverage, including the assignability of the OIDC verifier and client to the lite interfaces (`src/oidc/compat.spec.ts`).
+
+```ts
+const issuer = await FakeOidcIssuer.create({ audience: "api" })
+const token = await issuer.mintAccessToken({ sub: "user-1", roles: ["member"] })
+const ci = createIssuerVerifier(githubActionsIssuer({ audience: "api", repository: "o/r", endpoints: issuer.endpoints() }), { http: issuer.http })
+```

package/dist/client/oidc/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/oidc.js";
+export type { OidcClientOutcome, OidcFailureKind, OidcSessionUser } from "../../contracts/oidc.js";

package/dist/client/oidc/index.js

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

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

@@ -0,0 +1,85 @@
+import type { SessionEvent, SessionListener, SessionSnapshot } from "../session.js";
+import type { OidcClientOutcome, OidcSessionUser } from "../../contracts/oidc.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/oidc-client.js

@@ -0,0 +1,304 @@
+import { createSessionStore, createSingleFlight } from "../session.js";
+import { OIDC_CLIENT_CODES } from "../../contracts/oidc.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/oidc/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/oidc/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;