@idp.global/sdk 19.3.0 → 19.4.0

package/dist_ts_relyingparty/classes.relyingpartysessions.d.ts

@@ -1,6 +1,6 @@
 import { type IOidcProvider } from './classes.idpoidcprovider.js';
 import type { IRelyingPartyModels } from './classes.rpmodels.js';
-import type { IAuthorityTokenSource, IProviderToken, IRelyingPartyBearerDelivery, IRelyingPartyBearerHandoff, IRelyingPartyBearerLoginRequest, IRelyingPartyBearerLoginStart, IRelyingPartyBearerOptions, IRelyingPartyBearerReturnTargets, IRelyingPartyBearerTokens, IRelyingPartyHooks, IRelyingPartyLiveSession, IRelyingPartyLoginOptions, IRelyingPartyLoginStart, IRelyingPartySession, IRelyingPartySessionOpening, IResolvedRelyingPartySession, TRelyingPartyPrincipals, TRelyingPartySessionEndReason } from './interfaces.js';
+import type { IAuthorityTokenSource, IProviderToken, IRelyingPartyBearerDelivery, IRelyingPartyBearerHandoff, IRelyingPartyBearerLoginRequest, IRelyingPartyBearerLoginStart, IRelyingPartyBearerOptions, IRelyingPartyBearerReturnTargets, IRelyingPartyBearerTokens, IRelyingPartyHooks, IRelyingPartyLiveSession, IRelyingPartyLoginOptions, IRelyingPartyLoginStart, IRelyingPartySession, IRelyingPartySessionOpening, IRelyingPartySessionsPage, IRelyingPartySessionsPageOptions, IResolvedRelyingPartySession, TRelyingPartyPrincipals, TRelyingPartySessionEndReason } from './interfaces.js';
 export declare const RELYING_PARTY_DEFAULT_SESSION_MAX_AGE_SECONDS: number;
 export declare const RELYING_PARTY_DEFAULT_LOGIN_PATH_PREFIX = "/auth/";
 /** The label the CSRF HMAC starts with unless the application names its own. */
@@ -9,6 +9,10 @@ export declare const RELYING_PARTY_DEFAULT_CSRF_LABEL: string;
 export declare const LOGIN_ATTEMPT_MAX_AGE_SECONDS: number;
 /** The longest intent a login carries (`IRelyingPartyLoginOptions.intent`), in characters. */
 export declare const RELYING_PARTY_MAX_INTENT_LENGTH = 4096;
+/** How many sessions one page of `sessionsOfPrincipal` holds unless its `limit` says otherwise. */
+export declare const RELYING_PARTY_DEFAULT_SESSIONS_PAGE_LIMIT = 100;
+/** The largest `limit` of `sessionsOfPrincipal`; the store reads no larger page. */
+export declare const RELYING_PARTY_MAX_SESSIONS_PAGE_LIMIT = 1000;
 /** How long a bearer hand-off code can be claimed, at most; never past its session. */
 export declare const BEARER_HANDOFF_MAX_AGE_SECONDS = 60;
 /** How long a bearer access token lives unless `bearer.accessTokenMaxAgeSeconds` says otherwise. */
@@ -40,6 +44,12 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
     sessionEncryptionKey: Buffer;
     /** 32 bytes; the CSRF HMAC key */
     csrfKey: Buffer;
+    /**
+     * `true` (the default): cookie sessions with a session-bound CSRF token,
+     * beside bearer hand-off mode when `bearer` is given. Bearer hand-off alone,
+     * without any cookie, is `IRelyingPartyBearerOnlySessionsOptions`.
+     */
+    cookieSessions?: true;
     /** the label the CSRF HMAC starts with; an application with live sessions keeps its own */
     csrfLabel?: string;
     sessionMaxAgeSeconds?: number;
@@ -63,15 +73,42 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
     /** the clock every comparison reads; tests step it instead of sleeping */
     now?: () => number;
 }
