@idp.global/sdk 19.3.0 → 19.5.0

package/ts_browser/index.ts

@@ -1,3 +1,4 @@
 export * from './classes.idpclient.js';
 export * from './classes.idprequests.js';
 export * from './secret-delivery.js';
+export * from './classes.relyingpartybearerclient.js';

package/ts_relyingparty/classes.authorityobserver.ts

@@ -1,6 +1,6 @@
 import { AuthorityTokenError } from './classes.errors.js';
 import { OidcAuthorityUnavailableError, type IOidcProvider } from './classes.idpoidcprovider.js';
-import type { IAuthorityTokenSource } from './interfaces.js';
+import type { IAuthorityTokenSource, IProviderToken } from './interfaces.js';
 
 /** Why an observation refused: no membership at all, or roles the application maps to nothing. */
 export type TAuthorityRefusalReason = 'idp_membership_absent' | 'idp_roles_unmapped';
@@ -58,6 +58,8 @@ export interface IAuthorityObserverOptions<TGrant> {
 const DEFAULT_MAX_ENTRIES = 2_000;
 /** how much room an eviction makes, so it does not run on every insert */
 const EVICTION_HEADROOM = 0.1;
+/** a session's token is rotated for an inactive answer at most once in this long */
+export const AUTHORITY_FORCED_REFRESH_INTERVAL_MS = 60_000;
 
 interface ICachedObservation<TGrant> {
   outcome: 'active' | 'inactive';
@@ -72,6 +74,14 @@ interface ICachedObservation<TGrant> {
   reported: boolean;
 }
 
+/** The one rotation of a session's token that an inactive answer forced. */
+interface IForcedRefresh {
+  startedAt: number;
+  /** where its start falls among the observer's inactive answers */
+  sequence: number;
+  token: Promise<IProviderToken>;
+}
+
 const assertTtl = (valueArg: number, labelArg: string): number => {
   if (!Number.isSafeInteger(valueArg) || valueArg < 0) {
     throw new Error(labelArg + ' must be a non-negative integer of milliseconds');
@@ -89,11 +99,28 @@ const assertTtl = (valueArg: number, labelArg: string): number => {
  * every attempt while the provider is unreachable. A session that is forgotten
  * while its observation is in flight never stores a positive answer. Nothing
  * runs on a timer: the cache is pruned when it is written to.
+ *
+ * idp.global answers inactive both for a login that ended and for a
+ * membership that is gone, so an inactive answer rotates the session's token
+ * (`rejectedAccessToken`) before it counts. A refused rotation is the ended
+ * login: it throws `authority_login_required` and stores nothing. Only an
+ * inactive answer on a token from a rotation that started after the
+ * observation's own inactive answer is a refusal (`idp_membership_absent`). A session's token is
+ * rotated so at most once per `AUTHORITY_FORCED_REFRESH_INTERVAL_MS`. An inactive
+ * answer that no rotation followed — it came within that time of the last
+ * one, the rotation started before it, or the source did not mark the token
+ * as its own rotation — confirms nothing: it throws `authority_unavailable`
+ * and stores nothing, and after the interval the next one rotates and
+ * decides. One monotonic sequence orders answers and rotation starts, so no
+ * token is compared with another and no clock with another's.
  */
 export class AuthorityObserver<TGrant> {
   readonly #cache = new Map<string, ICachedObservation<TGrant>>();
   readonly #inFlight = new Map<string, Promise<ICachedObservation<TGrant>>>();
   readonly #forgotten = new Set<string>();
+  readonly #forcedRefreshes = new Map<string, IForcedRefresh>();
+  /** counts inactive answers and forced rotation starts, in the order they happen */
+  #sequence = 0;
   readonly #provider: IOidcProvider;
   readonly #tokens: IAuthorityTokenSource;
   readonly #project: (rolesArg: readonly string[]) => TGrant | undefined;
@@ -149,6 +176,7 @@ export class AuthorityObserver<TGrant> {
 
   /** Drops every observation of a session; wire it to the session layer's `onSessionEnded`. */
   public forgetSession(sessionIdArg: string): void {
+    this.#forcedRefreshes.delete(sessionIdArg);
     const prefix = `${sessionIdArg} `;
     for (const key of this.#cache.keys()) {
       if (key.startsWith(prefix)) {
@@ -188,18 +216,15 @@ export class AuthorityObserver<TGrant> {
     optionsArg: { loginSessionId: string; principalId: string; idpOrganizationId: string },
   ): Promise<ICachedObservation<TGrant>> {
     const token = await this.#tokens.liveProviderToken(optionsArg.loginSessionId, optionsArg.principalId);
-    let answer: Awaited<ReturnType<IOidcProvider['introspectOrganization']>>;
-    try {
-      answer = await this.#provider.introspectOrganization({
-        accessToken: token.accessToken,
-        subject: token.subject,
-        organizationId: optionsArg.idpOrganizationId,
-      });
-    } catch (error) {
-      if (error instanceof OidcAuthorityUnavailableError) {
-        throw new AuthorityTokenError('authority_unavailable', error);
+    let answer = await this.introspect(token, optionsArg.idpOrganizationId);
+    if (!answer.active) {
+      const answeredAt = ++this.#sequence;
+      const forced = this.forcedRefresh(optionsArg.loginSessionId, optionsArg.principalId, token.accessToken);
+      const rotated = await forced.token;
+      if (forced.sequence < answeredAt || rotated.rotatedAfterRejection !== true) {
+        throw new AuthorityTokenError('authority_unavailable');
       }
-      throw error;
+      answer = await this.introspect(rotated, optionsArg.idpOrganizationId);
     }
     const grant = answer.active ? this.#project(answer.roles) : undefined;
     const active = answer.active && grant !== undefined;
@@ -228,6 +253,49 @@ export class AuthorityObserver<TGrant> {
     return entry;
   }
 
+  private async introspect(
+    tokenArg: IProviderToken,
+    organizationIdArg: string,
+  ): Promise<Awaited<ReturnType<IOidcProvider['introspectOrganization']>>> {
+    try {
+      return await this.#provider.introspectOrganization({
+        accessToken: tokenArg.accessToken,
+        subject: tokenArg.subject,
+        organizationId: organizationIdArg,
+      });
+    } catch (error) {
+      if (error instanceof OidcAuthorityUnavailableError) {
+        throw new AuthorityTokenError('authority_unavailable', error);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * The session's one forced rotation within `AUTHORITY_FORCED_REFRESH_INTERVAL_MS`,
+   * started for `rejectedArg` when there is none. Its failure is every
+   * caller's failure until the interval is over.
+   */
+  private forcedRefresh(sessionIdArg: string, principalIdArg: string, rejectedArg: string): IForcedRefresh {
+    const now = this.#now();
+    const last = this.#forcedRefreshes.get(sessionIdArg);
+    if (last && now - last.startedAt < AUTHORITY_FORCED_REFRESH_INTERVAL_MS) {
+      return last;
+    }
+    for (const [sessionId, forced] of this.#forcedRefreshes) {
+      if (now - forced.startedAt >= AUTHORITY_FORCED_REFRESH_INTERVAL_MS) {
+        this.#forcedRefreshes.delete(sessionId);
+      }
+    }
+    const forced: IForcedRefresh = {
+      startedAt: now,
+      sequence: ++this.#sequence,
+      token: this.#tokens.liveProviderToken(sessionIdArg, principalIdArg, { rejectedAccessToken: rejectedArg }),
+    };
+    this.#forcedRefreshes.set(sessionIdArg, forced);
+    return forced;
+  }
+
   /** Expired entries go first; if that is not enough, the oldest do. */
   private prune(): void {
     if (this.#cache.size <= this.#maxEntries) {

package/ts_relyingparty/classes.errors.ts

@@ -13,7 +13,11 @@ export type TRelyingPartyErrorCode =
   /** a hand-off code that is unknown, expired, already claimed, or claimed with the wrong verifier */
   | 'invalid_bearer_handoff'
   /** a refresh token that is unknown, rotated, expired, or of a session that is over */
-  | 'invalid_bearer_grant';
+  | 'invalid_bearer_grant'
+  /** `openBearerHandoff` named an opener that is no live provider login: unknown, ended, expired, of an inactive principal, or without a provider login of its own */
+  | 'invalid_handoff_opener'
+  /** a `sessionsOfPrincipal` cursor that no page of it answered */
+  | 'invalid_sessions_cursor';
 
 const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number>> = {
   login_method_unavailable: 404,
@@ -25,6 +29,8 @@ const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number
   return_target_not_allowed: 400,
   invalid_bearer_handoff: 400,
   invalid_bearer_grant: 400,
+  invalid_handoff_opener: 400,
+  invalid_sessions_cursor: 400,
 };
 
 /** A request the login flow refuses; the code is safe to answer, the browser learns nothing more. */

package/ts_relyingparty/classes.relyingpartyroutes.ts

@@ -13,6 +13,9 @@ import { sanitizeReturnPath } from './helpers.returnpath.js';
 import type {
   IRelyingPartyBearerDelivery,
   IRelyingPartyBearerLoginRequest,
+  IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerSessionAnswer,
+  IRelyingPartyBearerTokenAnswer,
   IRelyingPartyBearerTokens,
   IRelyingPartySession,
   IResolvedRelyingPartySession,
@@ -149,6 +152,12 @@ type TBearerApiRoute = 'bearerClaim' | 'bearerRefresh' | 'bearerSession' | 'bear
  * The four API routes answer CORS requests from the popup return targets'
  * origins, exactly, and no others; they never allow credentials.
  *
+ * In bearer-only mode (`RelyingPartySessions` `cookieSessions: false`) only
+ * the bearer routes and the callback answer, and no answer sets a cookie: a
+ * callback that is no bearer login fails without clearing an intent cookie
+ * that was never set, and `login`, `finalize`, `session` and `logout` answer
+ * `null`.
+ *
  * `handle()` answers `null` for every other request, so the application
  * chains its own routes (a local password login) around it. Cookies are only
  * ever set here: a `/typedrequest` answer cannot carry `Set-Cookie`.
@@ -204,12 +213,15 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
         return bearerResponse;
       }
     }
-    if (path === paths.login && method === 'GET' && providerLogin) {
-      return this.login(contextArg);
-    }
     if (path === paths.callback && method === 'GET' && providerLogin) {
       return this.callback(contextArg);
     }
+    if (!this.#sessions.cookieSessionsEnabled) {
+      return null;
+    }
+    if (path === paths.login && method === 'GET' && providerLogin) {
+      return this.login(contextArg);
+    }
     if (path === paths.finalize && method === 'GET' && providerLogin) {
       let location = this.#options.failureLocation;
       try {
@@ -257,16 +269,20 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     // the callback is read from the public origin, never from a forwarded host
     const callbackUrl = new URL(contextArg.url.pathname + contextArg.url.search, this.#sessions.publicOrigin);
     if (this.#sessions.bearerLoginEnabled) {
+      const cookieSessions = this.#sessions.cookieSessionsEnabled;
       let delivery: IRelyingPartyBearerDelivery | null;
       try {
         delivery = await this.#sessions.bearerDeliveryOf(callbackUrl);
       } catch (error) {
         // unknown whose callback this is: answered as the cookie path answers a failure
-        return this.callbackFailure(error, { 'Set-Cookie': this.#sessions.clearIntentCookie() });
+        return this.callbackFailure(error, cookieSessions ? { 'Set-Cookie': this.#sessions.clearIntentCookie() } : {});
       }
       if (delivery) {
         return this.bearerCallback(callbackUrl, delivery);
       }
+      if (!cookieSessions) {
+        return this.callbackOfNoBearerLogin(callbackUrl);
+      }
     }
     const cookieHeader = contextArg.headers.get('cookie');
     const providerError = callbackUrl.searchParams.get('error');
@@ -298,6 +314,20 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     }
   }
 
+  /**
+   * A callback of no bearer login in bearer-only mode: no attempt of this
+   * relying party can be completed with it, and no cookie is cleared because
+   * none was ever set.
+   */
+  private callbackOfNoBearerLogin(callbackUrlArg: URL): Response {
+    const providerError = callbackUrlArg.searchParams.get('error');
+    if (providerError) {
+      this.emit({ event: 'auth_callback_declined', code: providerError.slice(0, MAX_PROVIDER_ERROR_CODE_LENGTH) });
+      return redirect(this.#options.failureLocation);
+    }
+    return this.callbackFailure(new RelyingPartyError('invalid_login_callback'), {});
+  }
+
   /** A callback that failed for a reason other than a refusal: reported when it is the relying party's fault. */
   private callbackFailure(errorArg: unknown, headersArg: Record<string, string>): Response {
     const status = this.callbackFailureStatus(errorArg);
@@ -374,7 +404,8 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
         const refreshToken = bodyField(await this.readJsonBody(contextArg), 'refreshToken');
         endedLiveSession = refreshToken !== undefined ? await this.#sessions.endBearerSession(refreshToken) : false;
       }
-      return { endedLiveSession };
+      const answer: IRelyingPartyBearerLogoutAnswer = { endedLiveSession };
+      return answer;
     });
   }
 
@@ -491,7 +522,7 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     }
   }
 
-  private bearerTokenAnswer(tokensArg: IRelyingPartyBearerTokens): object {
+  private bearerTokenAnswer(tokensArg: IRelyingPartyBearerTokens): IRelyingPartyBearerTokenAnswer {
     return {
       tokenType: 'Bearer',
       accessToken: tokensArg.accessToken,
@@ -508,7 +539,7 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     };
   }
 
-  private async bearerSessionAnswer(contextArg: IRelyingPartyHttpContext): Promise<object> {
+  private async bearerSessionAnswer(contextArg: IRelyingPartyHttpContext): Promise<IRelyingPartyBearerSessionAnswer> {
     const live = await this.#sessions.resolveBearerSession(contextArg.headers.get('authorization'));
     return {
       session: live