@hyper.authio/client 0.1.1 → 0.8.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { compactDecrypt, createRemoteJWKSet, customFetch, jwtVerify, importPKCS8, SignJWT, importJWK } from 'jose';
+import { compactDecrypt, errors, decodeProtectedHeader, createRemoteJWKSet, customFetch, jwtVerify, importPKCS8, SignJWT, importJWK } from 'jose';
 
 // src/constants.ts
 var AuthioClaimTypes = {
@@ -18,6 +18,8 @@ var AuthioClaimTypes = {
   AuthenticationMethods: "amr",
   IdentityProvider: "idp",
   Nonce: "nonce",
+  AccessTokenHash: "at_hash",
+  Events: "events",
   OrganizationId: "org_id",
   OrganizationAlias: "org_alias",
   AccountId: "account_id",
@@ -37,6 +39,12 @@ var AuthioClaimTypes = {
   ConsumerName: "consumer_name",
   CredentialId: "credential_id",
   CredentialType: "credential_type",
+  CredentialName: "credential_name",
+  CredentialRealm: "credential_realm",
+  CredentialClient: "credential_client",
+  ActorType: "actor_type",
+  OwnerUserId: "owner_user_id",
+  OwnerUsername: "owner_username",
   UserResourceAccess: "user_resource_access",
   RealmResourceAccess: "realm_resource_access",
   ClientResourceAccess: "client_resource_access",
@@ -94,7 +102,13 @@ var AuthioOAuthErrors = {
   ConnectionSelectionRequired: "connection_selection_required",
   ConnectionPolicyViolation: "connection_policy_violation",
   ServerError: "server_error",
-  TemporarilyUnavailable: "temporarily_unavailable"
+  TemporarilyUnavailable: "temporarily_unavailable",
+  LoginRequired: "login_required",
+  InteractionRequired: "interaction_required",
+  ConsentRequired: "consent_required",
+  AccountSelectionRequired: "account_selection_required",
+  InsufficientScope: "insufficient_scope",
+  InsufficientUserAuthentication: "insufficient_user_authentication"
 };
 var AuthioWebhookEventTypes = {
   UserCreated: "user_created",
@@ -111,6 +125,8 @@ var AuthioWebhookEventTypes = {
   AdminResourceDeleted: "admin_resource_deleted",
   UserSuspended: "user_suspended",
   UserSuspensionEnded: "user_suspension_ended",
+  AttackDetected: "attack_detected",
+  CredentialCompromised: "credential_compromised",
   Ping: "ping"
 };
 var AuthioWebhookHeaders = {
@@ -118,6 +134,8 @@ var AuthioWebhookHeaders = {
   Event: "X-Authio-Event",
   EventId: "X-Authio-Event-Id"
 };
+var AuthioCallerKinds = ["user", "client", "consumer", "account_credential"];
+var AuthioPrompts = ["none", "login", "select_account", "consent"];
 var AuthioAsymmetricAlgorithms = [
   "RS256",
   "RS384",
@@ -129,14 +147,27 @@ 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",
   RedactedValue: "[redacted]",
   PlatformRealm: "authio",
   PlatformClientId: "authio",
   ApiKeyPrefix: "ak_",
   ClientSecretPrefix: "cs_",
   PersonalAccessTokenPrefix: "pat_",
+  /** The `client_id` an account credential's client secret is exchanged with: `cred_` and the credential id (format N). */
+  CredentialClientIdPrefix: "cred_",
+  ApiKeyHeader: "x-api-key",
+  RequestIdHeader: "X-Request-Id",
+  /** The header `typ` of a back-channel logout token. */
+  LogoutTokenType: "logout+jwt",
+  /** The event a back-channel logout token carries. */
+  BackchannelLogoutEvent: "http://schemas.openid.net/event/backchannel-logout",
+  /** Seconds. */
+  ClockSkew: 30,
   /** Seconds. */
   ClientAssertionLifetime: 120,
   /** Seconds. */
@@ -188,6 +219,47 @@ var AuthioDiscoveryError = class extends AuthioError {
 };
 var AuthioConfigurationError = class extends AuthioError {
 };
+var AuthioTokenValidationError = class extends AuthioError {
+  /** Why, as a stable code. */
+  reason;
+  constructor(reason, message, options) {
+    super(message, options);
+    this.reason = reason;
+  }
+};
+var AuthioCallbackError = class extends AuthioError {
+  /** Why, as a stable code. */
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+  }
+};
+var AuthioAdminError = class extends AuthioError {
+  /** The HTTP status. */
+  status;
+  /** Authio's error code, such as `ValidationFailed` or `RealmNotFound`. */
+  errorCode;
+  /** The messages, with the field each one is about. */
+  notifications;
+  /** The request id, from the envelope or the `X-Request-Id` header. */
+  requestId;
+  /** Seconds to wait before retrying, from `Retry-After` (`429` and `503`). */
+  retryAfterSeconds;
+  constructor(details) {
+    const notifications = details.notifications ?? [];
+    const summary = notifications.map((notification) => notification.message).filter(Boolean).join(" ");
+    super(
+      `The Authio Admin API answered HTTP ${details.status}${details.errorCode ? ` (${details.errorCode})` : ""}${summary ? `: ${summary}` : "."}`,
+      { cause: details.cause }
+    );
+    this.status = details.status;
+    this.errorCode = details.errorCode;
+    this.notifications = Object.freeze([...notifications]);
+    this.requestId = details.requestId;
+    this.retryAfterSeconds = details.retryAfterSeconds;
+  }
+};
 
 // src/options.ts
 var systemClock = {
@@ -208,6 +280,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);
@@ -523,7 +601,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)
@@ -534,17 +614,22 @@ function createClientAuthenticator(settings, connection) {
       `The Authio clientAssertionLifetime must be more than 0 and at most ${AuthioDefaults.MaxClientAssertionLifetime} seconds.`
     );
   const loadKey = method === "private_key_jwt" ? createKeyLoader(settings) : void 0;
+  const secret = async () => {
+    const value = typeof settings.clientSecret === "function" ? await settings.clientSecret() : settings.clientSecret;
+    if (typeof value !== "string" || !value) throw new AuthioConfigurationError("The Authio clientSecret function returned no secret.");
+    return value;
+  };
   return {
     clientId,
     method,
     async apply(form, headers) {
       switch (method) {
         case "client_secret_basic":
-          headers.set("authorization", toBasicAuthorization(clientId, settings.clientSecret));
+          headers.set("authorization", toBasicAuthorization(clientId, await secret()));
           return;
         case "client_secret_post":
           form.set("client_id", clientId);
-          form.set("client_secret", settings.clientSecret);
+          form.set("client_secret", await secret());
           return;
         case "private_key_jwt":
           form.set("client_id", clientId);
@@ -598,17 +683,28 @@ 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;
 }
-function createAuthioTokenDecrypter(key, setting = "clientEncryptionKey") {
+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);
     if (!pending) {
-      pending = importDecryptionKey(key, algorithm, setting);
+      pending = Promise.resolve(typeof key === "function" ? key() : key).then((value) => importDecryptionKey(value, algorithm, setting));
       imported.set(algorithm, pending);
       pending.catch(() => imported.delete(algorithm));
     }
@@ -616,17 +712,83 @@ function createAuthioTokenDecrypter(key, setting = "clientEncryptionKey") {
   };
   return async (token) => {
     if (!isAuthioTokenEncrypted(token)) return token;
-    if (!key)
-      throw new AuthioError(
+    const algorithm = algorithmOf(token);
+    if (AuthioLegacyKeyManagementAlgorithms.includes(algorithm))
+      throw new AuthioTokenValidationError(
+        "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 (!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's content is encrypted with '${method}', and encryptionMethods accepts ${contentEncryptionAlgorithms.join(" or ")}.`
+      );
+    if (key === void 0 || key === null || key === "")
+      throw new AuthioTokenValidationError(
+        "decryption_failed",
         `Authio encrypted this token to the client's own key; set ${setting} to the private key Authio showed when it generated the pair.`
       );
-    const { plaintext } = await compactDecrypt(token, (header) => importFor(header.alg), {
-      keyManagementAlgorithms: [...AuthioKeyManagementAlgorithms],
-      contentEncryptionAlgorithms: [...AuthioContentEncryptionAlgorithms]
-    });
-    return new TextDecoder().decode(plaintext);
+    try {
+      const { plaintext } = await compactDecrypt(token, (header) => importFor(header.alg), {
+        keyManagementAlgorithms: [...keyManagementAlgorithms],
+        contentEncryptionAlgorithms: [...contentEncryptionAlgorithms]
+      });
+      return new TextDecoder().decode(plaintext);
+    } catch (error) {
+      if (error instanceof AuthioConfigurationError) throw error;
+      if (error instanceof errors.JOSEError)
+        throw new AuthioTokenValidationError("decryption_failed", `The token could not be decrypted with ${setting}: ${error.message}`, { cause: error });
+      throw error;
+    }
   };
 }
+function encryptionKeyFromFile(path, setting = "clientEncryptionKeyPath") {
+  let current;
+  return async () => {
+    const nodeCrypto = await loadNodeCrypto();
+    if (!nodeCrypto) throw new AuthioConfigurationError(`${setting} needs Node; pass clientEncryptionKey instead.`);
+    const { readFile, stat } = await import('fs/promises');
+    let written;
+    try {
+      written = (await stat(path)).mtimeMs;
+    } catch (error) {
+      throw new AuthioConfigurationError(`${setting} '${path}' could not be read.`, { cause: error });
+    }
+    if (!current || current.written !== written) current = { written, key: readFile(path, "utf8") };
+    return current.key;
+  };
+}
+function algorithmOf(token) {
+  try {
+    return String(decodeProtectedHeader(token).alg ?? "");
+  } catch (error) {
+    throw new AuthioTokenValidationError("decryption_failed", "The encrypted token's header could not be read.", { cause: error });
+  }
+}
+function contentMethodOf(token) {
+  try {
+    return String(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);
@@ -666,14 +828,362 @@ function toBase64(bytes) {
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary);
 }
+function createAuthioSigningKeys(connection, discovery) {
+  let keys;
+  return async (signal) => {
+    const document = await discovery.get(signal);
+    const uri = document.jwks_uri;
+    if (!uri) throw new AuthioError("The Authio discovery document has no jwks_uri.");
+    if (!keys || keys.uri !== uri)
+      keys = { uri, set: createRemoteJWKSet(new URL(uri), { [customFetch]: connection.fetch, timeoutDuration: connection.httpTimeoutMs }) };
+    return keys.set;
+  };
+}
+async function verifyAuthioJwt(token, keys, expected) {
+  if (!looksLikeJws(token))
+    throw new AuthioTokenValidationError("reference_token", "The token is not a JWT; only introspection can resolve it ('introspectionOnly').");
+  try {
+    const { payload, protectedHeader } = await jwtVerify(token, keys, {
+      issuer: expected.issuer,
+      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 ?? []])],
+      currentDate: new Date(expected.now)
+    });
+    return { payload, header: protectedHeader };
+  } catch (error) {
+    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 });
+  if (error instanceof errors.JWTExpired) {
+    const exp = error.payload.exp;
+    return refuse("expired", typeof exp === "number" ? `The token expired at '${new Date(exp * 1e3).toISOString()}'` : "The token has expired");
+  }
+  if (error instanceof errors.JWTClaimValidationFailed) {
+    switch (error.claim) {
+      case "aud":
+        return refuse("invalid_audience", describeAudience([error.payload.aud ?? []].flat(), audiences));
+      case "iss":
+        return refuse("invalid_issuer", `The issuer '${error.payload.iss ?? ""}' is invalid`);
+      case "nbf":
+        return refuse(
+          "not_yet_valid",
+          typeof error.payload.nbf === "number" ? `The token is not valid before '${new Date(error.payload.nbf * 1e3).toISOString()}'` : "The token is not valid yet"
+        );
+      case "exp":
+        return refuse("expired", "The token has no expiration");
+      default:
+        return refuse("malformed", `The token's ${error.claim} claim is invalid`);
+    }
+  }
+  if (error instanceof errors.JWSSignatureVerificationFailed) return refuse("invalid_signature", "The signature is invalid");
+  if (error instanceof errors.JWKSNoMatchingKey || error instanceof errors.JWKSMultipleMatchingKeys)
+    return refuse("invalid_signature", "The signature key was not found");
+  if (error instanceof errors.JOSEAlgNotAllowed) return refuse("invalid_algorithm", `The algorithm '${algorithmOf2(token)}' is not available`);
+  if (error instanceof errors.JWKSTimeout || error instanceof errors.JWKSInvalid)
+    return refuse("signing_keys_unavailable", "Authio could not be reached to read its signing keys.");
+  if (error instanceof errors.JWTInvalid || error instanceof errors.JWSInvalid) return refuse("malformed", "The token is malformed");
+  if (error instanceof errors.JOSEError) return refuse("malformed", error.message);
+  return refuse("signing_keys_unavailable", "Authio could not be reached to read its signing keys.");
+}
+async function computeAuthioTokenHash(value, algorithm) {
+  const size = /(\d{3})$/.exec(algorithm)?.[1];
+  const hash = size === "384" ? "SHA-384" : size === "512" ? "SHA-512" : "SHA-256";
+  const digest = new Uint8Array(await crypto.subtle.digest(hash, new TextEncoder().encode(value)));
+  return toBase64Url(digest.subarray(0, digest.length / 2));
+}
+async function validateAuthioIdToken(token, context, expectations = {}) {
+  const signed = isAuthioTokenEncrypted(token) ? await context.decrypt(token) : token;
+  const { payload, header } = await verifyAuthioJwt(signed, context.keys, {
+    issuer: context.issuer,
+    audiences: [context.clientId],
+    algorithms: context.algorithms,
+    clockSkew: context.clockSkew,
+    now: context.now,
+    requiredClaims: ["sub", "iat"]
+  });
+  const type = typeof payload.typ === "string" ? payload.typ : void 0;
+  if (type !== void 0 && type.toLowerCase() !== "id")
+    throw new AuthioTokenValidationError("not_id_token", `Only ID tokens are accepted; this token's typ is '${type}'.`);
+  const audiences = [payload.aud ?? []].flat();
+  if (audiences.length > 1 && payload.azp !== context.clientId)
+    throw new AuthioTokenValidationError("invalid_audience", `The ID token has several audiences and its azp is not '${context.clientId}'.`);
+  if (expectations.nonce !== void 0 && payload[AuthioClaimTypes.Nonce] !== expectations.nonce)
+    throw new AuthioTokenValidationError(
+      "invalid_nonce",
+      payload[AuthioClaimTypes.Nonce] === void 0 ? "The ID token carries no nonce, although one was sent." : "The ID token's nonce is not the one sent."
+    );
+  const atHash = payload[AuthioClaimTypes.AccessTokenHash];
+  if (expectations.accessToken !== void 0 && typeof atHash === "string") {
+    const expected = await computeAuthioTokenHash(expectations.accessToken, String(header.alg ?? ""));
+    if (expected !== atHash) throw new AuthioTokenValidationError("invalid_at_hash", "The ID token's at_hash does not match the access token.");
+  }
+  if (expectations.maxAge !== void 0) {
+    const authTime = payload[AuthioClaimTypes.AuthTime];
+    const skew = context.clockSkew ?? AuthioDefaults.ClockSkew;
+    if (typeof authTime !== "number")
+      throw new AuthioTokenValidationError("authentication_too_old", "max_age was requested, and the ID token carries no auth_time.");
+    if ((authTime + expectations.maxAge + skew) * 1e3 < context.now)
+      throw new AuthioTokenValidationError(
+        "authentication_too_old",
+        `The person signed in at '${new Date(authTime * 1e3).toISOString()}', more than ${expectations.maxAge} seconds ago.`
+      );
+  }
+  return payload;
+}
+async function validateAuthioLogoutToken(token, context) {
+  const signed = isAuthioTokenEncrypted(token) ? await context.decrypt(token) : token;
+  const invalid = (message) => new AuthioTokenValidationError("invalid_logout_token", message);
+  let headerType;
+  try {
+    const header = decodeProtectedHeader(signed);
+    headerType = typeof header.typ === "string" ? header.typ.toLowerCase() : void 0;
+  } catch (error) {
+    throw new AuthioTokenValidationError("malformed", "The logout token is malformed", { cause: error });
+  }
+  const { payload } = await verifyAuthioJwt(signed, context.keys, {
+    issuer: context.issuer,
+    audiences: [context.clientId],
+    algorithms: context.algorithms,
+    clockSkew: context.clockSkew,
+    now: context.now,
+    requiredClaims: ["iat"]
+  });
+  if (headerType !== AuthioDefaults.LogoutTokenType && headerType !== `application/${AuthioDefaults.LogoutTokenType}`)
+    throw invalid(`The token's header typ is '${headerType ?? ""}', not '${AuthioDefaults.LogoutTokenType}'.`);
+  const events = payload[AuthioClaimTypes.Events];
+  if (!events || typeof events !== "object" || Array.isArray(events) || typeof events[AuthioDefaults.BackchannelLogoutEvent] !== "object")
+    throw invalid("The token carries no back-channel logout event.");
+  if (payload[AuthioClaimTypes.Nonce] !== void 0) throw invalid("A logout token must not carry a nonce.");
+  const subject = typeof payload.sub === "string" && payload.sub ? payload.sub : void 0;
+  const sessionId = typeof payload.sid === "string" && payload.sid ? payload.sid : void 0;
+  if (!subject && !sessionId) throw invalid("The logout token names neither a subject nor a session.");
+  return Object.freeze({ subject, sessionId, tokenId: typeof payload.jti === "string" ? payload.jti : void 0, claims: Object.freeze({ ...payload }) });
+}
+function describeAudience(tokenAudiences, audiences) {
+  const known = tokenAudiences.length === 0 ? "" : ` ${tokenAudiences.map((audience) => `'${audience}'`).join(" and ")}`;
+  const accepted = audiences.map((audience) => `'${audience}'`).join(" or ");
+  return audiences.length === 1 ? `The token is not addressed to this API: its audience${known} is not ${accepted}. Request the token for that resource (RFC 8707).` : `The token is not addressed to this API: its audience${known} is not ${accepted}. Request the token for one of those resources (RFC 8707).`;
+}
+function looksLikeJws(token) {
+  const parts = token.split(".");
+  return parts.length === 3 && parts[0].length > 0;
+}
+function algorithmOf2(token) {
+  try {
+    return String(decodeProtectedHeader(token).alg ?? "");
+  } catch {
+    return "";
+  }
+}
+function toBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// 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);
+  const codeChallenge = method === "plain" ? codeVerifier : toBase64Url2(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(codeVerifier))));
+  return { codeVerifier, codeChallenge, codeChallengeMethod: method };
+}
+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 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,
+    response_type: "code",
+    client_id: clientId,
+    redirect_uri: request.redirectUri,
+    scope: toScopeString(request.scopes) ?? "openid",
+    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),
+    max_age: request.maxAge?.toString(),
+    acr_values: joined(request.acrValues),
+    login_hint: request.loginHint,
+    id_token_hint: request.idTokenHint,
+    ui_locales: joined(request.uiLocales),
+    display,
+    response_mode: responseMode,
+    idp_hint: request.idpHint
+  };
+  for (const [name, value] of Object.entries(parameters)) if (value !== void 0 && value !== "") url.searchParams.set(name, value);
+  return {
+    url: url.toString(),
+    transaction: Object.freeze({
+      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 } : {}
+    })
+  };
+}
+function readCallbackParameters(callback) {
+  if (callback instanceof URLSearchParams) return Object.fromEntries(callback);
+  if (callback instanceof URL) return Object.fromEntries(callback.searchParams);
+  if (typeof callback === "string") {
+    const text = callback.trim();
+    const query = /^[a-z][a-z0-9+.-]*:/i.test(text) ? new URL(text).search : text.slice(text.indexOf("?") + 1);
+    return Object.fromEntries(new URLSearchParams(query));
+  }
+  const parameters = {};
+  for (const [name, value] of Object.entries(callback ?? {})) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (typeof first === "string") parameters[name] = first;
+  }
+  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 = {};
+  for (const match of header.matchAll(/([a-zA-Z_]+)\s*=\s*"((?:[^"\\]|\\.)*)"|([a-zA-Z_]+)\s*=\s*([^,\s]+)/g)) {
+    const name = (match[1] ?? match[3] ?? "").toLowerCase();
+    values[name] ??= (match[2] ?? match[4] ?? "").replace(/\\(.)/g, "$1");
+  }
+  const maxAge = values.max_age !== void 0 && /^\d+$/.test(values.max_age) ? Number(values.max_age) : void 0;
+  return {
+    error: values.error,
+    errorDescription: values.error_description,
+    scope: values.scope,
+    acrValues: values.acr_values,
+    maxAge,
+    resourceMetadata: values.resource_metadata
+  };
+}
+function joined(value) {
+  if (value === void 0) return void 0;
+  const text = (typeof value === "string" ? [value] : [...value]).map((item) => item.trim()).filter(Boolean).join(" ");
+  return text || void 0;
+}
+function toBase64Url2(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// src/client.ts
 function createAuthioClient(options) {
   const connection = resolveConnection(options);
   const discovery = createAuthioDiscoveryClient(connection);
   const authenticator = createClientAuthenticator(options, connection);
   const refreshSkewMs = seconds(options.tokenRefreshSkew, AuthioDefaults.TokenRefreshSkew, "tokenRefreshSkew");
-  const decrypt = createAuthioTokenDecrypter(options.clientEncryptionKey);
+  const clockSkew = seconds(options.clockSkew, AuthioDefaults.ClockSkew, "clockSkew") / 1e3;
+  const encryptionKey = resolveEncryptionKey(options);
+  const decrypt = createAuthioTokenDecrypter(encryptionKey, {
+    setting: options.clientEncryptionKey === void 0 && options.clientEncryptionKeyPath ? "clientEncryptionKeyPath" : "clientEncryptionKey",
+    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) => {
+    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);
+  };
+  const createAuthorizationUrl = async (request = {}) => {
+    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,
+      checks: request.checks ?? checks,
+      codeChallengeMethod: request.codeChallengeMethod ?? codeChallengeMethod,
+      responseMode: request.responseMode ?? responseMode
+    });
+  };
   return {
     issuer: connection.issuer,
     clientId: authenticator.clientId,
@@ -716,7 +1226,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, response.status);
+        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);
@@ -724,6 +1246,84 @@ function createAuthioClient(options) {
       }
       return readProtocolJson(response);
     },