+/**
+ * Bearer-only mode (`cookieSessions: false`): the application's own clients
+ * sign in through bearer hand-off and nothing else. The relying party never
+ * reads or sets a cookie — not even the clearing intent cookie of a callback
+ * that is no bearer login — so it has no CSRF token and takes no CSRF key:
+ * `csrfKey`, `csrfLabel` and `cookieNames` are refused, not ignored. The
+ * cookie steps (`openSession`, `startLogin`, `completeLogin`, `abandonLogin`,
+ * `finalizeLogin`, `clearSessionCookie`, `clearIntentCookie`) throw
+ * `RelyingPartyError('login_method_unavailable')` and `resolveCookieSession`
+ * answers `null`.
+ */
+export interface IRelyingPartyBearerOnlySessionsOptions<TPrincipal extends object | undefined = undefined> extends Omit<IRelyingPartySessionsOptions<TPrincipal>, 'provider' | 'csrfKey' | 'csrfLabel' | 'cookieNames' | 'cookieSessions' | 'bearer'> {
+    cookieSessions: false;
+    /** every bearer session is a provider login */
+    provider: IOidcProvider;
+    bearer: IRelyingPartyBearerOptions;
+    csrfKey?: never;
+    csrfLabel?: never;
+    cookieNames?: never;
+}
 /**
  * The relying-party session layer: provider logins through the authorization
  * code flow with PKCE, HttpOnly cookie sessions with a session-bound CSRF
  * token, provider tokens sealed at rest and rotated under a cross-replica
  * lock, and session ends that hand the tokens back.
  *
- * Nothing here runs on a timer: expired login attempts are swept when the next
- * login starts, and the only timer — the revocation budget — is unreferenced
- * and cleared on every path. Nothing here does I/O while it is constructed,
+ * With `cookieSessions: false` it runs bearer hand-off mode alone and never
+ * touches a cookie (`IRelyingPartyBearerOnlySessionsOptions`).
+ *
+ * Nothing here runs on a timer: expired login attempts, bearer state and
+ * ended sessions are swept one bounded batch at a time when a login starts or
+ * the application opens a session, and the only timer — the revocation
+ * budget — is unreferenced and cleared on every path. Every session comes
+ * from a login start or from `openSession`, and each of those sweeps a batch
+ * of at least one first, so removal keeps pace with creation and the ended
+ * sessions kept stay bounded. Nothing here does I/O while it is constructed,
  * so it is built before the database connects.
  *
  * `TPrincipal` is what a `principals.resolve` answers; with `isActive`
@@ -85,9 +122,11 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
     readonly intentCookieName: string;
     readonly loginPathPrefix: string;
     readonly sessionMaxAgeSeconds: number;
-    constructor(optionsArg: IRelyingPartySessionsOptions<TPrincipal>);
+    constructor(optionsArg: IRelyingPartySessionsOptions<TPrincipal> | IRelyingPartyBearerOnlySessionsOptions<TPrincipal>);
     /** Whether provider logins are offered at all. */
     get providerLoginEnabled(): boolean;
+    /** Whether cookie sessions are offered; `false` only in bearer-only mode (`cookieSessions: false`). */
+    get cookieSessionsEnabled(): boolean;
     /** Whether bearer hand-off mode is offered. */
     get bearerLoginEnabled(): boolean;
     /** The return targets bearer clients may name, per kind, as configured; `undefined` without bearer mode. */
@@ -109,7 +148,11 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
         principalId: string;
         maxAgeSeconds?: number;
     }): Promise<IRelyingPartySessionOpening>;
