@hyper.authio/server 0.7.0 → 0.8.0

package/README.md

@@ -34,12 +34,13 @@ try {
 | `resource` | | The API's own resource identifier (RFC 8707); added to `audiences` and used for RFC 9728. |
 | `resourceMetadata` | off | `true` (or the URL) adds `resource_metadata="{origin}/.well-known/oauth-protected-resource{path}"` to `401` challenges (RFC 9728). |
 | `requiredScopes` | | Scopes every request must carry (all); `authioBearer` answers `403 insufficient_scope`. |
-| `clientEncryptionKey`, `clientEncryptionKeyPath` | | Decrypts access tokens Authio encrypts to this key (RSA-OAEP, RSA-OAEP-256) and validates them locally. RSA1_5 is refused (`legacy_algorithm`), even with `allowLegacyEncryptionAlgorithms`. |
+| `clientEncryptionKey`, `clientEncryptionKeyPath` | | Decrypts access tokens Authio encrypts to this key and validates them locally. Without it nothing is decrypted. RSA1_5 is refused (`legacy_algorithm`), even with `allowLegacyEncryptionAlgorithms`. |
+| `encryptionAlgorithms`, `encryptionMethods` | `RSA-OAEP`, `RSA-OAEP-256`; the CBC-HS methods | The JWE `alg` and `enc` accepted, as registered in Authio (AES-GCM may be listed; RSA1_5 cannot: Node cannot decrypt it). |
 | `introspection` | `none` | `none`: local JWT validation. `activeCheck`: then confirmed active by introspection (cached per `jti`), so a revoked token, an ended session or a suspension is refused before the token expires. `introspectionOnly`: introspection alone, for opaque tokens (or encrypted ones without the key). |
-| `client` | | The API's confidential client, needed by introspection: an `AuthioClient` or `{ clientId, clientSecret }` (or a private key). It must be the resource server's introspection client. |
+| `client` | | The API's confidential client, needed by introspection: an `AuthioClient` or `{ clientId, clientSecret }` (or a private key), with `tokenEndpointAuthMethod` as the client is registered. It must be the resource server's introspection client. |
 | `introspectionCacheDuration` | 30 s | Never past the token's expiry; only active answers are kept. |
 | `clockSkew` | 30 s | |
-| `validAlgorithms` | RS*, PS*, ES* | |
+| `accessTokenSignedResponseAlg` | RS*, PS*, ES* (never HS*) | The algorithm (or several) access tokens are signed with, as the client is registered in Authio. HS256/384/512 are verified with the `clientSecret` of `client: { clientId, clientSecret }` (at least 32, 48 or 64 bytes). |
 | `rejectNonAccessTokens` | `true` | Refuses a token whose `typ` is not `Bearer` (an ID token, for one). |
 | `roleClaims` | `["role"]` | Claims holding flat role names (a Role claim mapper). |
 | `groupClaims` | `["groups"]` | Claims holding group names (a Group claim mapper). |
@@ -60,6 +61,26 @@ const path = protectedResourceMetadataPath(verifier.resource!); // /.well-known/
 const document = createProtectedResourceMetadata({ issuer, resource: verifier.resource!, scopesSupported: ["orders:read"] });
 ```
 
+### Access tokens signed with the client secret (HS*)
+
+Authio signs a client's access tokens with the algorithm of its access token setting. When that is HS256, HS384 or
+HS512, the signature is made with the client secret: only who holds the secret validates the token locally, so that is
+the client's own API.
+
+```ts
+const verifier = createAuthioVerifier({
+  issuer,
+  audiences: "storefront",
+  accessTokenSignedResponseAlg: "HS256",
+  client: { clientId: "storefront", clientSecret: process.env.AUTHIO_CLIENT_SECRET! }, // 32+ bytes for HS256
+});
+```
+
+Third-party APIs never get the secret: they validate such tokens with introspection (`introspection:
+"introspectionOnly"` and their own introspection client). Without `accessTokenSignedResponseAlg`, an HS* token is
+refused (`invalid_algorithm`) with a description naming both ways. `authioBearer` and the MCP packages take the same
+option.
+
 ## The caller
 
 `AuthioUser` reads every form of permission, the same way from a JWT or an introspection answer:

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var client = require('@hyper.authio/client');
+var jose = require('jose');
 
 // src/user.ts
 var accessTokenTypes = /* @__PURE__ */ new Set(["bearer", "api_key"]);
@@ -553,7 +554,8 @@ var AuthioBearerErrorDescriptions = {
   Unconfirmed: "Authio could not be reached to confirm that the token is active.",
   Empty: "The token is empty.",
   Encrypted: "The token is encrypted; set clientEncryptionKey to decrypt it, or validate it with introspection ('introspectionOnly').",
-  SigningKeysUnavailable: "Authio could not be reached to read its signing keys."
+  SigningKeysUnavailable: "Authio could not be reached to read its signing keys.",
+  Symmetric: "The token is signed with the client's secret (HS*): set accessTokenSignedResponseAlg and the client's clientSecret to validate it locally, or validate it with introspection ('introspectionOnly')."
 };
 var maxCachedAnswers = 1e4;
 function createAuthioVerifier(options) {
@@ -573,7 +575,9 @@ function createAuthioVerifier(options) {
   const resourceMetadataUrl = resolveResourceMetadata(options.resourceMetadata, resource);
   const cacheDurationMs = client.seconds(options.introspectionCacheDuration, 30, "introspectionCacheDuration");
   const clockSkew = client.seconds(options.clockSkew, 30, "clockSkew") / 1e3;
-  const algorithms = options.validAlgorithms && options.validAlgorithms.length > 0 ? [...options.validAlgorithms] : void 0;
+  const algorithms = resolveAccessTokenAlgorithms(options.accessTokenSignedResponseAlg);
+  const symmetric = algorithms?.filter((algorithm) => client.AuthioHmacAlgorithms.includes(algorithm)) ?? [];
+  const clientSecret = symmetric.length > 0 ? resolveClientSecret(options, symmetric) : void 0;
   const rejectNonAccessTokens = options.rejectNonAccessTokens ?? true;
   const claimSettings = { roleClaims: options.roleClaims, groupClaims: options.groupClaims };
   const cache = /* @__PURE__ */ new Map();
@@ -581,7 +585,9 @@ function createAuthioVerifier(options) {
   const encryptionKey = options.clientEncryptionKey ?? (options.clientEncryptionKeyPath ? client.encryptionKeyFromFile(options.clientEncryptionKeyPath) : void 0);
   const decrypt = encryptionKey === void 0 ? void 0 : client.createAuthioTokenDecrypter(encryptionKey, {
     setting: options.clientEncryptionKey === void 0 ? "clientEncryptionKeyPath" : "clientEncryptionKey",
-    allowLegacyEncryptionAlgorithms: options.allowLegacyEncryptionAlgorithms
+    allowLegacyEncryptionAlgorithms: options.allowLegacyEncryptionAlgorithms,
+    encryptionAlgorithms: options.encryptionAlgorithms,
+    encryptionMethods: options.encryptionMethods
   });
   const requiredScopes = Object.freeze([...new Set((options.requiredScopes ?? []).filter((scope) => scope?.trim()))]);
   const introspect = async (token, key, signal) => {
@@ -611,7 +617,7 @@ function createAuthioVerifier(options) {
     }
     let keySet;
     try {
-      keySet = await signingKeys(signal);
+      keySet = client.withClientSecret(await signingKeys(signal), clientSecret);
     } catch (error) {
       throw new AuthioBearerError(AuthioBearerErrorDescriptions.SigningKeysUnavailable, { cause: error, reason: "signing_keys_unavailable" });
     }
@@ -625,6 +631,8 @@ function createAuthioVerifier(options) {
         now: connection.clock.now()
       }));
     } catch (error) {
+      if (error instanceof client.AuthioTokenValidationError && error.reason === "invalid_algorithm" && symmetric.length === 0 && isSymmetricToken(signed))
+        throw new AuthioBearerError(AuthioBearerErrorDescriptions.Symmetric, { cause: error, reason: error.reason });
       if (error instanceof client.AuthioTokenValidationError) throw new AuthioBearerError(error.message, { cause: error, reason: error.reason });
       throw error;
     }
@@ -706,6 +714,35 @@ function resolveResourceMetadata(setting, resource) {
     throw new client.AuthioConfigurationError("resourceMetadata: true needs the API's resource identifier: set options.resource, or pass the metadata URL.");
   return protectedResourceMetadataUrl(resource);
 }
+function resolveAccessTokenAlgorithms(setting) {
+  const algorithms = [...new Set((typeof setting === "string" ? [setting] : [...setting ?? []]).map((algorithm) => algorithm.trim()).filter(Boolean))];
+  const known = [...client.AuthioAsymmetricAlgorithms, ...client.AuthioHmacAlgorithms];
+  for (const algorithm of algorithms)
+    if (!known.includes(algorithm))
+      throw new client.AuthioConfigurationError(`The Authio accessTokenSignedResponseAlg '${algorithm}' is not one of ${known.join(", ")}.`);
+  return algorithms.length > 0 ? algorithms : void 0;
+}
+function resolveClientSecret(options, symmetric) {
+  const given = options.client;
+  const source = given && !isClient(given) ? given.clientSecret : void 0;
+  if (!source)
+    throw new client.AuthioConfigurationError(
+      `accessTokenSignedResponseAlg ${symmetric.join(", ")} is verified with the client secret: pass options.client as { clientId, clientSecret } (an AuthioClient does not expose its secret).`
+    );
+  if (typeof source === "string") for (const algorithm of symmetric) client.requireHmacSecretLength(algorithm, new TextEncoder().encode(source).length);
+  return async () => {
+    const value = typeof source === "function" ? await source() : source;
+    if (typeof value !== "string" || !value) throw new client.AuthioConfigurationError("The Authio clientSecret function returned no secret.");
+    return value;
+  };
+}
+function isSymmetricToken(token) {
+  try {
+    return client.AuthioHmacAlgorithms.includes(String(jose.decodeProtectedHeader(token).alg));
+  } catch {
+    return false;
+  }
+}
 function resolveClient(options) {
   const given = options.client;
   if (!given) return void 0;