+    createAuthorizationUrl,
+    async handleAuthorizationCallback(callback, transaction, callOptions = {}) {
+      if (!transaction?.redirectUri || !Array.isArray(transaction.checks))
+        throw new TypeError("transaction is required: keep what createAuthorizationUrl returned.");
+      const parameters = readCallbackParameters(callback);
+      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) {
+        if (parameters.iss.replace(/\/+$/, "") !== connection.issuer)
+          throw new AuthioCallbackError("issuer_mismatch", `The callback comes from the issuer '${parameters.iss}', not '${connection.issuer}' (RFC 9207).`);
+      } else if (document.authorization_response_iss_parameter_supported === true) {
+        throw new AuthioCallbackError("missing_issuer", "The callback carries no iss parameter, although Authio sends one (RFC 9207).");
+      }
+      if (parameters.error) throw new AuthioProtocolError(parameters.error, parameters.error_description, parameters.error_code);
+      if (!parameters.code) throw new AuthioCallbackError("missing_code", "The callback carries neither a code nor an error.");
+      const answer = await tokens.authorizationCode({
+        code: parameters.code,
+        redirectUri: transaction.redirectUri,
+        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.checks.includes("nonce") ? transaction.nonce : void 0,
+        accessToken: answer.access_token,
+        maxAge: transaction.maxAge,
+        signal: callOptions.signal
+      }) : void 0;
+      return { tokens: answer, idToken };
+    },
+    validateIdToken,
+    async validateLogoutToken(logoutToken, callOptions = {}) {
+      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"));
+      const locales = request.uiLocales === void 0 ? void 0 : (typeof request.uiLocales === "string" ? [request.uiLocales] : [...request.uiLocales]).join(" ");
+      const parameters = {
+        id_token_hint: request.idTokenHint,
+        post_logout_redirect_uri: request.postLogoutRedirectUri ?? options.postLogoutRedirectUri,
+        state: request.state,
+        ui_locales: locales,
+        client_id: request.includeClientId === false ? void 0 : authenticator.clientId
+      };
+      for (const [name, value] of Object.entries(parameters)) if (value) url.searchParams.set(name, value);
+      return url.toString();
+    },
+    async createStepUpAuthorizationUrl(challenge, request = {}) {
+      const parsed = typeof challenge === "string" ? parseAuthioBearerChallenge(challenge) : challenge;
+      if (!parsed || parsed.error !== AuthioOAuthErrors.InsufficientUserAuthentication)
+        throw new TypeError("The challenge is not an insufficient_user_authentication bearer challenge.");
+      return createAuthorizationUrl({
+        ...request,
+        acrValues: request.acrValues ?? parsed.acrValues,
+        maxAge: request.maxAge ?? parsed.maxAge,
+        prompt: request.prompt ?? (parsed.maxAge === 0 ? "login" : void 0)
+      });
+    },
     clientCredentialsFetch(fetchOptions = {}) {
       const inner = fetchOptions.fetch ?? connection.fetch;
       const key = { scopes: fetchOptions.scopes, resource: fetchOptions.resource };
@@ -745,8 +1345,8 @@ function createAuthioClient(options) {
   };
 }
 function createTokenClient(connection, discovery, authenticator) {
-  const requestToken = async (parameters, signal) => {
-    const response = await postForm(connection, discovery, authenticator, "token_endpoint", parameters, signal);
+  const requestToken = async (parameters, signal, authenticate = true) => {
+    const response = await postForm(connection, discovery, authenticate ? authenticator : void 0, "token_endpoint", parameters, signal);
     const token = await readProtocolJson(response);
     return redact(token, ["access_token", "refresh_token", "id_token"]);
   };
@@ -762,12 +1362,9 @@ function createTokenClient(connection, discovery, authenticator) {
         return await requestToken({ grant_type: AuthioGrantTypes.DeviceCode, device_code: authorization.device_code }, options.signal);
       } catch (error) {
         if (!(error instanceof AuthioProtocolError)) throw error;
-        if (error.error === AuthioOAuthErrors.AuthorizationPending) continue;
-        if (error.error === AuthioOAuthErrors.SlowDown) {
-          wait += AuthioDefaults.DeviceSlowDownIncrement * 1e3;
-          continue;
-        }
-        throw error;
+        const outcome = toDevicePollOutcome(error.error);
+        if (outcome.outcome === "failed") throw error;
+        wait += outcome.intervalIncrease * 1e3;
       }
     }
   };
@@ -793,7 +1390,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
       );
     },
@@ -843,6 +1440,20 @@ function createTokenClient(connection, discovery, authenticator) {
       return redact(await readProtocolJson(response), ["device_code"]);
     },
     pollDevice,
+    personalAccessToken: (options) => {
+      requireValue(options?.token, "token");
+      return requestToken(
+        {
+          grant_type: AuthioGrantTypes.PersonalAccessToken,
+          client_secret: options.token,
+          client_id: options.clientId,
+          scope: toScopeString(options.scopes),
+          resource: options.resource
+        },
+        options.signal,
+        false
+      );
+    },
     password: (options) => {
       requireValue(options?.username, "username");
       if (typeof options.password !== "string") throw new TypeError("password is required.");
@@ -900,48 +1511,90 @@ function toConnectionExchangeResult(body, status, provider) {
     const token = parseProtocolJson(body, status);
     if (typeof token.access_token === "string" && token.access_token)
       return redact(
-        {
+        withoutUndefined({
           status: "granted",
           accessToken: token.access_token,
-          provider: typeof token.provider === "string" && token.provider ? token.provider : provider,
-          providerType: token.provider_type,
-          connectionId: token.connection_id,
-          tokenType: token.token_type,
-          issuedTokenType: token.issued_token_type,
-          scope: token.scope,
-          externalAccount: token.external_account,
-          expiresIn: token.expires_in
-        },
+          issuedTokenType: textOf(token.issued_token_type),
+          tokenType: textOf(token.token_type),
+          expiresIn: typeof token.expires_in === "number" ? token.expires_in : void 0,
+          scope: textOf(token.scope),
+          connectionId: textOf(token.connection_id),
+          provider: textOf(token.provider) ?? provider,
+          providerType: textOf(token.provider_type),
+          externalAccount: token.external_account && typeof token.external_account === "object" ? token.external_account : void 0
+        }),
         ["accessToken"]
       );
   }
   const error = toErrorResponse(body);
-  const description = error?.error_description?.trim() ? error.error_description : `Authio answered HTTP ${status} to the connected-account token exchange.`;
+  const errorDescription = error?.error_description?.trim() ? error.error_description : `Authio answered HTTP ${status} to the connected-account token exchange.`;
+  const errorCode = textOf(error?.error_code);
   switch (error?.error) {
     case AuthioOAuthErrors.ConnectionRequired:
-      return { status: "required", connectUri: error.connect_uri, description };
+      return withoutUndefined({
+        status: "required",
+        connectUri: textOf(error.connect_uri),
+        provider: textOf(error.connection_provider) ?? provider,
+        errorCode,
+        errorDescription
+      });
     case AuthioOAuthErrors.ConnectionSelectionRequired:
-      return { status: "selection_required", connections: error.connections ?? [], description };
+      return withoutUndefined({
+        status: "selection_required",
+        provider: textOf(error.connection_provider) ?? provider,
+        connections: (Array.isArray(error.connections) ? error.connections : []).map(toConnectionChoice),
+        errorCode,
+        errorDescription
+      });
     default:
-      return { status: "refused", error: error?.error ?? `http_${status}`, code: error?.error_code, description, connectUri: error?.connect_uri };
+      return withoutUndefined({
+        status: "refused",
+        error: error?.error ?? `http_${status}`,
+        errorCode,
+        errorDescription,
+        connectUri: textOf(error?.connect_uri)
+      });
   }
 }
