@idp.global/sdk 19.5.0 → 19.6.0

package/readme.md

@@ -559,8 +559,10 @@ What it does:
 - **Login**: `GET /auth/login?return=/path` stores one login attempt (state and
   browser binding stored as SHA-256, PKCE verifier sealed) and redirects to the
   provider. `GET /auth/callback` consumes the attempt exactly once, exchanges
-  the code, reads UserInfo with a subject check, calls `principals.admit` and
-  opens a session; a provider `error` abandons the attempt. `GET /auth/finalize`
+  the code, verifies the ID token (its RS256 signature against idp.global's
+  JWKS, its issuer, audience and nonce), reads UserInfo with a subject check,
+  calls `principals.admit` and opens a session; a provider `error` abandons the
+  attempt. `GET /auth/finalize`
   releases the return path only to the browser holding the session that attempt
   created. Return paths stay on the public origin and outside the login routes.
   Expired attempts are swept when the next login starts.
@@ -583,7 +585,8 @@ What it does:
   the routes follow it only when it is a plain path on the public origin
   outside the login routes, exactly as given, and otherwise answer as if it
   named none.
-- **Sessions**: an HttpOnly, `SameSite=Lax` cookie whose token is stored as a
+- **Sessions**: an HttpOnly, `SameSite=Lax` (by default, see "Framed
+  applications" below) cookie whose token is stored as a
   hash, touched at most once a minute, with a CSRF token derived per request as
   an HMAC of the cookie token. `GET /auth/session` answers the session and
   `POST /auth/logout` needs the public origin and the CSRF token; its body is
@@ -596,7 +599,8 @@ What it does:
 - **Provider tokens**: sealed with AES-256-GCM (`SecretBox`) and rotated shortly
   before they expire, once per process and under a lock stored on the session,
   so two replicas never spend one refresh token. A refused refresh ends the
-  session; an unreachable provider fails closed.
+  session; an unreachable provider fails closed, and so does a refresh whose ID
+  token does not verify against the JWKS.
 - **Live authority**: `AuthorityObserver.observe({ loginSessionId, principalId,
   idpOrganizationId })` introspects the organization with the session's live
   token and projects the role keys through the application's table. It answers
@@ -630,9 +634,46 @@ login's cause. Custom `cookieNames` with a `__Host-` or `__Secure-` prefix need
 an https `publicOrigin`; on http the constructor refuses them, because browsers
 would silently drop those cookies.
 
+**Framed applications.** The session cookie and the login's intent cookie are
+`SameSite=Lax`, so a browser never sends them into a page of the application
+that another site frames. `cookiePolicy` changes that for both cookies, on
+every `Set-Cookie` that sets or clears them:
+
+```ts
+const sessions = new RelyingPartySessions({
+  // …
+  cookiePolicy: { sameSite: 'None', partitioned: true },
+});
+```
+
+- `sameSite: 'None'` sends the cookies with the framed page's requests too.
+  It needs an https `publicOrigin`, since a `SameSite=None` cookie must be
+  `Secure`.
+- `partitioned: true` adds `Partitioned` (CHIPS): the browser keeps the
+  cookies per top-level site, so the application has one jar under each site
+  that frames it, where a browser that blocks third-party cookies would
+  otherwise drop them. It is valid only with `sameSite: 'None'`.
+- The constructor refuses `partitioned` without `sameSite: 'None'`,
+  `sameSite: 'None'` on http, any other `sameSite` value and a `partitioned`
+  that is not a boolean. Bearer-only mode refuses `cookiePolicy` altogether.
+  `sessions.cookiePolicy` answers the resolved policy; the default is
+  `{ sameSite: 'Lax', partitioned: false }`.
+- With `SameSite=None` the browser also sends the session cookie with other
+  sites' requests to the application, so the CSRF token (`validateCsrf`) and
+  the origin check are its only CSRF defence: check them on every request that
+  changes something.
+- A partitioned cookie belongs to the top-level site of the window that
+  received it. A login that leaves the frame, in a popup or a new tab, sets its
+  cookies in the application's own top-level jar, where the frame never reads
+  them, so the whole login, `/auth/login` through `/auth/finalize`, has to run
+  inside the frame. Where the provider's login cannot run framed, the framed
+  application signs in with a bearer `popup` login instead (see "Bearer
+  Hand-off").
+
 **Adopting existing session data.** The persisted fields and index declarations
 are those nevermind.finance has stored since mainapp 0b693cb, and the session
-model adds an `expiresAt` index, built on first use. An application that
+model adds an `expiresAt` index and the bearer hand-off and token models a
+`sessionId` index, each built on first use. An application that
 already holds such collections binds the models to them and passes its own
 cookie names and CSRF label, so live sessions and sealed tokens keep working:
 
@@ -657,7 +698,11 @@ Nothing runs on a timer. A login start first removes up to 100 login attempts
 and up to 100 sessions that ended more than an hour ago, and a bearer login
 start also its bearer hand-offs and token generations; `openBearerHandoff`
 removes the bearer state and the sessions, `openSession` the sessions only.
-Removing an ended session fires no end hook and calls no provider.
+Removing an ended session fires no end hook and calls no provider. In bearer
+mode a session's hand-offs and token generations go before its row, so none
+outlives the session, and a removal that fails half way is finished by the
+next one. `endSessionsOfPrincipal` ends the principal's live sessions; one that
+expired is over already and is neither ended nor counted.
 
 **Deleting an account.** The sweeps above run only when a session is created,
 so an ended session can stay stored for long on a quiet service.
@@ -688,13 +733,44 @@ await users.delete(userId);
   covered. It keeps the principal id until it expires and a later sweep
   removes it. A second `eraseSessionsOfPrincipal(principalId)`, run after the
   user record is deleted, removes it. A token generation issued by a refresh
-  already under way is not covered either; it outlives its session row as
-  described below.
-- A token generation, and for at most a minute a hand-off, outlives the row
-  of its session when that session was revoked and swept before its expiry.
-  It holds only hashes, the session id and times, the bearer sweep removes it
-  an hour after the session would have expired, and the erase cannot
-  attribute it to the principal any more.
+  already under way is not covered either; it holds only hashes, the session
+  id and times, and the bearer sweep removes it an hour after the session
+  would have expired.
+
+**Telling provider failures apart.** Every failure of the provider half is an
+`OidcProviderError`, so an application classifies it without importing
+openid-client. `code` (`TOidcProviderErrorCode`) says which case it is, and
+`oauthError` the provider's own OAuth error code when it sent one, such as
+`invalid_grant` (a short token; the provider's description is never kept):
+
+| `code` | When |
+| --- | --- |
+| `token_exchange_refused` | The provider refused the login: an OAuth error in the callback, for the code at the token endpoint (`invalid_grant` for a used or expired code), or for its token at UserInfo. |
+| `login_mismatch` | The callback or its ID token is not this login's: another `state`, or an ID token claim that does not match it (the nonce, and likewise the issuer, the audience or the authorized party). |
+| `invalid_response` | The provider answered outside its contract: an ID token whose signature does not verify against the JWKS or that has expired, no subject, another subject at UserInfo, a body that is no OAuth answer. |
+| `provider_unreachable` | The provider could not be asked: no answer in time, a transport failure, a 5xx, or no discovery yet. |
+| `refresh_refused` | The refresh grant answered `invalid_grant`: the refresh family is revoked, expired or was reused. |
+
+`OidcCompletionError` (with its `stage`), `OidcRefreshRefusedError` and
+`OidcAuthorityUnavailableError` (with its `reason`) are `OidcProviderError`s. A
+failed login callback throws `LoginCallbackError`, whose `cause` is the
+provider's failure when the provider half failed:
+
+```ts
+import { LoginCallbackError, OidcProviderError } from '@idp.global/sdk/relyingparty';
+
+try {
+  await sessions.completeLogin(callbackUrl, cookieHeader);
+} catch (error) {
+  const failure = error instanceof LoginCallbackError ? error.cause : error;
+  if (failure instanceof OidcProviderError) {
+    // `failure.code` and `failure.oauthError` are tokens a log line may carry
+    log({ event: 'login_failed', code: failure.code, oauthError: failure.oauthError });
+    const retryLater = failure.code === 'provider_unreachable' || failure.code === 'invalid_response';
+    // …
+  }
+}
+```
 
 **Building before the database connects.** `db` may be a function that answers
 the database once it exists. It is called on every use of a model, the way
@@ -751,10 +827,11 @@ a deadline of its own; bound a slow audit store inside it.
 
 **Issuers under a private CA.** `IdpOidcProvider` takes `trustedCaPem` — one
 PEM string or several, e.g. `@idp.global/devidp`'s `caCertificatePem` or a LAN
-deployment's root. Discovery, token, UserInfo, refresh, revocation and
-introspection then go through one `node:https` agent of this provider that
-trusts those CAs and nothing else; the global `fetch`, its dispatcher and
-`NODE_EXTRA_CA_CERTS` are not involved, and the issuer must still be `https:`.
+deployment's root. Discovery, token, UserInfo, refresh, revocation,
+introspection and the JWKS the ID tokens are verified with then go through one
+`node:https` agent of this provider that trusts those CAs and nothing else; the
+global `fetch`, its dispatcher and `NODE_EXTRA_CA_CERTS` are not involved, and
+the issuer must still be `https:`.
 An unreadable PEM is refused by the constructor.
 
 ```ts
@@ -819,6 +896,7 @@ const sessions = new RelyingPartySessions({
       popup: ['https://workspace.example'],
     },
     accessTokenMaxAgeSeconds: 900, // the default
+    refreshReuseGraceSeconds: 60, // the default; 0 turns it off, at most 300
   },
 });
 ```
@@ -877,9 +955,26 @@ Tokens and their ends:
   extends it.
 - A refresh spends its refresh token and answers a new pair; the old access
   token stops working at once. A spent refresh token that comes back ends the
-  whole session (`refresh_token_reused`), so a client serializes its refreshes,
-  and a client that lost a refresh answer signs in again. A refused refresh
-  answers 400 `invalid_bearer_grant`.
+  whole session (`refresh_token_reused`), so a client serializes its refreshes.
+  A refused refresh answers 400 `invalid_bearer_grant`.
+- A refresh answer that never reached the client (a reload, a closed tab, a
+  dropped connection) is the one exception. Within `refreshReuseGraceSeconds`
+  of the rotation (60 by default, 0 turns it off, at most 300; the
+  constructor refuses anything else), a spent refresh token whose successor
+  was never presented revokes that successor and answers a new pair, reported
+  as a `bearer_refresh_reissued` event. Presented means its access token
+  authenticated a request (`bearer/session`, `resolveBearerSession`,
+  `resolveBearerAccessToken`) or its refresh token was sent to `bearer/refresh`.
+  Only hashes are stored, so the lost pair is replaced, never repeated, and
+  that pair coming back later is reuse. Once the successor was presented, after
+  the window (counted from the rotation, however often the retry's answer is
+  lost too), and for the second of two retries at once, the spent token is
+  reuse and ends the session as before. `bearer/logout` judges a spent refresh
+  token the same way: a sign-out after a lost answer, within the window, ends
+  the session as a `logout`, not as reuse. A stolen spent token works within the
+  same window while the client has not used its new pair yet: the client's
+  access token then stops working, and its next refresh ends the session.
+  Choose the window by that trade-off.
 - The first claim consumes the code, whatever its verifier. A wrong verifier
   ends the session (`handoff_verifier_mismatch`), a claimed code that comes
   back ends it too (`handoff_code_reused`, RFC 6749 §4.1.2), and a code that
@@ -916,9 +1011,10 @@ The client side:
 - Every client claims a code once and never retries a claim or a refresh. Its
   refreshes run one at a time across everything that shares the pair, and a
   rotated pair is stored, all of it at once, before its access token is first
-  used: a pair that is lost after the relying party rotated it cannot be
-  recovered, and its spent refresh token coming back ends the session. Native
-  clients implement this side themselves.
+  used. A pair that is lost after the relying party rotated it is recovered
+  only by the next refresh with the stored pair within the grace window; after
+  it, the spent refresh token coming back ends the session. Native clients
+  implement this side themselves.
 
 The HTTP answers are exported as types (`IRelyingPartyBearerTokenAnswer`,
 `IRelyingPartyBearerSessionAnswer`, `IRelyingPartyBearerLogoutAnswer`,
@@ -1006,8 +1102,9 @@ await client.logout();
   time. Inside the lock the pair is read from the storage again. A pair another
   tab rotated is used as it is, so concurrent refreshes make one request. A
   rotated pair is stored before the lock is released and before its access
-  token is answered; when `storage.set` fails, the new pair is never used and
-  the session is lost.
+  token is answered; when `storage.set` fails, the new pair is never used, and
+  the session goes on only if the next refresh comes within the relying
+  party's grace window.
 - `requestTimeoutMs` (30 seconds by default, more than 0 and at most two
   minutes; any other value throws) is the deadline of each operation: the
   claim of a login's code, a refresh with the write of its pair, the store of a
@@ -1017,9 +1114,10 @@ await client.logout();
   tabs and the call fails with `request_failed`; a login whose pair is stored
   by then stands, with `previous_session_not_revoked`. A claim or refresh the
   relying party carried out before the deadline is lost with its answer. A
-  timed-out claim fails the login, and the user signs in again; after a lost
-  refresh, the next refresh ends the session (`refresh_token_reused`) and the
-  user signs in again. Strict rotation costs that.
+  timed-out claim fails the login, and the user signs in again. After a lost
+  refresh, the next refresh with the stored pair gets a new one when it runs
+  within the relying party's `refreshReuseGraceSeconds`; later it ends the
+  session (`refresh_token_reused`) and the user signs in again.
 - `storage.set(tokens, { signal })` and `storage.clear({ signal })` either
   honour the signal, so a write it aborted is not made and the call rejects,
   or complete synchronously, as an adapter over `localStorage` does. The lock
@@ -1127,8 +1225,9 @@ const result = await client.claimCode(pkce, await pollForCode());
 **Bearer-only mode.** An application whose every client is a bearer client turns
 the cookie login off with `cookieSessions: false`. No route then reads or sets a
 cookie, and that includes the intent cookie a cookie-mode callback clears. It
-takes no `csrfKey`, and it refuses `csrfKey`, `csrfLabel` and `cookieNames`,
-because nothing would use them; `bearer` and `provider` are required.
+takes no `csrfKey`, and it refuses `csrfKey`, `csrfLabel`, `cookieNames` and
+`cookiePolicy`, because nothing would use them; `bearer` and `provider` are
+required.
 
 ```ts
 const sessions = new RelyingPartySessions({
@@ -1229,20 +1328,21 @@ const delivery = await readBearerDelivery(await fetch(callback, { redirect: 'man
 
 | API | Description |
 | --- | --- |
-| `IdpOidcProvider` | Discovery, PKCE authorization URL, code exchange with UserInfo, refresh, revocation and organization introspection for idp.global. Implements `IOidcProvider`. `trustedCaPem` or `fetch` for an issuer under a private CA. |
+| `IdpOidcProvider` | Discovery, PKCE authorization URL, code exchange with UserInfo, refresh, revocation and organization introspection for idp.global. Implements `IOidcProvider`. Verifies the signature of every ID token against the issuer's JWKS. `trustedCaPem` or `fetch` for an issuer under a private CA. |
 | `createRelyingPartyModels()` | Binds the session, login-attempt, bearer hand-off and bearer token models to one `SmartdataDb`, or to a function asked for it on every use, optionally under existing collection names. |
 | `RelyingPartySessions<TPrincipal>` | Login start (with an application intent and a prompt)/complete/abandon/finalize, `openSession` (with a shorter lifetime), `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `eraseSessionsOfPrincipal` (deleting an account), `sessionsOfPrincipal` (paged), `liveProviderToken` (with `rejectedAccessToken`). Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. With `bearer`: `startBearerLogin`, `bearerDeliveryOf`, `completeBearerLogin`, `abandonBearerLogin`, `openBearerHandoff` (pairing a device from a live provider login), `claimBearerHandoff`, `refreshBearerTokens`, `resolveBearerAccessToken`, `resolveBearerSession`, `endBearerSession`; `cookieSessions: false` (`IRelyingPartyBearerOnlySessionsOptions`) runs bearer hand-off alone, without cookies or a CSRF key. |
 | `AuthorityObserver`, `AUTHORITY_FORCED_REFRESH_INTERVAL_MS` | Live organization authority with opt-in positive and negative reuse. An inactive answer rotates the session's token, at most once per interval, before it refuses. |
 | `RelyingPartyRoutes` | `handle(ctx)` for `/auth/login`, `/auth/callback`, `/auth/finalize`, `/auth/session` and `/auth/logout`; `null` for anything else. Takes a typedserver route context. `onLogout` is awaited after a CSRF-checked logout ended the session. In bearer mode also `/auth/bearer/login`, `/auth/bearer/claim`, `/auth/bearer/refresh`, `/auth/bearer/session` and `/auth/bearer/logout`, with CORS for the popup origins only; in bearer-only mode `/auth/login`, `/auth/finalize`, `/auth/session` and `/auth/logout` answer `null`. |
 | `createActorScope()` | AsyncLocalStorage actor context with a TypedRouter request scope. |
 | `RelyingPartySocketBinding` | TypedSocket browser registration, per-request re-validation and session tags; takes a connection wrapper or its peer. |
-| `SecretBox`, `deriveCsrfToken()`, `decodeSecretKey()`, `parseCookies()`, `serializeCookie()`, `sanitizeReturnPath()` | The primitives underneath. |
+| `SecretBox`, `deriveCsrfToken()`, `decodeSecretKey()`, `parseCookies()`, `serializeCookie()` (with `partitioned`, which needs `secure`), `sanitizeReturnPath()` | The primitives underneath. |
 | `pkceChallengeOf()`, `verifyPkceChallenge()`, `parseBearerAuthorization()`, `isBearerReturnTargetAllowed()`, `RELYING_PARTY_BEARER_MESSAGE_TYPE`, `BEARER_HANDOFF_MAX_AGE_SECONDS` | The bearer primitives: S256, the `Authorization` header, the return-target match and the popup message type. |
 | `IRelyingPartyBearerTokenAnswer`, `IRelyingPartyBearerSessionAnswer`, `IRelyingPartyBearerLogoutAnswer`, `IRelyingPartyBearerErrorAnswer`, `TRelyingPartyBearerErrorCode`, `IRelyingPartyBearerMessage` | The HTTP answers of the bearer routes and the popup message, shared with `@idp.global/sdk/browser`. |
 | `IRelyingPartyBearerLoginQuery`, `IRelyingPartyBearerClaimRequest`, `IRelyingPartyBearerRefreshRequest`, `IRelyingPartyBearerLogoutRequest` | The requests of the bearer routes: the `bearer/login` query and the JSON bodies, shared with `@idp.global/sdk/browser`. |
 | `IRelyingPartyBearerHandoffOpening` | What `openBearerHandoff` answers: the paired session, its code and when the code expires. |
 | `IRelyingPartySessionsErasure` | What `eraseSessionsOfPrincipal` answers: how many sessions it ended, and how many sessions, login attempts, bearer hand-offs and token generations it deleted. |
 | `RelyingPartyError`, `RelyingPartyRefusal`, `LoginCallbackError`, `AuthorityTokenError`, `AuthorityRefusedError`, `RelyingPartyDatabaseUnavailableError` | Errors with stable codes; none carries token material. A `RelyingPartyRefusal` may name the application's `location` for the browser. |
+| `OidcProviderError`, `TOidcProviderErrorCode`, `OIDC_PROVIDER_ERROR_CODES`; `OidcCompletionError`, `OidcRefreshRefusedError`, `OidcAuthorityUnavailableError` | The provider's failures with the sdk's own `code` and the provider's `oauthError`, so no application classifies openid-client errors itself. |
 | `RelyingPartyProviderDouble` (`/relyingparty/testing`) | An in-process idp.global for an application's tests: personas, live organization roles, single-use codes, rotating and reuse-detecting refresh tokens, recorded calls and injectable failures. `createBearerPkcePair()` and `readBearerDelivery()` for bearer clients. |
 
 ## Runtime Notes

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@idp.global/sdk',
-  version: '19.5.0',
+  version: '19.6.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }

package/ts_relyingparty/classes.idpoidcprovider.ts

@@ -70,24 +70,163 @@ export interface IOidcRefreshedTokens {
   accessTokenExpiresAt: number;
 }
 
+/**
+ * What failed when the provider was asked, as an application tells the cases
+ * apart; never why access was refused, which only an authority answer says.
+ */
+export type TOidcProviderErrorCode =
+  /**
+   * The provider refused the login: an OAuth error in the callback, for the
+   * code at the token endpoint, or for its token at UserInfo. `oauthError`
+   * names it, such as `invalid_grant` for a code that was used or expired.
+   */
+  | 'token_exchange_refused'
+  /**
+   * The callback or its ID token is not this login's: a `state` that is not
+   * the login's, or an ID token claim that does not match it (the nonce, and
+   * likewise the issuer, the audience or the authorized party).
+   */
+  | 'login_mismatch'
+  /**
+   * The provider answered outside its contract: an ID token whose signature
+   * does not verify against the JWKS or that has expired, no subject, another
+   * subject at UserInfo, or a body that is no OAuth answer.
+   */
+  | 'invalid_response'
+  /** The provider could not be asked: no answer in time, a transport failure, a 5xx, or no discovery yet. */
+  | 'provider_unreachable'
+  /** The refresh grant answered `invalid_grant`: the refresh family is revoked, expired or was reused. */
+  | 'refresh_refused';
+
+export const OIDC_PROVIDER_ERROR_CODES: readonly TOidcProviderErrorCode[] = [
+  'token_exchange_refused',
+  'login_mismatch',
+  'invalid_response',
+  'provider_unreachable',
+  'refresh_refused',
+];
+
+/** An OAuth error code is a short token; anything else a provider sends there is dropped, never kept. */
+const OAUTH_ERROR_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+
+const oauthErrorOf = (valueArg: unknown): string | undefined =>
+  typeof valueArg === 'string' && OAUTH_ERROR_PATTERN.test(valueArg) ? valueArg : undefined;
+
+/** The OAuth error and HTTP status of an openid-client failure that is the provider's own answer; `null` for any other failure. */
+const providerAnswerOf = (errorArg: unknown): { oauthError?: string; status?: number } | null => {
+  const openidClient = plugins.openidClient;
+  if (errorArg instanceof openidClient.ResponseBodyError) {
+    return { oauthError: oauthErrorOf(errorArg.error), status: errorArg.status };
+  }
+  if (errorArg instanceof openidClient.AuthorizationResponseError) {
+    return { oauthError: oauthErrorOf(errorArg.error) };
+  }
+  if (errorArg instanceof openidClient.WWWAuthenticateChallengeError) {
+    return { oauthError: oauthErrorOf(errorArg.cause[0]?.parameters.error), status: errorArg.status };
+  }
+  return null;
+};
+
+/** openid-client's codes (`ClientError.code`) for a provider that did not answer in time or within HTTP's own contract. */
+const UNREACHABLE_CLIENT_ERROR_CODES: readonly string[] = ['OAUTH_TIMEOUT', 'OAUTH_ABORT', 'OAUTH_RESPONSE_IS_NOT_CONFORM'];
+/** openid-client's code for a JWT claim that is not the expected one: the nonce, the issuer, the audience or the authorized party. */
+const JWT_CLAIM_COMPARISON_CODE = 'OAUTH_JWT_CLAIM_COMPARISON_FAILED';
+
+/**
+ * The class of an openid-client failure of the code exchange or of UserInfo.
+ * The provider's own OAuth error answer is a refusal, or unreachable on a 5xx;
+ * a claim that does not match is not this login's; every other failure of
+ * openid-client's checks is an invalid response; and anything else (a
+ * transport failure is fetch's `TypeError`) is an unreachable provider.
+ */
+const classifyCompletionFailure = (errorArg: unknown): { code: TOidcProviderErrorCode; oauthError?: string } => {
+  if (errorArg instanceof OidcProviderError) {
+    return { code: errorArg.code, oauthError: errorArg.oauthError };
+  }
+  const answer = providerAnswerOf(errorArg);
+  if (answer) {
+    const code: TOidcProviderErrorCode = answer.status !== undefined && answer.status >= 500
+      ? 'provider_unreachable'
+      : 'token_exchange_refused';
+    return { code, oauthError: answer.oauthError };
+  }
+  if (errorArg instanceof plugins.openidClient.ClientError) {
+    if (errorArg.code === JWT_CLAIM_COMPARISON_CODE) {
+      return { code: 'login_mismatch' };
+    }
+    return { code: errorArg.code !== undefined && UNREACHABLE_CLIENT_ERROR_CODES.includes(errorArg.code) ? 'provider_unreachable' : 'invalid_response' };
+  }
+  return { code: 'provider_unreachable' };
+};
+
+/** Why a refresh could not be made: openid-client's checks failed on the answer, or the provider could not be asked. */
+const refreshFailureReasonOf = (errorArg: unknown): TOidcAuthorityFailure =>
+  errorArg instanceof plugins.openidClient.ClientError
+    && !(errorArg.code !== undefined && UNREACHABLE_CLIENT_ERROR_CODES.includes(errorArg.code))
+    ? 'invalid_response'
+    : 'unavailable';
+
+/**
+ * Every failure of the provider this module throws: its `code` says which
+ * case it is, `oauthError` the provider's own OAuth error code where it sent
+ * one (a short token, never its description). An application classifies a
+ * failure by these and never by openid-client's classes; `cause` keeps the
+ * original for a debugger, not for a log line.
+ */
+export class OidcProviderError extends Error {
+  public readonly code: TOidcProviderErrorCode;
+  public readonly oauthError?: string;
+
+  constructor(
+    messageArg: string,
+    detailArg: { code: TOidcProviderErrorCode; oauthError?: string },
+    causeArg?: unknown,
+  ) {
+    super(messageArg, { cause: causeArg });
+    this.name = 'OidcProviderError';
+    if (!OIDC_PROVIDER_ERROR_CODES.includes(detailArg?.code)) {
+      throw new TypeError('OidcProviderError needs one of OIDC_PROVIDER_ERROR_CODES');
+    }
+    this.code = detailArg.code;
+    const oauthError = oauthErrorOf(detailArg.oauthError);
+    if (oauthError !== undefined) {
+      this.oauthError = oauthError;
+    }
+  }
+}
+
 /** Why an observation or a refresh could not be made; never why access was refused. */
 export type TOidcAuthorityFailure = 'unavailable' | 'invalid_response';
 
-/** The provider could not be asked, or did not answer in its own contract. The caller fails closed on it. */
-export class OidcAuthorityUnavailableError extends Error {
+/**
+ * The provider could not be asked, or did not answer in its own contract. The
+ * caller fails closed on it. `code` is `provider_unreachable` or
+ * `invalid_response`, after `reason`.
+ */
+export class OidcAuthorityUnavailableError extends OidcProviderError {
   constructor(
     public readonly reason: TOidcAuthorityFailure,
     causeArg?: unknown,
   ) {
-    super('The identity provider could not be observed', { cause: causeArg });
+    super(
+      'The identity provider could not be observed',
+      {
+        code: reason === 'invalid_response' ? 'invalid_response' : 'provider_unreachable',
+        oauthError: providerAnswerOf(causeArg)?.oauthError,
+      },
+      causeArg,
+    );
     this.name = 'OidcAuthorityUnavailableError';
   }
 }
 
-/** The provider refused the refresh with `invalid_grant`: the refresh family is revoked, expired or was reused. */
-export class OidcRefreshRefusedError extends Error {
+/**
+ * The provider refused the refresh with `invalid_grant`: the refresh family is
+ * revoked, expired or was reused. `code` is `refresh_refused`.
+ */
+export class OidcRefreshRefusedError extends OidcProviderError {
   constructor(causeArg?: unknown) {
-    super('The identity provider refused the refresh', { cause: causeArg });
+    super('The identity provider refused the refresh', { code: 'refresh_refused', oauthError: 'invalid_grant' }, causeArg);
     this.name = 'OidcRefreshRefusedError';
   }
 }
@@ -96,12 +235,18 @@ export type TOidcTokenHint = 'access_token' | 'refresh_token';
 
 export type TOidcCompletionFailureStage = 'token_exchange' | 'token_validation' | 'userinfo';
 
-export class OidcCompletionError extends Error {
+/**
+ * A login the provider half could not complete. `stage` says where it
+ * stopped, `code` what it was; without a `detailArg` the code is read from
+ * the cause, an openid-client failure.
+ */
+export class OidcCompletionError extends OidcProviderError {
   constructor(
     public readonly stage: TOidcCompletionFailureStage,
     causeArg: unknown,
+    detailArg?: { code: TOidcProviderErrorCode; oauthError?: string },
   ) {
-    super('OIDC completion failed', { cause: causeArg });
+    super('OIDC completion failed', detailArg ?? classifyCompletionFailure(causeArg), causeArg);
     this.name = 'OidcCompletionError';
   }
 }
@@ -151,7 +296,7 @@ export interface IIdpOidcProviderOptions {
   /** the registered callback, on the application's public origin */
   redirectUri: URL;
   scopes?: string;
-  /** deadline of discovery, token, UserInfo, refresh and revocation requests */
+  /** deadline of discovery, token, JWKS, UserInfo, refresh and revocation requests */
   requestTimeoutSeconds?: number;
   /** deadline of one introspection; the introspection client's default applies when absent */
   introspectionTimeoutMs?: number;
@@ -165,7 +310,7 @@ export interface IIdpOidcProviderOptions {
   trustedCaPem?: string | readonly string[];
   /**
    * Advanced: the fetch that carries every request of this provider —
-   * discovery, token, UserInfo, refresh, revocation and introspection.
+   * discovery, token, JWKS, UserInfo, refresh, revocation and introspection.
    * It owns the transport's trust decisions; https-only still holds. Not
    * combined with `trustedCaPem`.
    */
@@ -213,9 +358,9 @@ export const readOrganizationClaims = (valueArg: unknown): IOidcOrganizationClai
 /**
  * The relying-party side of the authorization code flow with S256 PKCE on
  * `openid-client`, in the profile idp.global supports: code responses, S256
- * challenges, RS256 ID tokens and `client_secret_basic` for a confidential
- * client. Live organization authority is observed with the sdk's
- * `OidcIntrospectionClient`.
+ * challenges, RS256 ID tokens whose signature is verified against the
+ * issuer's JWKS, and `client_secret_basic` for a confidential client. Live
+ * organization authority is observed with the sdk's `OidcIntrospectionClient`.
  */
 export class IdpOidcProvider implements IOidcProvider {
   public readonly requestTimeoutSeconds: number;
@@ -262,7 +407,11 @@ export class IdpOidcProvider implements IOidcProvider {
     }
     const options = this.#options;
     // the timeout and the fetch given to discovery apply to discovery itself
-    // and stay on the resolved configuration for every later request
+    // and stay on the resolved configuration for every later request.
+    // `enableNonRepudiationChecks` verifies the signature of every ID token the
+    // code grant and the refresh grant answer against the issuer's JWKS
+    // (`jwks_uri`, fetched through the same fetch), so an ID token is never
+    // accepted on the trust of the TLS connection alone
     const configuration = await plugins.openidClient.discovery(
       options.issuer,
       options.clientId,
@@ -274,6 +423,7 @@ export class IdpOidcProvider implements IOidcProvider {
       plugins.openidClient.ClientSecretBasic(options.clientSecret),
       {
         timeout: this.requestTimeoutSeconds,
+        execute: [plugins.openidClient.enableNonRepudiationChecks],
         ...(this.#fetch ? { [plugins.openidClient.customFetch]: this.#fetch } : {}),
       },
     );
@@ -322,6 +472,15 @@ export class IdpOidcProvider implements IOidcProvider {
   }
 
   public async completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion> {
+    // the one state of the callback is the login's, or nothing is exchanged
+    const states = optionsArg.callbackUrl.searchParams.getAll('state');
+    if (states.length !== 1 || states[0] !== optionsArg.state) {
+      throw new OidcCompletionError(
+        'token_exchange',
+        new Error('The callback state is not the state of this login'),
+        { code: 'login_mismatch' },
+      );
+    }
     let tokens: Awaited<ReturnType<typeof plugins.openidClient.authorizationCodeGrant>>;
     try {
       tokens = await plugins.openidClient.authorizationCodeGrant(this.configuration, optionsArg.callbackUrl, {
@@ -342,7 +501,7 @@ export class IdpOidcProvider implements IOidcProvider {
       }
       subject = claims.sub;
     } catch (error) {
-      throw new OidcCompletionError('token_validation', error);
+      throw new OidcCompletionError('token_validation', error, { code: 'invalid_response' });
     }
 
     // UserInfo is the current view of profile and organization claims; the ID
@@ -354,7 +513,11 @@ export class IdpOidcProvider implements IOidcProvider {
       throw new OidcCompletionError('userinfo', error);
     }
     if (userInfo.sub !== subject) {
-      throw new OidcCompletionError('token_validation', new Error('The UserInfo subject does not match the ID token'));
+      throw new OidcCompletionError(
+        'token_validation',
+        new Error('The UserInfo subject does not match the ID token'),
+        { code: 'invalid_response' },
+      );
     }
 
     return {
@@ -426,7 +589,10 @@ export class IdpOidcProvider implements IOidcProvider {
       if (error instanceof plugins.openidClient.ResponseBodyError && error.error === 'invalid_grant') {
         throw new OidcRefreshRefusedError(error);
       }
-      throw new OidcAuthorityUnavailableError('unavailable', error);
+      // everything else fails closed: another OAuth error (`invalid_client` for a
+      // deactivated app) or a transport failure is unreachable, an answer that
+      // fails openid-client's checks (an ID token that does not verify) is invalid
+      throw new OidcAuthorityUnavailableError(refreshFailureReasonOf(error), error);
     }
     return {
       accessToken: tokens.access_token,