@idp.global/sdk 19.4.0 → 19.5.0

package/ts_relyingparty/interfaces.ts

@@ -2,9 +2,13 @@ import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcPrompt, TOidcTo
 import type { TRelyingPartyBearerClientKind } from './contract.bearer.js';
 
 export type {
+  IRelyingPartyBearerClaimRequest,
   IRelyingPartyBearerErrorAnswer,
+  IRelyingPartyBearerLoginQuery,
   IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerLogoutRequest,
   IRelyingPartyBearerMessage,
+  IRelyingPartyBearerRefreshRequest,
   IRelyingPartyBearerSessionAnswer,
   IRelyingPartyBearerSessionInfo,
   IRelyingPartyBearerTokenAnswer,
@@ -156,6 +160,37 @@ export interface IRelyingPartyBearerHandoff {
   expiresAt: number;
 }
 
+/**
+ * A bearer session the application opened for a device it paired
+ * (`openBearerHandoff`): the session, which has no provider login of its own
+ * (`idpSubject` and `loginAttemptId` are absent), and the single-use code the
+ * device claims at `bearer/claim` with the verifier of its challenge. The
+ * code is no token; only its hash is stored.
+ */
+export interface IRelyingPartyBearerHandoffOpening {
+  session: IRelyingPartySession;
+  code: string;
+  /** epoch milliseconds, at most `BEARER_HANDOFF_MAX_AGE_SECONDS` after the opening and never past the session */
+  expiresAt: number;
+}
+
+/**
+ * What `eraseSessionsOfPrincipal` removed of one principal: the sessions it
+ * ended first, and the rows it deleted.
+ */
+export interface IRelyingPartySessionsErasure {
+  /** sessions not revoked yet (an expired one too) that it ended, each with `onSessionEnded` and its provider tokens handed back */
+  endedSessions: number;
+  /** session rows, live or ended */
+  deletedSessions: number;
+  /** the sign-in transactions the provider sessions came out of */
+  deletedLoginAttempts: number;
+  /** bearer hand-offs, claimed or not */
+  deletedBearerHandoffs: number;
+  /** bearer token generations, current or rotated */
+  deletedBearerTokens: number;
+}
+
 /**
  * The relying party's own tokens of a bearer session. The refresh token
  * rotates on every use; a rotated one coming back ends the session.
@@ -298,20 +333,22 @@ export interface IRelyingPartyHooks {
    * A provider login opened a session, linked to its attempt. Runs before the
    * login answers; a throw fails the login: the session is revoked, the
    * provider tokens are handed back and the original error is rethrown.
+   * `delivery` is where a bearer login's outcome goes (its client kind, return
+   * target and the client's `state`); a cookie login has none.
    */
-  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession }): Promise<void>;
+  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession; delivery?: IRelyingPartyBearerDelivery }): Promise<void>;
   /**
    * A session ended, or a caller tried to end one that was already over
    * (`revokedHere: false`). Close its live connections when `revokedHere`,
    * drop cached authority either way. Must not wait. A throw (or a rejected
    * promise) is reported as a `hook_failed` event and never stops the end:
-   * the provider tokens go back regardless.
+   * the provider tokens go back regardless. An end that revoked the session
+   * here names its principal (`principalId`); one that found it over already
+   * does not.
    */
-  onSessionEnded?(eventArg: {
-    sessionId: string;
-    reason: TRelyingPartySessionEndReason;
-    revokedHere: boolean;
-  }): void;
+  onSessionEnded?(eventArg:
+    | { sessionId: string; reason: TRelyingPartySessionEndReason; revokedHere: true; principalId: string }
+    | { sessionId: string; reason: TRelyingPartySessionEndReason; revokedHere: false }): void;
   /**
    * Structured diagnostics; the default writes one JSON line to
    * `console.error`. A throwing sink never interrupts the step that reported: