@udibo/oauth2 0.4.0 → 0.5.0

package/esm/server/grants/refresh-token.js

@@ -40,8 +40,9 @@ export class RefreshTokenGrant extends AbstractGrant {
      * authorization.
      *
      * @throws {InvalidRequestError} If `refresh_token` is missing.
-     * @throws {InvalidGrantError} If the refresh token is unknown or expired, or
-     * its family has outlived the absolute cap.
+     * @throws {InvalidGrantError} If the refresh token is unknown or expired, its
+     * family has outlived the absolute cap, or a concurrent exchange already
+     * claimed it.
      * @throws {InvalidClientError} If the token was issued to another client.
      * @throws {InvalidScopeError} If the requested scope exceeds the original grant.
      */
@@ -98,7 +99,7 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (familyExpiresAt && familyExpiresAt.getTime() <= Date.now()) {
             throw new InvalidGrantError("refresh_token family expired");
         }
-        const nextToken = await this.generateToken(client, user, nextScope, tokenService, currentToken.authenticationContext);
+        const nextToken = await this.generateToken(client, user, nextScope, tokenService, currentToken.authenticationContext, familyExpiresAt);
         const nextRefreshToken = "refreshToken" in nextToken
             ? nextToken
             : {

package/esm/server/introspection-token-reader.d.ts

@@ -46,10 +46,13 @@ export interface IntrospectionTokenReaderOptions<Client extends ClientInterface,
      * `undefined` when the token doesn't represent a user. Omit entirely if
      * your app never reads user info off the token.
      *
-     * A machine token (client credentials) carries no `sub`, so `data.sub` is
-     * present only when there is a resource owner — `data.sub ? {…} : undefined`
-     * is the whole discriminator, and a client-credentials caller resolves to no
-     * user.
+     * This package's authorization server sets `sub` from its `subjectOf`
+     * option (the user's `id` by default — the same value its id_token and
+     * UserInfo carry) and omits it for a token with no user, whatever its
+     * `introspectionClaims` hook returns, so `data.sub` is present only when
+     * there is a resource owner and `data.sub ? {…} : undefined` is the whole
+     * discriminator. Another authorization server may set `sub` to the client
+     * id for a machine token; check how yours answers.
      *
      * May be async — return a promise to enrich from a DB lookup or the
      * authorization server's OIDC UserInfo endpoint, using `data.sub` as
@@ -81,6 +84,11 @@ export interface IntrospectionTokenReaderOptions<Client extends ClientInterface,
  * types via the {@linkcode IntrospectionTokenReaderOptions.getClient} and
  * {@linkcode IntrospectionTokenReaderOptions.getUser} mappers.
  *
+ * The reader does not check `aud` or `iss`: any token the endpoint reports
+ * active with a bearer `token_type` is accepted. When one authorization server
+ * issues tokens for several APIs, check the audience yourself (it is on
+ * {@linkcode Token.claims}) or have the endpoint scope its answers.
+ *
  * @example
  * ```ts
  * import {
@@ -137,9 +145,10 @@ export declare class IntrospectionTokenReader<Client extends ClientInterface, Us
      *   returns a 5xx — a down authorization server must be distinguishable from
      *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
      *   collapsed into it.
-     * @throws {ServerError} If the endpoint returns a 4xx (e.g. the reader's own
-     *   introspection credentials are rejected) — a misconfiguration, not a
-     *   verdict on the caller's token.
+     * @throws {ServerError} If the endpoint returns any other non-2xx status
+     *   (e.g. the reader's own introspection credentials are rejected) or a body
+     *   that is not JSON — a misconfiguration, not a verdict on the caller's
+     *   token.
      *
      * An active response is only accepted when its `token_type` names a bearer
      * token. RFC 7662 answers for refresh tokens too, and a refresh token's

package/esm/server/introspection-token-reader.js

@@ -22,6 +22,11 @@ import { encodeBasicAuth } from "../utils/basic-auth.js";
  * types via the {@linkcode IntrospectionTokenReaderOptions.getClient} and
  * {@linkcode IntrospectionTokenReaderOptions.getUser} mappers.
  *
+ * The reader does not check `aud` or `iss`: any token the endpoint reports
+ * active with a bearer `token_type` is accepted. When one authorization server
+ * issues tokens for several APIs, check the audience yourself (it is on
+ * {@linkcode Token.claims}) or have the endpoint scope its answers.
+ *
  * @example
  * ```ts
  * import {
@@ -87,9 +92,10 @@ export class IntrospectionTokenReader {
      *   returns a 5xx — a down authorization server must be distinguishable from
      *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
      *   collapsed into it.
-     * @throws {ServerError} If the endpoint returns a 4xx (e.g. the reader's own
-     *   introspection credentials are rejected) — a misconfiguration, not a
-     *   verdict on the caller's token.
+     * @throws {ServerError} If the endpoint returns any other non-2xx status
+     *   (e.g. the reader's own introspection credentials are rejected) or a body
+     *   that is not JSON — a misconfiguration, not a verdict on the caller's
+     *   token.
      *
      * An active response is only accepted when its `token_type` names a bearer
      * token. RFC 7662 answers for refresh tokens too, and a refresh token's

package/esm/server/jwks-token-reader.d.ts

@@ -255,9 +255,9 @@ export declare class JwksTokenReader<Client extends ClientInterface, User, S ext
      *   available — a down issuer must be distinguishable from a genuinely
      *   invalid token, not collapsed into it. Once keys are cached, a failed
      *   refresh is absorbed and the cached keys keep serving.
-     * @throws {ServerError} If the JWKS endpoint returns a 4xx or a body that
-     *   is not a JWKS, or discovery reports no `jwks_uri` — a
-     *   misconfiguration, not a verdict on the caller's token.
+     * @throws {ServerError} If, with no keys cached, the JWKS endpoint returns
+     *   a 4xx or a body that is not a JWKS, or discovery reports no `jwks_uri`
+     *   — a misconfiguration, not a verdict on the caller's token.
      */
     getToken(accessToken: string): Promise<Token<Client, User, S> | undefined>;
 }

package/esm/server/jwks-token-reader.js

@@ -276,9 +276,9 @@ export class JwksTokenReader {
      *   available — a down issuer must be distinguishable from a genuinely
      *   invalid token, not collapsed into it. Once keys are cached, a failed
      *   refresh is absorbed and the cached keys keep serving.
-     * @throws {ServerError} If the JWKS endpoint returns a 4xx or a body that
-     *   is not a JWKS, or discovery reports no `jwks_uri` — a
-     *   misconfiguration, not a verdict on the caller's token.
+     * @throws {ServerError} If, with no keys cached, the JWKS endpoint returns
+     *   a 4xx or a body that is not a JWKS, or discovery reports no `jwks_uri`
+     *   — a misconfiguration, not a verdict on the caller's token.
      */
     async getToken(accessToken) {
         const parsed = parseJws(accessToken);