@hyper.authio/client 0.7.0 → 0.8.0

package/README.md

@@ -26,15 +26,22 @@ const authio = createAuthioClient({
 | --- | --- | --- |
 | `issuer`, or `authority` + `realm` | | The realm's issuer. Must be HTTPS, except on loopback or with `requireHttps: false`. |
 | `clientId` | | Required. |
-| `clientAuthentication` | `private_key_jwt` with only a key, else `client_secret_basic` | Also `client_secret_post` and `none` (a public client). |
+| `tokenEndpointAuthMethod` | `client_secret_basic` with a secret, `private_key_jwt` with only a key, `none` with neither | The client's authentication method in Authio, which matches it exactly: `client_secret_basic`, `client_secret_post`, `private_key_jwt` or `none` (a public client). |
 | `clientSecret` | | For `client_secret_basic` / `client_secret_post`. A function returning the secret is called for every request, so a rotated secret is used without a restart. |
 | `clientPrivateKey`, `clientPrivateKeyPath`, `clientKeyId`, `clientSigningAlgorithm` | RS256 for RSA, the curve's ES algorithm for EC | For `private_key_jwt`: PEM (PKCS#8, PKCS#1, SEC1) or JWK; the file is re-read when it changes; RSA keys need 2048 bits. |
 | `clientAssertionLifetime` | 120 s | At most 3600. |
-| `clientEncryptionKey`, `clientEncryptionKeyPath` | | The private half of the client's encryption key (JWK or PEM, or a function returning it; the path is Node only), to read ID tokens, UserInfo and logout tokens Authio encrypts (RSA-OAEP, RSA-OAEP-256). |
+| `checks` | none | What the sign-in checks: `pkce`, `state`, `nonce` (or `none`). Only the listed checks are made. |
+| `codeChallengeMethod` | `S256` | `S256` or `plain`, with the `pkce` check: one of the client's allowed PKCE methods. |
+| `responseMode` | not sent | `query` or `web_message`. |
+| `idTokenSignedResponseAlg` | the asymmetric algorithms the discovery document announces | The client's signing algorithm: RS/PS/ES 256/384/512, or HS256/384/512 verified with `clientSecret` (at least 32, 48 or 64 bytes, RFC 7518 §3.2). Also used for logout tokens. |
+| `accessTokenSignedResponseAlg` | the asymmetric algorithms the discovery document announces | The algorithm of the client's access tokens (Authio's second signing setting), for `readAccessTokenClaims`; HS* with `clientSecret`. |
+| `userinfoSignedResponseAlg` | `idTokenSignedResponseAlg` | For UserInfo answered as a signed JWT. |
+| `clientEncryptionKey`, `clientEncryptionKeyPath` | | The private half of the client's encryption key (JWK or PEM, or a function returning it; the path is Node only), to read ID tokens, UserInfo and logout tokens Authio encrypts. Without it nothing is decrypted. |
+| `encryptionAlgorithms` | `RSA-OAEP`, `RSA-OAEP-256` | The JWE `alg` accepted. RSA1_5 cannot be listed: Node and WebCrypto cannot decrypt it. |
+| `encryptionMethods` | `A128CBC-HS256`, `A192CBC-HS384`, `A256CBC-HS512` | The JWE `enc` accepted; `A128GCM`, `A192GCM` and `A256GCM` may be listed. |
 | `allowLegacyEncryptionAlgorithms` | `false` | Accepted for parity; RSA1_5 stays refused in Node, which cannot decrypt it (`legacy_algorithm`). |
 | `redirectUri`, `postLogoutRedirectUri` | | Defaults for sign-in and sign-out requests. |
 | `clockSkew` | 30 s | Tolerated on ID tokens, logout tokens and signed UserInfo. |
-| `validAlgorithms` | RS*, PS*, ES* | Accepted signing algorithms for those tokens. |
 | `discoveryCacheDuration` | 3600 s | |
 | `httpTimeout` | 30 s | |
 | `tokenRefreshSkew` | 60 s | How early cached tokens are renewed (at most half their lifetime). |
@@ -45,11 +52,30 @@ when it names another issuer.
 
 Option names follow the shared `conformance/options.md`; there are no aliases for older names.
 
+## Mirror the client
+
+The options describe the client as it is registered in Authio's console, and an option left out is off: the library
+hard-codes none of it. Authio refuses a request that does not match the client and accepts what the client does not
+require.
+
+| In the console | Options |
+| --- | --- |
+| PKCE required, method S256 | `checks: ["pkce", "state"]` (add `"nonce"` to bind the ID token), `codeChallengeMethod: "S256"` |
+| PKCE required, method plain only | `checks: ["pkce", "state"]`, `codeChallengeMethod: "plain"` |
+| PKCE off | `checks: ["state"]`, or leave `checks` out to check nothing (sending PKCE anyway is accepted) |
+| Authentication on, `client_secret_post` | `clientSecret`, `tokenEndpointAuthMethod: "client_secret_post"` |
+| Authentication on, `private_key_jwt` | `clientPrivateKey` (or `clientPrivateKeyPath`), `clientKeyId` |
+| Authentication off (public client) | no secret nor key: `tokenEndpointAuthMethod` is `none` |
+| ID token signing algorithm HS256 | `clientSecret`, `idTokenSignedResponseAlg: "HS256"` |
+| Access token signing algorithm HS256 | `clientSecret`, `accessTokenSignedResponseAlg: "HS256"` (an API: the verifier's `accessTokenSignedResponseAlg`) |
+| Tokens encrypted with the client's key, RSA-OAEP-256 | `clientEncryptionKey`, `encryptionAlgorithms: ["RSA-OAEP-256"]` |
+
 ## Sign people in
 
 ```ts
 const authio = createAuthioClient({
-  issuer, clientId: "storefront", clientAuthentication: "none", // or a secret / private key for a confidential client
+  issuer, clientId: "storefront", // a public client: no secret nor key, so tokenEndpointAuthMethod is none
+  checks: ["pkce", "state", "nonce"], codeChallengeMethod: "S256", // the client requires PKCE with S256
   redirectUri: "https://shop.example.com/callback",
 });
 
@@ -62,12 +88,15 @@ const { url, transaction } = await authio.createAuthorizationUrl({
   maxAge: 900, acrValues: "2", loginHint, uiLocales: "pt-BR", idpHint: "google",
 });
 
-// 2. On the callback: state and iss (RFC 9207) are checked, the code is redeemed with the PKCE verifier,
-//    and the ID token validated (nonce, at_hash, auth_time against maxAge).
+// 2. On the callback: state (with the state check) and iss (RFC 9207) are checked, the code is redeemed (with the
+//    PKCE verifier, with the pkce check), and the ID token validated (nonce with the nonce check, at_hash, auth_time
+//    against maxAge).
 const { tokens, idToken } = await authio.handleAuthorizationCallback(request.url, transaction);
 ```
 
-PKCE uses S256 unless `codeChallengeMethod: "plain"` is asked for. `popup: true` sets `display=popup` and
+Each check generates its parameter and is verified on the callback; the transaction lists the checks it was made with,
+and a `state` it did not ask for is ignored. A request may pass its own `checks`, `codeChallengeMethod` and
+`responseMode`. `popup: true` sets `display=popup` and
 `response_mode=web_message`; pass the parameters the popup posted to the opener to `handleAuthorizationCallback`. A
 callback that is not for the transaction throws `AuthioCallbackError` (`reason`: `state_mismatch`, `issuer_mismatch`,
 `missing_issuer`, `missing_code`); an OAuth error Authio sent back (`login_required` after `prompt: "none"`, for one)
@@ -81,13 +110,19 @@ const logoutUrl = await authio.createEndSessionUrl({ idTokenHint, postLogoutRedi
 const logout = await authio.validateLogoutToken(form.logout_token); // { subject, sessionId, tokenId, claims }
 ```
 
-ID tokens are checked against the realm's JWKS (cached, re-read on an unknown `kid`): `iss`, `aud` = the client id,
+ID tokens are checked against the realm's JWKS (cached, re-read on an unknown `kid`), or against `clientSecret` for
+the HS* algorithm `idTokenSignedResponseAlg` names: `iss`, `aud` = the client id,
 `exp` with `clockSkew`, payload `typ` = `ID`, `azp` when there are several audiences, `nonce`, `at_hash` (hash of the
 signing algorithm) and `auth_time` against `maxAge`. An encrypted ID token is decrypted with `clientEncryptionKey`
 first. A back-channel logout token must be typed `logout+jwt`, carry the back-channel event, no `nonce`, and a `sub`
 or `sid`. Every refusal is an `AuthioTokenValidationError` whose `reason` uses the outcome names of
-`conformance/tokens.json` (`invalid_nonce`, `invalid_at_hash`, `invalid_logout_token`, `expired`, …). In Express,
-`authioBackchannelLogout` from `@hyper.authio/express` is the endpoint.
+`conformance/tokens.json` (`invalid_nonce`, `invalid_at_hash`, `invalid_logout_token`, `invalid_algorithm`, `expired`,
+…). In Express, `authioBackchannelLogout` from `@hyper.authio/express` is the endpoint.
+
+`readAccessTokenClaims(accessToken)` returns the payload of an access token the client received once it is decrypted
+and its signature, `iss` and `exp` verify (`undefined` for an opaque token). For front-channel logout, Authio loads the
+client's front-channel logout URI in an iframe; `validateFrontChannelLogout(request.url)` checks `iss` and returns the
+`sessionId` (`sid`) to end (`authioFrontchannelLogout` in `@hyper.authio/express`).
 
 ### Step-up
 
@@ -104,7 +139,7 @@ const { url, transaction } = await authio.createStepUpAuthorizationUrl(challenge
 ```ts
 await authio.tokens.clientCredentials({ scopes: ["orders:read"], resource: "https://orders.example.com" });
 await authio.tokens.authorizationCode({ code, redirectUri, codeVerifier });
-await authio.tokens.refresh({ refreshToken });             // store the rotated refresh_token it returns
+await authio.tokens.refresh({ refreshToken, resource });   // store the rotated refresh_token it returns; resource: RFC 8707
 await authio.tokens.exchange({ subjectToken, resource });  // on-behalf-of (RFC 8693)
 await authio.tokens.password({ username, password });
 await authio.tokens.personalAccessToken({ token: "pat_…", clientId: "billing-api" }); // clientId only for a consumer's PAT

package/dist/index.cjs

@@ -149,6 +149,8 @@ var AuthioAsymmetricAlgorithms = [
   "ES384",
   "ES512"
 ];
+var AuthioHmacAlgorithms = ["HS256", "HS384", "HS512"];
+var AuthioHmacMinimumSecretBytes = Object.freeze({ HS256: 32, HS384: 48, HS512: 64 });
 var AuthioDefaults = {
   DiscoveryPath: "/.well-known/openid-configuration",
   ProtectedResourceMetadataPath: "/.well-known/oauth-protected-resource",
@@ -280,6 +282,12 @@ var systemClock = {
     signal?.addEventListener("abort", onAbort, { once: true });
   })
 };
+var AuthioTokenEndpointAuthMethods = [
+  "client_secret_basic",
+  "client_secret_post",
+  "private_key_jwt",
+  "none"
+];
 function resolveConnection(options) {
   const requireHttps = options.requireHttps ?? true;
   const issuer = resolveIssuer(options);
@@ -595,7 +603,9 @@ function createClientAuthenticator(settings, connection) {
   const clientId = settings.clientId?.trim();
   if (!clientId) throw new AuthioConfigurationError("The Authio clientId is required.");
   const hasKey = settings.clientPrivateKey !== void 0 || !!settings.clientPrivateKeyPath;
-  const method = settings.clientAuthentication ?? (!settings.clientSecret && hasKey ? "private_key_jwt" : "client_secret_basic");
+  const method = settings.tokenEndpointAuthMethod ?? (settings.clientSecret ? "client_secret_basic" : hasKey ? "private_key_jwt" : "none");
+  if (!AuthioTokenEndpointAuthMethods.includes(method))
+    throw new AuthioConfigurationError(`The Authio tokenEndpointAuthMethod '${String(method)}' is not one of ${AuthioTokenEndpointAuthMethods.join(", ")}.`);
   if ((method === "client_secret_basic" || method === "client_secret_post") && !settings.clientSecret)
     throw new AuthioConfigurationError(`The Authio clientSecret is required with ${method}.`);
   if (method === "private_key_jwt" && !hasKey)
@@ -677,6 +687,7 @@ function createKeyLoader(settings) {
 var AuthioKeyManagementAlgorithms = ["RSA-OAEP", "RSA-OAEP-256"];
 var AuthioLegacyKeyManagementAlgorithms = ["RSA1_5"];
 var AuthioContentEncryptionAlgorithms = ["A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"];
+var AuthioSupportedContentEncryptionAlgorithms = [...AuthioContentEncryptionAlgorithms, "A128GCM", "A192GCM", "A256GCM"];
 var rsaAlgorithmIdentifier = [48, 13, 6, 9, 42, 134, 72, 134, 247, 13, 1, 1, 1, 5, 0];
 function isAuthioTokenEncrypted(token) {
   return typeof token === "string" && token.split(".").length === 5;
@@ -684,6 +695,13 @@ function isAuthioTokenEncrypted(token) {
 function createAuthioTokenDecrypter(key, options = {}) {
   const settings = typeof options === "string" ? { setting: options } : options;
   const setting = settings.setting ?? "clientEncryptionKey";
+  const keyManagementAlgorithms = resolveAllowlist(settings.encryptionAlgorithms, AuthioKeyManagementAlgorithms, AuthioKeyManagementAlgorithms, "encryptionAlgorithms");
+  const contentEncryptionAlgorithms = resolveAllowlist(
+    settings.encryptionMethods,
+    AuthioContentEncryptionAlgorithms,
+    AuthioSupportedContentEncryptionAlgorithms,
+    "encryptionMethods"
+  );
   const imported = /* @__PURE__ */ new Map();
   const importFor = (algorithm) => {
     let pending = imported.get(algorithm);
@@ -702,10 +720,16 @@ function createAuthioTokenDecrypter(key, options = {}) {
         "legacy_algorithm",
         settings.allowLegacyEncryptionAlgorithms ? "The token is encrypted with RSA1_5 (PKCS#1 v1.5), which Node and WebCrypto cannot decrypt even with allowLegacyEncryptionAlgorithms; register RSA-OAEP-256 as the client's encryption algorithm in Authio." : "The token is encrypted with the legacy RSA1_5 algorithm, which is refused; register RSA-OAEP-256 as the client's encryption algorithm in Authio."
       );
-    if (!AuthioKeyManagementAlgorithms.includes(algorithm))
+    if (!keyManagementAlgorithms.includes(algorithm))
+      throw new AuthioTokenValidationError(
+        "decryption_failed",
+        `The token is encrypted with '${algorithm}', and encryptionAlgorithms accepts ${keyManagementAlgorithms.join(" or ")}.`
+      );
+    const method = contentMethodOf(token);
+    if (!contentEncryptionAlgorithms.includes(method))
       throw new AuthioTokenValidationError(
         "decryption_failed",
-        `The token is encrypted with '${algorithm}'; Authio encrypts with ${AuthioKeyManagementAlgorithms.join(" or ")}.`
+        `The token's content is encrypted with '${method}', and encryptionMethods accepts ${contentEncryptionAlgorithms.join(" or ")}.`
       );
     if (key === void 0 || key === null || key === "")
       throw new AuthioTokenValidationError(
@@ -714,8 +738,8 @@ function createAuthioTokenDecrypter(key, options = {}) {
       );
     try {
       const { plaintext } = await jose.compactDecrypt(token, (header) => importFor(header.alg), {
-        keyManagementAlgorithms: [...AuthioKeyManagementAlgorithms],
-        contentEncryptionAlgorithms: [...AuthioContentEncryptionAlgorithms]
+        keyManagementAlgorithms: [...keyManagementAlgorithms],
+        contentEncryptionAlgorithms: [...contentEncryptionAlgorithms]
       });
       return new TextDecoder().decode(plaintext);
     } catch (error) {
@@ -749,6 +773,24 @@ function algorithmOf(token) {
     throw new AuthioTokenValidationError("decryption_failed", "The encrypted token's header could not be read.", { cause: error });
   }
 }
+function contentMethodOf(token) {
+  try {
+    return String(jose.decodeProtectedHeader(token).enc ?? "");
+  } catch (error) {
+    throw new AuthioTokenValidationError("decryption_failed", "The encrypted token's header could not be read.", { cause: error });
+  }
+}
+function resolveAllowlist(configured, defaults, supported, setting) {
+  if (configured === void 0 || configured.length === 0) return defaults;
+  for (const value of configured) {
+    if (AuthioLegacyKeyManagementAlgorithms.includes(value))
+      throw new AuthioConfigurationError(
+        `${setting} cannot hold ${value}: Node and WebCrypto cannot decrypt PKCS#1 v1.5; register RSA-OAEP-256 as the client's encryption algorithm in Authio.`
+      );
+    if (!supported.includes(value)) throw new AuthioConfigurationError(`${setting} holds '${value}'; it accepts ${supported.join(", ")}.`);
+  }
+  return [...new Set(configured)];
+}
 async function importDecryptionKey(key, algorithm, setting) {
   try {
     if (typeof key !== "string") return await importPrivateJwk(key, algorithm, setting);
@@ -805,7 +847,7 @@ async function verifyAuthioJwt(token, keys, expected) {
   try {
     const { payload, protectedHeader } = await jose.jwtVerify(token, keys, {
       issuer: expected.issuer,
-      audience: [...expected.audiences],
+      audience: expected.audiences ? [...expected.audiences] : void 0,
       algorithms: [...expected.algorithms && expected.algorithms.length > 0 ? expected.algorithms : AuthioAsymmetricAlgorithms],
       clockTolerance: expected.clockSkew ?? AuthioDefaults.ClockSkew,
       requiredClaims: [.../* @__PURE__ */ new Set(["exp", ...expected.requiredClaims ?? []])],
@@ -813,9 +855,34 @@ async function verifyAuthioJwt(token, keys, expected) {
     });
     return { payload, header: protectedHeader };
   } catch (error) {
-    throw toTokenValidationError(error, expected.audiences, token);
+    if (error instanceof AuthioConfigurationError) throw error;
+    throw toTokenValidationError(error, expected.audiences ?? [], token);
   }
 }
+function withClientSecret(keys, secret) {
+  if (!secret) return keys;
+  return async (header, token) => {
+    const algorithm = String(header.alg);
+    if (!AuthioHmacAlgorithms.includes(algorithm)) return keys(header, token);
+    const bytes = new TextEncoder().encode(await secret());
+    requireHmacSecretLength(algorithm, bytes.length);
+    return bytes;
+  };
+}
+function requireHmacSecretLength(algorithm, length) {
+  const minimum = AuthioHmacMinimumSecretBytes[algorithm];
+  if (minimum !== void 0 && length < minimum)
+    throw new AuthioConfigurationError(
+      `The Authio clientSecret has ${length} bytes, and ${algorithm} needs at least ${minimum} (RFC 7518 \xA73.2): Authio refuses a shorter secret for it.`
+    );
+}
+function acceptedSigningAlgorithms(configured, announced) {
+  if (configured) return [configured];
+  const asymmetric = (Array.isArray(announced) ? announced : []).filter(
+    (algorithm) => typeof algorithm === "string" && AuthioAsymmetricAlgorithms.includes(algorithm)
+  );
+  return asymmetric.length > 0 ? asymmetric : AuthioAsymmetricAlgorithms;
+}
 function toTokenValidationError(error, audiences, token) {
   if (error instanceof AuthioTokenValidationError) return error;
   const refuse = (reason, message) => new AuthioTokenValidationError(reason, message, { cause: error });
@@ -947,6 +1014,7 @@ function toBase64Url(bytes) {
 }
 
 // src/authorization.ts
+var AuthioChecks = ["pkce", "state", "nonce", "none"];
 async function createAuthioPkce(method = "S256") {
   if (method !== "S256" && method !== "plain") throw new TypeError(`The PKCE method '${String(method)}' is not S256 or plain.`);
   const codeVerifier = randomValue(32);
@@ -956,14 +1024,26 @@ async function createAuthioPkce(method = "S256") {
 function randomValue(bytes = 32) {
   return toBase64Url2(crypto.getRandomValues(new Uint8Array(bytes)));
 }
+function resolveChecks(checks, setting = "checks") {
+  const resolved = [];
+  for (const check of checks ?? []) {
+    if (!AuthioChecks.includes(check))
+      throw new AuthioConfigurationError(`The Authio ${setting} value '${String(check)}' is not one of ${AuthioChecks.join(", ")}.`);
+    if (check !== "none" && !resolved.includes(check)) resolved.push(check);
+  }
+  return Object.freeze(resolved);
+}
 async function buildAuthorizationUrl(endpoint, clientId, request) {
-  const pkce = await createAuthioPkce(request.codeChallengeMethod ?? "S256");
-  const state = request.state?.trim() || randomValue();
-  const nonce = request.nonce?.trim() || randomValue();
+  const checks = resolveChecks(request.checks);
+  const pkce = checks.includes("pkce") ? await createAuthioPkce(request.codeChallengeMethod ?? "S256") : void 0;
+  const state = checks.includes("state") ? request.state?.trim() || randomValue() : void 0;
+  const nonce = checks.includes("nonce") ? request.nonce?.trim() || randomValue() : void 0;
   if (request.maxAge !== void 0 && (!Number.isInteger(request.maxAge) || request.maxAge < 0))
     throw new RangeError("maxAge must be a non-negative whole number of seconds.");
   const display = request.popup ? "popup" : request.display;
   const responseMode = request.popup ? "web_message" : request.responseMode;
+  if (responseMode !== void 0 && responseMode !== "query" && responseMode !== "web_message")
+    throw new AuthioConfigurationError(`The Authio responseMode '${String(responseMode)}' is not query or web_message.`);
   const url = new URL(endpoint);
   const parameters = {
     ...request.extraParameters,
@@ -971,10 +1051,10 @@ async function buildAuthorizationUrl(endpoint, clientId, request) {
     client_id: clientId,
     redirect_uri: request.redirectUri,
     scope: toScopeString(request.scopes) ?? "openid",
-    state,
-    nonce,
-    code_challenge: pkce.codeChallenge,
-    code_challenge_method: pkce.codeChallengeMethod,
+    state: state ?? request.state?.trim(),
+    nonce: nonce ?? request.nonce?.trim(),
+    code_challenge: pkce?.codeChallenge,
+    code_challenge_method: pkce?.codeChallengeMethod,
     resource: request.resource,
     organization: request.organization,
     prompt: joined(request.prompt),
@@ -991,10 +1071,10 @@ async function buildAuthorizationUrl(endpoint, clientId, request) {
   return {
     url: url.toString(),
     transaction: Object.freeze({
-      state,
-      nonce,
-      codeVerifier: pkce.codeVerifier,
-      codeChallengeMethod: pkce.codeChallengeMethod,
+      checks,
+      ...state ? { state } : {},
+      ...nonce ? { nonce } : {},
+      ...pkce ? { codeVerifier: pkce.codeVerifier, codeChallengeMethod: pkce.codeChallengeMethod } : {},
       redirectUri: request.redirectUri,
       ...request.resource ? { resource: request.resource } : {},
       ...request.maxAge !== void 0 ? { maxAge: request.maxAge } : {}
@@ -1016,6 +1096,16 @@ function readCallbackParameters(callback) {
   }
   return parameters;
 }
+function readAuthioFrontChannelLogout(request, issuer) {
+  const parameters = readCallbackParameters(request);
+  const sessionId = parameters.sid?.trim() || void 0;
+  const sentIssuer = parameters.iss?.trim() || void 0;
+  if (sentIssuer !== void 0 && sentIssuer.replace(/\/+$/, "") !== issuer.replace(/\/+$/, ""))
+    throw new AuthioCallbackError("issuer_mismatch", `The front-channel logout comes from the issuer '${sentIssuer}', not '${issuer}'.`);
+  if (sessionId !== void 0 && sentIssuer === void 0)
+    throw new AuthioCallbackError("missing_issuer", "The front-channel logout names a sid without its iss.");
+  return Object.freeze({ sessionId, issuer: sentIssuer });
+}
 function parseAuthioBearerChallenge(header) {
   if (!header || !/^\s*bearer(\s|$)/i.test(header)) return void 0;
   const values = {};
@@ -1051,22 +1141,35 @@ function createAuthioClient(options) {
   const authenticator = createClientAuthenticator(options, connection);
   const refreshSkewMs = seconds(options.tokenRefreshSkew, AuthioDefaults.TokenRefreshSkew, "tokenRefreshSkew");
   const clockSkew = seconds(options.clockSkew, AuthioDefaults.ClockSkew, "clockSkew") / 1e3;
-  const decrypt = createAuthioTokenDecrypter(resolveEncryptionKey(options), {
+  const encryptionKey = resolveEncryptionKey(options);
+  const decrypt = createAuthioTokenDecrypter(encryptionKey, {
     setting: options.clientEncryptionKey === void 0 && options.clientEncryptionKeyPath ? "clientEncryptionKeyPath" : "clientEncryptionKey",
-    allowLegacyEncryptionAlgorithms: options.allowLegacyEncryptionAlgorithms
+    allowLegacyEncryptionAlgorithms: options.allowLegacyEncryptionAlgorithms,
+    encryptionAlgorithms: options.encryptionAlgorithms,
+    encryptionMethods: options.encryptionMethods
   });
+  const checks = resolveChecks(options.checks);
+  const codeChallengeMethod = resolveCodeChallengeMethod(options.codeChallengeMethod);
+  const responseMode = resolveResponseMode(options.responseMode);
+  const idTokenAlgorithm = resolveSigningAlgorithm(options.idTokenSignedResponseAlg, "idTokenSignedResponseAlg", options.clientSecret);
+  const userInfoAlgorithm = resolveSigningAlgorithm(options.userinfoSignedResponseAlg, "userinfoSignedResponseAlg", options.clientSecret) ?? idTokenAlgorithm;
+  const accessTokenAlgorithm = resolveSigningAlgorithm(options.accessTokenSignedResponseAlg, "accessTokenSignedResponseAlg", options.clientSecret);
+  const clientSecret = options.clientSecret === void 0 ? void 0 : () => readSecret(options.clientSecret);
   const signingKeys = createAuthioSigningKeys(connection, discovery);
   const tokens = createTokenClient(connection, discovery, authenticator);
   const clientCredentials = createClientCredentialsCache(connection, authenticator.clientId, tokens, refreshSkewMs);
-  const validationContext = async (signal) => ({
-    keys: await signingKeys(signal),
-    decrypt,
-    issuer: connection.issuer,
-    clientId: authenticator.clientId,
-    algorithms: options.validAlgorithms,
-    clockSkew,
-    now: connection.clock.now()
-  });
+  const validationContext = async (signal) => {
+    const document = await discovery.get(signal);
+    return {
+      keys: withClientSecret(await signingKeys(signal), clientSecret),
+      decrypt,
+      issuer: connection.issuer,
+      clientId: authenticator.clientId,
+      algorithms: acceptedSigningAlgorithms(idTokenAlgorithm, document.id_token_signing_alg_values_supported),
+      clockSkew,
+      now: connection.clock.now()
+    };
+  };
   const validateIdToken = async (idToken, expectations = {}) => {
     requireValue(idToken, "idToken");
     return validateAuthioIdToken(idToken, await validationContext(expectations.signal), expectations);
@@ -1075,7 +1178,13 @@ function createAuthioClient(options) {
     const redirectUri = request.redirectUri ?? options.redirectUri;
     requireValue(redirectUri, "redirectUri");
     const document = await discovery.get(request.signal);
-    return buildAuthorizationUrl(requireEndpoint(document, "authorization_endpoint"), authenticator.clientId, { ...request, redirectUri });
+    return buildAuthorizationUrl(requireEndpoint(document, "authorization_endpoint"), authenticator.clientId, {
+      ...request,
+      redirectUri,
+      checks: request.checks ?? checks,
+      codeChallengeMethod: request.codeChallengeMethod ?? codeChallengeMethod,
+      responseMode: request.responseMode ?? responseMode
+    });
   };
   return {
     issuer: connection.issuer,
@@ -1119,12 +1228,19 @@ function createAuthioClient(options) {
       );
       const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
       if (response.ok && mediaType === "application/jwt")
-        return readUserInfoJwt((await response.text()).trim(), document, connection, authenticator.clientId, decrypt, signingKeys, {
-          algorithms: options.validAlgorithms,
-          clockSkew,
-          status: response.status,
-          signal: callOptions.signal
-        });
+        return readUserInfoJwt(
+          (await response.text()).trim(),
+          document,
+          connection,
+          authenticator.clientId,
+          decrypt,
+          withClientSecret(await signingKeys(callOptions.signal), clientSecret),
+          {
+            algorithms: acceptedSigningAlgorithms(userInfoAlgorithm, document.userinfo_signing_alg_values_supported ?? document.id_token_signing_alg_values_supported),
+            clockSkew,
+            status: response.status
+          }
+        );
       if (!response.ok) {
         const body = await response.text();
         const challenge = toErrorResponse(body) ? void 0 : readBearerChallenge(response);
@@ -1134,9 +1250,10 @@ function createAuthioClient(options) {
     },
     createAuthorizationUrl,
     async handleAuthorizationCallback(callback, transaction, callOptions = {}) {
-      if (!transaction?.state || !transaction.redirectUri) throw new TypeError("transaction is required: keep what createAuthorizationUrl returned.");
+      if (!transaction?.redirectUri || !Array.isArray(transaction.checks))
+        throw new TypeError("transaction is required: keep what createAuthorizationUrl returned.");
       const parameters = readCallbackParameters(callback);
-      if (parameters.state !== transaction.state)
+      if (transaction.checks.includes("state") && (!transaction.state || parameters.state !== transaction.state))
         throw new AuthioCallbackError("state_mismatch", "The callback's state is not the one this sign-in was started with.");
       const document = await discovery.get(callOptions.signal);
       if (parameters.iss !== void 0) {
@@ -1150,12 +1267,12 @@ function createAuthioClient(options) {
       const answer = await tokens.authorizationCode({
         code: parameters.code,
         redirectUri: transaction.redirectUri,
-        codeVerifier: transaction.codeVerifier,
+        codeVerifier: transaction.checks.includes("pkce") ? transaction.codeVerifier : void 0,
         resource: transaction.resource,
         signal: callOptions.signal
       });
       const idToken = answer.id_token ? await validateIdToken(answer.id_token, {
-        nonce: transaction.nonce,
+        nonce: transaction.checks.includes("nonce") ? transaction.nonce : void 0,
         accessToken: answer.access_token,
         maxAge: transaction.maxAge,
         signal: callOptions.signal
@@ -1167,6 +1284,23 @@ function createAuthioClient(options) {
       requireValue(logoutToken, "logoutToken");
       return validateAuthioLogoutToken(logoutToken, await validationContext(callOptions.signal));
     },
+    validateFrontChannelLogout(request) {
+      return readAuthioFrontChannelLogout(request, connection.issuer);
+    },
+    async readAccessTokenClaims(accessToken, callOptions = {}) {
+      requireValue(accessToken, "accessToken");
+      if (isAuthioTokenEncrypted(accessToken) && encryptionKey === void 0) return void 0;
+      const signed = await decrypt(accessToken);
+      if (signed.split(".").length !== 3) return void 0;
+      const document = await discovery.get(callOptions.signal);
+      const { payload } = await verifyAuthioJwt(signed, withClientSecret(await signingKeys(callOptions.signal), clientSecret), {
+        issuer: connection.issuer,
+        algorithms: acceptedSigningAlgorithms(accessTokenAlgorithm, document.id_token_signing_alg_values_supported),
+        clockSkew,
+        now: connection.clock.now()
+      });
+      return payload;
+    },
     async createEndSessionUrl(request = {}) {
       const document = await discovery.get(request.signal);
       const url = new URL(requireEndpoint(document, "end_session_endpoint"));
@@ -1258,7 +1392,7 @@ function createTokenClient(connection, discovery, authenticator) {
     refresh: (options) => {
       requireValue(options?.refreshToken, "refreshToken");
       return requestToken(
-        { grant_type: AuthioGrantTypes.RefreshToken, refresh_token: options.refreshToken, scope: toScopeString(options.scopes) },
+        { grant_type: AuthioGrantTypes.RefreshToken, refresh_token: options.refreshToken, scope: toScopeString(options.scopes), resource: options.resource },
         options.signal
       );
     },
@@ -1453,10 +1587,10 @@ async function postForm(connection, discovery, authenticator, endpoint, paramete
   await authenticator?.apply(form, headers);
   return send(connection, url, { method: "POST", headers, body: form.toString() }, signal);
 }
-async function readUserInfoJwt(jwt, document, connection, clientId, decrypt, signingKeys, settings) {
+async function readUserInfoJwt(jwt, document, connection, clientId, decrypt, keys, settings) {
   try {
     const signed = isAuthioTokenEncrypted(jwt) ? await decrypt(jwt) : jwt;
-    const { payload } = await verifyAuthioJwt(signed, await signingKeys(settings.signal), {
+    const { payload } = await verifyAuthioJwt(signed, keys, {
       issuer: document.issuer.replace(/\/+$/, ""),
       audiences: [clientId],
       algorithms: settings.algorithms,
@@ -1488,6 +1622,33 @@ function readBearerChallenge(response) {
   }
   return error ? { error, description } : void 0;
 }
+function resolveCodeChallengeMethod(method) {
+  if (method !== void 0 && method !== "S256" && method !== "plain")
+    throw new AuthioConfigurationError(`The Authio codeChallengeMethod '${String(method)}' is not S256 or plain.`);
+  return method;
+}
+function resolveResponseMode(mode) {
+  if (mode !== void 0 && mode !== "query" && mode !== "web_message")
+    throw new AuthioConfigurationError(`The Authio responseMode '${String(mode)}' is not query or web_message.`);
+  return mode;
+}
+function resolveSigningAlgorithm(algorithm, setting, clientSecret) {
+  if (algorithm === void 0 || algorithm === "") return void 0;
+  const symmetric = AuthioHmacAlgorithms.includes(algorithm);
+  if (!symmetric && !AuthioAsymmetricAlgorithms.includes(algorithm))
+    throw new AuthioConfigurationError(
+      `The Authio ${setting} '${algorithm}' is not one of ${[...AuthioAsymmetricAlgorithms, ...AuthioHmacAlgorithms].join(", ")}.`
+    );
+  if (symmetric && !clientSecret)
+    throw new AuthioConfigurationError(`The Authio ${setting} ${algorithm} is verified with the client secret (OpenID Connect Core \xA710.1): set clientSecret.`);
+  if (symmetric && typeof clientSecret === "string") requireHmacSecretLength(algorithm, new TextEncoder().encode(clientSecret).length);
+  return algorithm;
+}
+async function readSecret(source) {
+  const value = typeof source === "function" ? await source() : source;
+  if (typeof value !== "string" || !value) throw new AuthioConfigurationError("The Authio clientSecret function returned no secret.");
+  return value;
+}
 function requireValue(value, name) {
   if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} is required.`);
 }
@@ -1540,7 +1701,7 @@ function createAuthioAccountCredential(options) {
       realm: AuthioDefaults.PlatformRealm,
       clientId: kind === "client_secret" ? toCredentialClientId(options.credentialId) : AuthioDefaults.PlatformClientId,
       clientSecret: kind === "client_secret" ? value : void 0,
-      clientAuthentication: kind === "client_secret" ? "client_secret_post" : "none"
+      tokenEndpointAuthMethod: kind === "client_secret" ? "client_secret_post" : "none"
     });
   }
   const exchange = async (signal) => {
@@ -1917,6 +2078,7 @@ exports.AuthioAdminError = AuthioAdminError;
 exports.AuthioAsymmetricAlgorithms = AuthioAsymmetricAlgorithms;
 exports.AuthioCallbackError = AuthioCallbackError;
 exports.AuthioCallerKinds = AuthioCallerKinds;
+exports.AuthioChecks = AuthioChecks;
 exports.AuthioClaimTypes = AuthioClaimTypes;
 exports.AuthioClientAssertionAlgorithms = AuthioClientAssertionAlgorithms;
 exports.AuthioConfigurationError = AuthioConfigurationError;
@@ -1925,6 +2087,8 @@ exports.AuthioDefaults = AuthioDefaults;
 exports.AuthioDiscoveryError = AuthioDiscoveryError;
 exports.AuthioError = AuthioError;
 exports.AuthioGrantTypes = AuthioGrantTypes;
+exports.AuthioHmacAlgorithms = AuthioHmacAlgorithms;
+exports.AuthioHmacMinimumSecretBytes = AuthioHmacMinimumSecretBytes;
 exports.AuthioKeyManagementAlgorithms = AuthioKeyManagementAlgorithms;
 exports.AuthioLegacyKeyManagementAlgorithms = AuthioLegacyKeyManagementAlgorithms;
 exports.AuthioOAuthErrors = AuthioOAuthErrors;
@@ -1933,6 +2097,8 @@ exports.AuthioProtocolError = AuthioProtocolError;
 exports.AuthioResourceAccess = AuthioResourceAccess;
 exports.AuthioResourceAccessClaims = AuthioResourceAccessClaims;
 exports.AuthioScopes = AuthioScopes;
+exports.AuthioSupportedContentEncryptionAlgorithms = AuthioSupportedContentEncryptionAlgorithms;
+exports.AuthioTokenEndpointAuthMethods = AuthioTokenEndpointAuthMethods;
 exports.AuthioTokenTypes = AuthioTokenTypes;
 exports.AuthioTokenValidationError = AuthioTokenValidationError;
 exports.AuthioWebhookEventTypes = AuthioWebhookEventTypes;
@@ -1969,7 +2135,9 @@ exports.parseResourceAccessClaim = parseResourceAccessClaim;
 exports.parseWebhookEvent = parseWebhookEvent;
 exports.randomValue = randomValue;
 exports.readAuthioAdminResponse = readAuthioAdminResponse;
+exports.readAuthioFrontChannelLogout = readAuthioFrontChannelLogout;
 exports.readWebhookEventData = readWebhookEventData;
+exports.requireHmacSecretLength = requireHmacSecretLength;
 exports.resolveConnection = resolveConnection;
 exports.resolveIssuer = resolveIssuer;
 exports.resourceAccessSourceOf = resourceAccessSourceOf;
@@ -1986,5 +2154,6 @@ exports.toTokenValidationError = toTokenValidationError;
 exports.tryParseWebhookEvent = tryParseWebhookEvent;
 exports.verifyAuthioJwt = verifyAuthioJwt;
 exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.withClientSecret = withClientSecret;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map