-    /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
+    /**
+     * The live session behind the session cookie, or `null`. A read touches it
+     * at most once a minute. Always `null` in bearer-only mode, which reads no
+     * cookie.
+     */
     resolveCookieSession(cookieHeaderArg: string | null | undefined): Promise<IResolvedRelyingPartySession<TPrincipal> | null>;
     /**
      * Re-checks a session by its id with the same strength as a cookie request:
@@ -142,6 +185,16 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
     endSessionsOfPrincipal(principalIdArg: string, optionsArg?: {
         keepSessionId?: string;
     }): Promise<number>;
+    /**
+     * One page of a principal's live sessions, newest first: the ones neither
+     * ended nor expired, and none at all while the principal is not active —
+     * exactly the sessions `isSessionLive` confirms. Pass the page's
+     * `nextCursor` as `cursor` to read the next one; the last page has none.
+     * The cursor is opaque, and one this method did not answer is refused with
+     * `invalid_sessions_cursor`. A session opened while the pages are read is
+     * listed only when it sorts after the cursor; none is listed twice.
+     */
+    sessionsOfPrincipal(principalIdArg: string, optionsArg?: IRelyingPartySessionsPageOptions): Promise<IRelyingPartySessionsPage>;
     clearSessionCookie(): string;
     clearIntentCookie(): string;
     /**
@@ -235,8 +288,25 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      * is unknown — is rotated first. The session has to belong to
      * `expectedPrincipalIdArg`, so a credential is never evaluated with another
      * person's tokens.
+     *
+     * With `rejectedAccessToken` (`IAuthorityTokenSource`) the call rotates the
+     * session's token whatever is stored, and only a rotation that it starts
+     * marks its answer `rotatedAfterRejection`: one that started before it, in
+     * this process or another replica's, says nothing about the rejection, so
+     * the call awaits it and throws `authority_unavailable`. A refused rotation
+     * ends the session (`refresh_token_refused`) and throws
+     * `authority_login_required`. A session without a refresh token has nothing
+     * to rotate with: it throws `authority_unavailable`, or ends as
+     * `access_token_unusable` when its token is dead.
+     */
+    liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string, optionsArg?: {
+        rejectedAccessToken?: string;
+    }): Promise<IProviderToken>;
+    /**
+     * One rotation of the session in this process at a time. A forced call that
+     * finds one running waits for it, so a refusal still ends it, and is
+     * unavailable otherwise: that rotation started before the call.
      */
-    liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken>;
     private refreshProviderToken;
     private runProviderRefresh;
     /**
@@ -246,6 +316,7 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      */
     private tokenAfterForeignRefresh;
     private requireProvider;
+    private requireCookieSessions;
     private requireBearer;
     private checkLoginOptions;
     /** An unsaved attempt with its state, nonce and sealed verifier; the caller binds it and names where it returns. */
@@ -282,6 +353,19 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
     private endUnclaimedHandoff;
     /** Revokes a session that was never handed out and erases its sealed tokens. */
     private discardUnopenedSession;
+    /**
+     * Revokes a session not revoked yet and erases its sealed tokens; answers
+     * the document as it was before, `null` when it was over already. Its
+     * expiry comes forward to the revocation, never later, so the sweep finds
+     * an ended session by its expiry alone and `revokedAt` keeps when and that
+     * it was ended. Two conditional writes keep the earlier of the two times:
+     * the first ends a session within its expiry, the second one past it. A
+     * crash between them leaves an expired row unrevoked, which reads as over
+     * and is swept; a row revoked before 19.4.0 kept its later expiry, which is
+     * harmless because every reader checks `revokedAt` or reads live rows only,
+     * and it ages out.
+     */
+    private revokeSessionDocument;
     /**
      * Tells the application a session ended. Its hook never stands between the
      * local revocation and the provider revocation: a throw or a rejection is
@@ -326,6 +410,17 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      * sign-in.
      */
     private sweepBearerState;
+    /**
+     * Removes sessions an hour past their expiry, oldest first, one bounded
+     * page per login start and per session the application opens. An ended
+     * session's expiry is its revocation at the latest, so the expiry index
+     * finds expired and revoked sessions alike. Each of them ended already: the
+     * row goes without an end, a hook or a provider call. A row is deleted only
+     * while its expiry is still past the cutoff, so a row whose expiry moved
+     * after the page was read stays. A sweep that cannot run never blocks a
+     * sign-in.
+     */
+    private sweepEndedSessions;
     /**
      * Reports one diagnostic. Every cleanup step reports through here, so a
      * throwing sink must not end it: the event and the sink's failure go to