@hyper.authio/server 0.9.0 → 0.10.1

package/dist/index.d.cts

@@ -34,8 +34,9 @@ interface AuthioUserClaimSettings {
     groupClaims?: readonly string[];
 }
 /**
- * The caller of an API, read from a validated access token or an introspection answer: identity, every form of
- * permission Authio issues, and the raw claims for anything else.
+ * The caller of an API, read from a validated access token, an introspection answer, or both (the token's claims and
+ * those of the answer the token does not carry, as `activeCheck` reads it): identity, every form of permission Authio
+ * issues, and the raw claims for anything else.
  */
 declare class AuthioUser {
     /** `sub`: the person's id, or the credential's for a machine caller. */
@@ -121,7 +122,10 @@ declare class AuthioUser {
     readonly credentialType: string | undefined;
     /** `credential_id`. */
     readonly credentialId: string | undefined;
-    /** 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).
+     */
     readonly claims: Readonly<Record<string, unknown>>;
     /** The access token the user was read from. Not enumerable, so it stays out of logs and JSON. */
     readonly token: string | undefined;
@@ -339,10 +343,15 @@ declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenErro
 /**
  * Whether and how Authio's introspection endpoint takes part in validating a token.
  *
- * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime). Fastest; a revoked token stays
- *   valid until it expires.
- * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`).
- * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key.
+ * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime) and the caller is read from it alone.
+ *   Fastest; a revoked token stays valid until it expires. A lightweight access token carries no roles, permissions,
+ *   plan, profile or email, so it needs one of the modes below.
+ * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`). The caller is read
+ *   from the token, and the introspection answer adds the claims the token does not carry: the answer has every claim
+ *   of the complete token, so a lightweight access token's roles and permissions are read too. A claim the token
+ *   carries keeps the token's value, which its signature vouches for, whatever the answer says.
+ * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key. The
+ *   caller is read from the answer.
  */
 type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
 /**

package/dist/index.d.ts

@@ -34,8 +34,9 @@ interface AuthioUserClaimSettings {
     groupClaims?: readonly string[];
 }
 /**
- * The caller of an API, read from a validated access token or an introspection answer: identity, every form of
- * permission Authio issues, and the raw claims for anything else.
+ * The caller of an API, read from a validated access token, an introspection answer, or both (the token's claims and
+ * those of the answer the token does not carry, as `activeCheck` reads it): identity, every form of permission Authio
+ * issues, and the raw claims for anything else.
  */
 declare class AuthioUser {
     /** `sub`: the person's id, or the credential's for a machine caller. */
@@ -121,7 +122,10 @@ declare class AuthioUser {
     readonly credentialType: string | undefined;
     /** `credential_id`. */
     readonly credentialId: string | undefined;
-    /** 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).
+     */
     readonly claims: Readonly<Record<string, unknown>>;
     /** The access token the user was read from. Not enumerable, so it stays out of logs and JSON. */
     readonly token: string | undefined;
@@ -339,10 +343,15 @@ declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenErro
 /**
  * Whether and how Authio's introspection endpoint takes part in validating a token.
  *
- * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime). Fastest; a revoked token stays
- *   valid until it expires.
- * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`).
- * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key.
+ * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime) and the caller is read from it alone.
+ *   Fastest; a revoked token stays valid until it expires. A lightweight access token carries no roles, permissions,
+ *   plan, profile or email, so it needs one of the modes below.
+ * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`). The caller is read
+ *   from the token, and the introspection answer adds the claims the token does not carry: the answer has every claim
+ *   of the complete token, so a lightweight access token's roles and permissions are read too. A claim the token
+ *   carries keeps the token's value, which its signature vouches for, whatever the answer says.
+ * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key. The
+ *   caller is read from the answer.
  */
 type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
 /**

package/dist/index.js

@@ -87,7 +87,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;
   /**
@@ -655,8 +658,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);
@@ -668,6 +672,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;