+function toDevicePollOutcome(error) {
+  if (error === AuthioOAuthErrors.AuthorizationPending) return { outcome: "keep_polling", intervalIncrease: 0 };
+  if (error === AuthioOAuthErrors.SlowDown) return { outcome: "keep_polling", intervalIncrease: AuthioDefaults.DeviceSlowDownIncrement };
+  return { outcome: "failed", error };
+}
+function toConnectionChoice(value) {
+  const record = value && typeof value === "object" ? value : {};
+  return withoutUndefined({ id: textOf(record.id) ?? "", label: textOf(record.label), externalLogin: textOf(record.external_login) });
+}
+function textOf(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function withoutUndefined(value) {
+  for (const key of Object.keys(value)) if (value[key] === void 0) delete value[key];
+  return value;
+}
+function resolveEncryptionKey(options) {
+  if (options.clientEncryptionKey !== void 0) return options.clientEncryptionKey;
+  if (options.clientEncryptionKeyPath) return encryptionKeyFromFile(options.clientEncryptionKeyPath);
+  return void 0;
+}
 async function postForm(connection, discovery, authenticator, endpoint, parameters, signal) {
   const document = await discovery.get(signal);
   const url = requireEndpoint(document, endpoint);
   const form = formBody(parameters);
   const headers = new Headers({ accept: "application/json", "content-type": "application/x-www-form-urlencoded" });
-  await authenticator.apply(form, headers);
+  await authenticator?.apply(form, headers);
   return send(connection, url, { method: "POST", headers, body: form.toString() }, signal);
 }
-async function readUserInfoJwt(jwt, document, connection, clientId, decrypt, status) {
+async function readUserInfoJwt(jwt, document, connection, clientId, decrypt, keys, settings) {
   try {
     const signed = isAuthioTokenEncrypted(jwt) ? await decrypt(jwt) : jwt;
-    const keys = createRemoteJWKSet(new URL(requireEndpoint(document, "jwks_uri")), { [customFetch]: connection.fetch });
-    const { payload } = await jwtVerify(signed, keys, {
-      issuer: document.issuer,
-      audience: clientId,
-      clockTolerance: 30
+    const { payload } = await verifyAuthioJwt(signed, keys, {
+      issuer: document.issuer.replace(/\/+$/, ""),
+      audiences: [clientId],
+      algorithms: settings.algorithms,
+      clockSkew: settings.clockSkew,
+      now: connection.clock.now(),
+      requiredClaims: ["sub"]
     });
     return payload;
   } catch (error) {
@@ -949,7 +1602,7 @@ async function readUserInfoJwt(jwt, document, connection, clientId, decrypt, sta
       "invalid_userinfo",
       `The userinfo JWT could not be verified: ${error?.message ?? "unknown reason."}`,
       void 0,
-      status,
+      settings.status,
       { cause: error }
     );
   }
@@ -967,10 +1620,180 @@ 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.`);
 }
 
+// src/admin.ts
+function parseAuthioAdminEnvelope(status, body, headers) {
+  const parsed = parseJson(body);
+  if (status >= 200 && status < 300) {
+    if (!parsed) return { ok: true };
+    return withoutUndefined2({ ok: true, data: parsed.data });
+  }
+  const notifications = Array.isArray(parsed?.notifications) ? parsed.notifications.map(toNotification).filter((item) => item.message) : [];
+  return {
+    ok: false,
+    error: new AuthioAdminError({
+      status,
+      errorCode: textOf2(parsed?.errorCode),
+      notifications,
+      requestId: textOf2(parsed?.requestId) ?? headerOf(headers, AuthioDefaults.RequestIdHeader),
+      retryAfterSeconds: retryAfterOf(headerOf(headers, "Retry-After"))
+    })
+  };
+}
+async function readAuthioAdminResponse(response) {
+  const envelope = parseAuthioAdminEnvelope(response.status, response.status === 204 ? null : await response.text(), response.headers);
+  if (!envelope.ok) throw envelope.error;
+  return envelope;
+}
+function createAuthioAccountCredential(options) {
+  const value = options.credential?.trim();
+  if (!value) throw new AuthioConfigurationError("The account credential is required.");
+  const kind = value.startsWith(AuthioDefaults.ApiKeyPrefix) ? "api_key" : value.startsWith(AuthioDefaults.ClientSecretPrefix) ? "client_secret" : value.startsWith(AuthioDefaults.PersonalAccessTokenPrefix) ? "personal_access_token" : void 0;
+  if (!kind)
+    throw new AuthioConfigurationError(
+      `The account credential must start with ${AuthioDefaults.ApiKeyPrefix}, ${AuthioDefaults.ClientSecretPrefix} or ${AuthioDefaults.PersonalAccessTokenPrefix}.`
+    );
+  const exchanged = kind === "client_secret" || kind === "personal_access_token" && options.exchangePersonalAccessToken === true;
+  const clock = options.clock ?? systemClock;
+  const inner = options.fetch ?? globalThis.fetch;
+  const scope = toScopeString(options.scopes);
+  const refreshSkewMs = seconds(options.tokenRefreshSkew, AuthioDefaults.TokenRefreshSkew, "tokenRefreshSkew");
+  let client;
+  let cached;
+  let pending;
+  if (exchanged) {
+    if (kind === "client_secret" && !options.credentialId?.trim())
+      throw new AuthioConfigurationError("A cs_ client secret is exchanged with its credential id: set credentialId.");
+    client = createAuthioClient({
+      ...options,
+      realm: AuthioDefaults.PlatformRealm,
+      clientId: kind === "client_secret" ? toCredentialClientId(options.credentialId) : AuthioDefaults.PlatformClientId,
+      clientSecret: kind === "client_secret" ? value : void 0,
+      tokenEndpointAuthMethod: kind === "client_secret" ? "client_secret_post" : "none"
+    });
+  }
+  const exchange = async (signal) => {
+    if (cached && clock.now() < cached.refreshAt) return cached;
+    pending ??= (async () => {
+      const issuedAt = clock.now();
+      const answer = kind === "client_secret" ? await client.tokens.clientCredentials({ scopes: scope, signal }) : await client.tokens.personalAccessToken({ token: value, scopes: scope, signal });
+      cached = toClientCredentialsToken(answer, issuedAt, refreshSkewMs);
+      return cached;
+    })().finally(() => {
+      pending = void 0;
+    });
+    return pending;
+  };
+  const headers = async (signal) => {
+    if (exchanged) {
+      const token = await exchange(signal);
+      return { authorization: `${token.tokenType} ${token.accessToken}` };
+    }
+    return options.presentAs === "x-api-key" ? { [AuthioDefaults.ApiKeyHeader]: value } : { authorization: `Bearer ${value}` };
+  };
+  const authenticatedFetch = async (input, init) => {
+    const request = new Request(input, init);
+    const body = request.body ? await request.arrayBuffer() : void 0;
+    const idempotent = ["GET", "HEAD", "PUT", "DELETE"].includes(request.method.toUpperCase());
+    const attempt = async () => {
+      const merged = new Headers(request.headers);
+      for (const [name, header] of Object.entries(await headers(request.signal))) merged.set(name, header);
+      return inner(request.url, { method: request.method, headers: merged, body, signal: request.signal, redirect: request.redirect });
+    };
+    let response = await attempt();
+    if (response.status === 401 && exchanged) {
+      cached = void 0;
+      response = await attempt();
+    }
+    if ((response.status === 429 || response.status === 503) && idempotent) {
+      const wait = retryAfterOf(response.headers.get("retry-after") ?? void 0);
+      if (wait !== void 0) {
+        await clock.sleep(wait * 1e3, request.signal);
+        response = await attempt();
+      }
+    }
+    return response;
+  };
+  return {
+    kind,
+    exchanged,
+    headers,
+    invalidate() {
+      cached = void 0;
+    },
+    fetch: authenticatedFetch
+  };
+}
+function toCredentialClientId(credentialId) {
+  const id = credentialId.trim();
+  return id.startsWith(AuthioDefaults.CredentialClientIdPrefix) ? id : `${AuthioDefaults.CredentialClientIdPrefix}${id.replace(/[{}-]/g, "").toLowerCase()}`;
+}
+function parseJson(body) {
+  if (!body?.trim()) return void 0;
+  try {
+    return asRecord(JSON.parse(body));
+  } catch {
+    return void 0;
+  }
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function toNotification(value) {
+  const record = asRecord(value) ?? {};
+  return withoutUndefined2({ message: textOf2(record.message) ?? "", field: textOf2(record.field), code: textOf2(record.code) });
+}
+function headerOf(headers, name) {
+  if (!headers) return void 0;
+  if (typeof headers.get === "function") return headers.get(name) ?? void 0;
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) if (key.toLowerCase() === wanted) return value;
+  return void 0;
+}
+function retryAfterOf(value) {
+  if (!value?.trim()) return void 0;
+  if (/^\d+$/.test(value.trim())) return Number(value.trim());
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, Math.ceil((date - Date.now()) / 1e3));
+}
+function textOf2(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function withoutUndefined2(value) {
+  for (const key of Object.keys(value)) if (value[key] === void 0) delete value[key];
+  return value;
+}
+
 // src/resource-access.ts
 var claimSources = new Map(Object.entries(AuthioResourceAccessClaims).map(([name, source]) => [name.toLowerCase(), source]));
 var AuthioResourceAccess = class _AuthioResourceAccess {
@@ -1050,7 +1873,7 @@ function parseResourceAccess(claims) {
   return roles.length === 0 ? AuthioResourceAccess.empty : new AuthioResourceAccess(roles);
 }
 function parseResourceAccessClaim(source, value) {
-  const root = typeof value === "string" ? parseJson(value) : value;
+  const root = typeof value === "string" ? parseJson2(value) : value;
   if (!isPlainObject(root)) return [];
   const roles = [];
   for (const [name, rolePermissions] of Object.entries(root)) {
@@ -1107,7 +1930,7 @@ function distinctIgnoringCase(values) {
     return true;
   });
 }
-function parseJson(text) {
+function parseJson2(text) {
   if (!text.trim()) return void 0;
   try {
     return JSON.parse(text);
@@ -1194,9 +2017,23 @@ var asAdminResourceEvent = (event) => dataWhen(
   AuthioWebhookEventTypes.AdminResourceDeleted
 );
 var asUserSuspensionEvent = (event) => dataWhen(event, AuthioWebhookEventTypes.UserSuspended, AuthioWebhookEventTypes.UserSuspensionEnded);
+var asAttackDetectedEvent = (event) => dataWhen(event, AuthioWebhookEventTypes.AttackDetected);
+var asCredentialCompromisedEvent = (event) => dataWhen(event, AuthioWebhookEventTypes.CredentialCompromised);
 var asPingEvent = (event) => dataWhen(event, AuthioWebhookEventTypes.Ping);
+var knownEventTypes = new Set(Object.values(AuthioWebhookEventTypes));
+function isKnownWebhookEventType(type) {
+  return knownEventTypes.has(type);
+}
+function readWebhookEventData(event) {
+  return isKnownWebhookEventType(event.type) ? dataWhen(event, event.type) : void 0;
+}
+function toCamelCasedMembers(value) {
+  const result = {};
+  for (const [name, member] of Object.entries(value)) result[name.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase())] = member;
+  return result;
+}
 function dataWhen(event, ...types) {
-  return types.includes(event.type) && event.data !== null && event.data !== void 0 ? event.data : void 0;
+  return types.includes(event.type) && event.data !== null && typeof event.data === "object" && !Array.isArray(event.data) ? toCamelCasedMembers(event.data) : void 0;
 }
 function parseSignatureHeader(header) {
   let timestamp = 0;
@@ -1235,6 +2072,6 @@ function constantTimeEquals(left, right) {
   return difference === 0;
 }
 
-export { AuthioAsymmetricAlgorithms, AuthioClaimTypes, AuthioClientAssertionAlgorithms, AuthioConfigurationError, AuthioContentEncryptionAlgorithms, AuthioDefaults, AuthioDiscoveryError, AuthioError, AuthioGrantTypes, AuthioKeyManagementAlgorithms, AuthioOAuthErrors, AuthioProtocolError, AuthioResourceAccess, AuthioResourceAccessClaims, AuthioScopes, AuthioTokenTypes, AuthioWebhookEventTypes, AuthioWebhookHeaders, asAdminResourceEvent, asKeysRotatedEvent, asLoginEvent, asPingEvent, asTokenReuseDetectedEvent, asTokenRevokedEvent, asUserEvent, asUserLockedOutEvent, asUserSuspensionEvent, computeWebhookSignatureHeader, createAuthioClient, createAuthioDiscoveryClient, createAuthioTokenDecrypter, escapeDataString, isAllowedUrl, isAuthioTokenEncrypted, isWebhookEventOfType, parseResourceAccess, parseResourceAccessClaim, parseWebhookEvent, resolveConnection, resolveIssuer, resourceAccessSourceOf, seconds, systemClock, toBasicAuthorization, toClientCredentialsToken, toScopeString, tryParseWebhookEvent, verifyWebhookSignature };
+export { AuthioAdminError, AuthioAsymmetricAlgorithms, AuthioCallbackError, AuthioCallerKinds, AuthioChecks, AuthioClaimTypes, AuthioClientAssertionAlgorithms, AuthioConfigurationError, AuthioContentEncryptionAlgorithms, AuthioDefaults, AuthioDiscoveryError, AuthioError, AuthioGrantTypes, AuthioHmacAlgorithms, AuthioHmacMinimumSecretBytes, AuthioKeyManagementAlgorithms, AuthioLegacyKeyManagementAlgorithms, AuthioOAuthErrors, AuthioPrompts, AuthioProtocolError, AuthioResourceAccess, AuthioResourceAccessClaims, AuthioScopes, AuthioSupportedContentEncryptionAlgorithms, AuthioTokenEndpointAuthMethods, AuthioTokenTypes, AuthioTokenValidationError, AuthioWebhookEventTypes, AuthioWebhookHeaders, asAdminResourceEvent, asAttackDetectedEvent, asCredentialCompromisedEvent, asKeysRotatedEvent, asLoginEvent, asPingEvent, asTokenReuseDetectedEvent, asTokenRevokedEvent, asUserEvent, asUserLockedOutEvent, asUserSuspensionEvent, computeAuthioTokenHash, computeWebhookSignatureHeader, createAuthioAccountCredential, createAuthioClient, createAuthioDiscoveryClient, createAuthioPkce, createAuthioSigningKeys, createAuthioTokenDecrypter, encryptionKeyFromFile, escapeDataString, isAllowedUrl, isAuthioTokenEncrypted, isKnownWebhookEventType, isWebhookEventOfType, parseAuthioAdminEnvelope, parseAuthioBearerChallenge, parseResourceAccess, parseResourceAccessClaim, parseWebhookEvent, randomValue, readAuthioAdminResponse, readAuthioFrontChannelLogout, readWebhookEventData, requireHmacSecretLength, resolveConnection, resolveIssuer, resourceAccessSourceOf, seconds, systemClock, toBasicAuthorization, toCamelCasedMembers, toClientCredentialsToken, toConnectionExchangeResult, toCredentialClientId, toDevicePollOutcome, toScopeString, toTokenValidationError, tryParseWebhookEvent, verifyAuthioJwt, verifyWebhookSignature, withClientSecret };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map