@hyper.authio/server 0.8.0 → 0.9.0

package/README.md

@@ -41,7 +41,7 @@ try {
 | `introspectionCacheDuration` | 30 s | Never past the token's expiry; only active answers are kept. |
 | `clockSkew` | 30 s | |
 | `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). |
+| `rejectNonAccessTokens` | `true` | Refuses a token whose `typ` claim is not `Bearer` (an ID token, for one). The header `typ` must be `at+jwt` (RFC 9068 §4) regardless. |
 | `roleClaims` | `["role"]` | Claims holding flat role names (a Role claim mapper). |
 | `groupClaims` | `["groups"]` | Claims holding group names (a Group claim mapper). |
 
@@ -120,11 +120,28 @@ const refusal = authorize(user, requirePermission("orders", "write"), anyOf(requ
 
 if (refusal) {
   const error = new AuthioForbiddenError(refusal);
-  // 403, with error.wwwAuthenticate when the refusal is about scopes (insufficient_scope) or the sign-in
-  // (insufficient_user_authentication); toProblemDetails(error) for an RFC 9457 body.
+  // error.status: 401 when the refusal asks for a stronger or more recent sign-in (insufficient_user_authentication,
+  // RFC 9470 §3), 403 otherwise; error.wwwAuthenticate for scope (insufficient_scope) and sign-in refusals;
+  // toProblemDetails(error) for an RFC 9457 body with the same status.
 }
 ```
 
+| Refusal | Status | `WWW-Authenticate` |
+| --- | --- | --- |
+| No token | `401` | `Bearer` (no `error`, RFC 6750 §3.1) |
+| Token not valid | `401` | `Bearer error="invalid_token", error_description="…"` |
+| Missing scope | `403` | `Bearer error="insufficient_scope", error_description="…", scope="…"` |
+| Sign-in too weak or too old (step-up) | `401` | `Bearer error="insufficient_user_authentication", error_description="…", acr_values="…", max_age=…` |
+| Missing role, permission, group, claim, organization, client or caller kind | `403` | none |
+
+When several rules fail at once, a step-up is asked for only if every failing rule is a step-up: a missing scope, role
+or permission, which no stronger sign-in fixes, answers `403` (with `insufficient_scope` for a scope) and no step-up.
+
+`resource_metadata` (RFC 9728 §5.1) is added to every `401` when the verifier publishes the protected resource
+metadata (`resourceMetadata`): the verifier's own refusals carry it, and `new AuthioForbiddenError(refusal, {
+resourceMetadata: verifier.resourceMetadataUrl })` (or `withResourceMetadata`) adds it to a step-up; the guards of
+`@hyper.authio/express` do it for you. The table is `conformance/challenges.json`, which every Authio library runs.
+
 Rules: `requireScope`, `requireRole`, `requirePermission`, `requireGroup`, `requireClaim`, `requireOrganization`,
 `requireAuthenticationLevel`, `requireAuthenticationMethod`, `requireRecentAuthentication`, `requireCallerKind`,
 `requireClient`, combined with `allOf` and `anyOf`. `authorize` checks every rule and joins their messages.
@@ -132,8 +149,9 @@ Rules: `requireScope`, `requireRole`, `requirePermission`, `requireGroup`, `requ
 **Step-up (RFC 9470)**: `requireAuthenticationLevel(2, { maxAge: 300 })`, `requireAuthenticationMethod("otp")` and
 `requireRecentAuthentication(300)` refuse with `insufficient_user_authentication`, `acrValues` (the level asked for;
 `2` for `mfa`/`otp`/`mca`, `3` for `swk`/`hwk`) and `maxAge`, so the challenge reads
-`Bearer error="insufficient_user_authentication", error_description="…", acr_values="2", max_age=300`. A client
-answers it with `createStepUpAuthorizationUrl` from `@hyper.authio/client`.
+`Bearer error="insufficient_user_authentication", error_description="…", acr_values="2", max_age=300`, answered with
+`401` (RFC 9470 §3; `403` before 0.8.1). A client answers it with `createStepUpAuthorizationUrl` from
+`@hyper.authio/client`.
 
 ## Webhooks
 

package/dist/index.cjs

@@ -43,7 +43,7 @@ var AuthioUser = class _AuthioUser {
   actorChain;
   /** `auth_time`, in seconds since the epoch. */
   authTime;
-  /** The client the token was issued to (`azp`, else `client_id`). */
+  /** The client the token was issued to (`client_id`, RFC 9068 §2.2, else `azp`). */
   clientId;
   /** `sid`. */
   sessionId;
@@ -104,7 +104,7 @@ var AuthioUser = class _AuthioUser {
     const text = (name) => typeof claims[name] === "string" && claims[name] ? claims[name] : void 0;
     this.claims = Object.freeze({ ...claims });
     this.subject = text(client.AuthioClaimTypes.Subject) ?? "";
-    this.clientId = text(client.AuthioClaimTypes.AuthorizedParty) ?? text(client.AuthioClaimTypes.ClientId);
+    this.clientId = text(client.AuthioClaimTypes.ClientId) ?? text(client.AuthioClaimTypes.AuthorizedParty);
     this.sessionId = text(client.AuthioClaimTypes.SessionId);
     this.tokenId = text(client.AuthioClaimTypes.JwtId);
     this.audiences = Object.freeze(distinct(valuesOf(claims[client.AuthioClaimTypes.Audience])));
@@ -277,8 +277,9 @@ function distinctIgnoringCase(values) {
 function authorize(user, ...rules) {
   const failures = rules.map((rule) => rule.check(user)).filter((failure) => failure !== void 0);
   if (failures.length === 0) return void 0;
-  const stepUps = failures.filter((failure) => failure.error === "insufficient_user_authentication");
-  const bearer = stepUps[0] ?? failures.find((failure) => failure.error);
+  const others = failures.filter((failure) => failure.error !== "insufficient_user_authentication");
+  const stepUps = others.length === 0 ? failures : [];
+  const bearer = stepUps[0] ?? others.find((failure) => failure.error);
   const acrValues = strongestAcr(stepUps.map((failure) => failure.acrValues));
   const maxAges = stepUps.map((failure) => failure.maxAge).filter((value) => value !== void 0);
   return {
@@ -471,16 +472,30 @@ var AuthioBearerError = class _AuthioBearerError extends client.AuthioError {
     return parameters.length === 0 ? "Bearer" : `Bearer ${parameters.join(", ")}`;
   }
 };
-var AuthioForbiddenError = class extends client.AuthioError {
-  status = 403;
+var AuthioForbiddenError = class _AuthioForbiddenError extends client.AuthioError {
+  /** `401` for a step-up (`insufficient_user_authentication`), `403` otherwise. */
+  status;
   failure;
-  constructor(failure) {
+  /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` with a step-up `401`. */
+  resourceMetadata;
+  constructor(failure, options = {}) {
     super(failure.message);
     this.failure = failure;
+    this.status = failure.error === "insufficient_user_authentication" ? 401 : 403;
+    this.resourceMetadata = options.resourceMetadata;
   }
-  /** The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. */
+  /** The same refusal, pointing at the API's protected resource metadata. */
+  withResourceMetadata(resourceMetadata) {
+    if (!resourceMetadata || resourceMetadata === this.resourceMetadata) return this;
+    return new _AuthioForbiddenError(this.failure, { resourceMetadata });
+  }
+  /**
+   * The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. A step-up `401`
+   * carries `resource_metadata` when `resourceMetadata` is set.
+   */
   get wwwAuthenticate() {
-    return toForbiddenChallenge(this.failure);
+    const challenge = toForbiddenChallenge(this.failure);
+    return challenge && this.status === 401 && this.resourceMetadata ? `${challenge}, resource_metadata="${escapeQuoted(this.resourceMetadata)}"` : challenge;
   }
 };
 function toForbiddenChallenge(failure) {
@@ -494,15 +509,15 @@ function toForbiddenChallenge(failure) {
 function toProblemDetails(error) {
   if (error instanceof AuthioBearerError)
     return {
-      type: "https://tools.ietf.org/html/rfc9110#section-15.5.2",
+      type: unauthorizedType,
       title: "Unauthorized",
       status: 401,
       detail: "A valid Authio access token is required."
     };
   return {
-    type: "https://tools.ietf.org/html/rfc9110#section-15.5.4",
-    title: "Forbidden",
-    status: 403,
+    type: error.status === 401 ? unauthorizedType : "https://tools.ietf.org/html/rfc9110#section-15.5.4",
+    title: error.status === 401 ? "Unauthorized" : "Forbidden",
+    status: error.status,
     detail: error.failure.message || "The caller is not allowed to access this resource.",
     ...error.failure.error ? { error: error.failure.error } : {},
     ...error.failure.scope ? { scope: error.failure.scope } : {},
@@ -510,6 +525,7 @@ function toProblemDetails(error) {
     ...error.failure.maxAge !== void 0 ? { max_age: error.failure.maxAge } : {}
   };
 }
+var unauthorizedType = "https://tools.ietf.org/html/rfc9110#section-15.5.2";
 function toHeaderText(text) {
   return [...text].map((character) => character >= " " && character <= "~" && character !== '"' && character !== "\\" ? character : "?").join("");
 }
@@ -623,13 +639,15 @@ function createAuthioVerifier(options) {
     }
     let payload;
     try {
-      ({ payload } = await client.verifyAuthioJwt(signed, keySet, {
+      let header;
+      ({ payload, header } = await client.verifyAuthioJwt(signed, keySet, {
         issuer: connection.issuer,
         audiences,
         algorithms,
         clockSkew,
         now: connection.clock.now()
       }));
+      client.requireAccessTokenType(header);
     } 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 });
@@ -905,13 +923,16 @@ function createOnBehalfOf(options) {
         };
         const token = await getToken(subject, request.signal);
         const response = await attempt(token);
-        if (response.status !== 401) return response;
+        if (response.status !== 401 || isStepUpChallenge(response)) return response;
         await invalidate(subject, token.accessToken);
         return attempt(await getToken(subject, request.signal));
       };
     }
   };
 }
+function isStepUpChallenge(response) {
+  return client.parseAuthioBearerChallenge(response.headers.get("www-authenticate"))?.error === client.AuthioOAuthErrors.InsufficientUserAuthentication;
+}
 function tokenOf(subject) {
   if (!subject) return void 0;
   return typeof subject === "string" ? subject : subject.token;