@hyper.authio/server 0.8.1 → 0.10.0

package/README.md

@@ -36,12 +36,12 @@ try {
 | `requiredScopes` | | Scopes every request must carry (all); `authioBearer` answers `403 insufficient_scope`. |
 | `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). |
+| `introspection` | `none` | `none`: local JWT validation; the caller is read from the token alone. `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; the caller is read from the token, plus the claims of the answer the token does not carry. `introspectionOnly`: introspection alone, for opaque (`Reference`) tokens (or encrypted ones without the key); the caller is read from the answer. A `Lightweight` access token needs `activeCheck` or `introspectionOnly` (see below). |
 | `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 | |
 | `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). |
 
@@ -51,6 +51,31 @@ A refusal is an `AuthioBearerError` whose `wwwAuthenticate` is `Bearer` when the
 `not_access_token`, `reference_token`, `decryption_failed`, …, and `inactive` / `unconfirmed` for introspection). A
 token addressed elsewhere is described with the audience the API accepts; introspection failures fail closed.
 
+### Lightweight and reference access tokens
+
+Authio hands out a client's access tokens in the form its access token format setting names:
+
+| Format | The token | Validate it with |
+| --- | --- | --- |
+| `Jwt` | A self-contained JWT with every claim. | Any mode. |
+| `Lightweight` | A JWT with only the identity and session claims (`iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`, `typ`, `client_id`, `azp`, `scope`, `sid`, `auth_time`, `acr`, `amr`, `idp`, `act`, `delegation_id`, `session_client`, `org_id`, `org_alias`). The `*_resource_access` roles and permissions, `subscription`, the profile and the email are only in the introspection answer. | `activeCheck` or `introspectionOnly`, which read the caller with the answer's claims, so `roles`, `permissions`, `kind` and `email` are complete. With `none` the caller has only what the token carries: no role or permission, and a consumer reads as a `client`. |
+| `Reference` | An opaque handle, no JWT (refused locally as `reference_token`). | `introspectionOnly`. |
+
+```ts
+const verifier = createAuthioVerifier({
+  issuer,
+  resource: "https://orders.example.com",
+  introspection: "activeCheck", // the client's access token format is Lightweight
+  client: { clientId: "orders-api", clientSecret: process.env.AUTHIO_CLIENT_SECRET! },
+});
+```
+
+Nothing tells a lightweight token apart from a full one that carries no role (a person without roles has no
+`*_resource_access` either), so the verifier never guesses: the mode decides. The introspection answer is cached per
+`jti` for `introspectionCacheDuration`, so `activeCheck` asks Authio once per token and cache period. The answer only
+adds claims: one the token carries keeps the token's value, which its signature vouches for (Authio answers a single
+`aud`, and `client_id` for `azp`).
+
 ### Protected resource metadata (RFC 9728)
 
 ```ts
@@ -83,7 +108,7 @@ option.
 
 ## The caller
 
-`AuthioUser` reads every form of permission, the same way from a JWT or an introspection answer:
+`AuthioUser` reads every form of permission, the same way from a JWT, an introspection answer or both (`activeCheck`):
 
 ```ts
 user.subject; user.clientId; user.scopes;
@@ -134,6 +159,9 @@ if (refusal) {
 | 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

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;
@@ -89,7 +89,10 @@ var AuthioUser = class _AuthioUser {
   credentialType;
   /** `credential_id`. */
   credentialId;
-  /** Every claim, as the token or the introspection answer carried it. */
+  /**
+   * Every claim, as the token or the introspection answer carried it (with `activeCheck`, the token's, plus the
+   * answer's the token does not carry).
+   */
   claims;
   flatRoles;
   /**
@@ -104,7 +107,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 +280,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 {
@@ -638,13 +642,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 });
@@ -654,8 +660,9 @@ function createAuthioVerifier(options) {
     const type = typeof payload.typ === "string" ? payload.typ : void 0;
     if (rejectNonAccessTokens && type !== void 0 && type.toLowerCase() !== "bearer")
       throw new AuthioBearerError(`Only access tokens are accepted; this token's typ is '${type}'.`, { reason: "not_access_token" });
-    if (introspection === "activeCheck") await confirmActive(token, payload, signal);
-    return new AuthioUser(payload, claimSettings, token);
+    if (introspection !== "activeCheck") return new AuthioUser(payload, claimSettings, token);
+    const answer = await confirmActive(token, payload, signal);
+    return new AuthioUser({ ...claimsOfIntrospection(answer), ...payload }, claimSettings, token);
   };
   const confirmActive = async (token, payload, signal) => {
     const key = payload.jti ? `jti:${payload.jti}` : await keyForToken(token);
@@ -667,6 +674,7 @@ function createAuthioVerifier(options) {
       throw new AuthioBearerError(AuthioBearerErrorDescriptions.Unconfirmed, { cause: error, reason: "unconfirmed" });
     }
     if (!result) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Inactive, { reason: "inactive" });
+    return result;
   };
   const verifyByIntrospection = async (token, signal) => {
     let result;