@hyper.authio/server 0.9.0 → 0.10.1

package/README.md

@@ -36,7 +36,7 @@ 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 | |
@@ -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, whatever the answer says
+(it names `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;

package/dist/index.cjs

@@ -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;
   /**
@@ -657,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);
@@ -670,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;