@idp.global/sdk 19.3.0 → 19.5.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, IRelyingPartyBearerHandoffOpening, IRelyingPartyBearerLoginRequest, IRelyingPartyBearerLoginStart, IRelyingPartyBearerOptions, IRelyingPartyBearerReturnTargets, IRelyingPartyBearerTokens, IRelyingPartyHooks, IRelyingPartyLiveSession, IRelyingPartyLoginOptions, IRelyingPartyLoginStart, IRelyingPartySession, IRelyingPartySessionOpening, IRelyingPartySessionsErasure, 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,16 +73,43 @@ 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 comes from a live provider login, directly or through a hand-off opened from one */
+    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,
- * so it is built before the database connects.
+ * 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, `openSession` or `openBearerHandoff`, 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`
  * principals it stays `undefined`.
@@ -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,34 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
     endSessionsOfPrincipal(principalIdArg: string, optionsArg?: {
         keepSessionId?: string;
     }): Promise<number>;
+    /**
+     * Erases every session of a principal, live or ended, and every row that
+     * belongs to one, without waiting for a sweep: what an application runs
+     * when it deletes an account, after its own erasers and before its user
+     * record.
+     *
+     * First each session not revoked yet, an expired one too, ends as
+     * `endSession` ends it: its tokens stop working at once, `onSessionEnded`
+     * names the principal, and its provider tokens go back to idp.global,
+     * which a deleted row could no longer do. Then each session's rows go: in
+     * bearer mode its hand-offs, claimed or not, and its token generations;
+     * the login attempt a provider session came out of; and the session row
+     * last, because it is the only link from the principal to the others, so
+     * an erase that fails half way leaves a retry everything it needs. A
+     * session opened or a token issued while the erase runs is not covered;
+     * it works only while the principal is active.
+     */
+    eraseSessionsOfPrincipal(principalIdArg: string): Promise<IRelyingPartySessionsErasure>;
+    /**
+     * 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;
     /**
@@ -195,6 +266,35 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      * at most and only its hash is stored. A code nobody claims ends its session.
      */
     completeBearerLogin(callbackUrlArg: URL): Promise<IRelyingPartyBearerHandoff>;
+    /**
+     * Opens a bearer session for a device the application pairs to a person
+     * who is signed in here, and answers its single-use hand-off code, which
+     * the device claims at `bearer/claim` with the verifier of `codeChallenge`,
+     * exactly like the code of a bearer login.
+     *
+     * `openerSessionId` names the session that confirmed the pairing, taken
+     * from the application's own record, never from the device. It must be a
+     * live provider login: not ended, not expired, its principal active, and
+     * with a provider login of its own. A session the application opened
+     * itself or one opened here does not qualify, so a paired device never
+     * pairs another one. Anything else throws
+     * `RelyingPartyError('invalid_handoff_opener')`.
+     *
+     * The new session acts as the opener's principal and has no provider login
+     * of its own: it ends by its expiry, `endSession`, `endSessionsOfPrincipal`,
+     * `bearer/logout` or the reuse of one of its credentials, never by an
+     * idp.global logout, and `AuthorityObserver` refuses it
+     * (`authority_login_required`). `maxAgeSeconds` is a whole number from 1 to
+     * `sessionMaxAgeSeconds`, the default, as for `openSession`. The code lives
+     * `BEARER_HANDOFF_MAX_AGE_SECONDS` at most and never past the session, and
+     * only its hash is stored; a code nobody claims ends its session. Nothing
+     * is stored for a refused opening.
+     */
+    openBearerHandoff(optionsArg: {
+        openerSessionId: string;
+        codeChallenge: string;
+        maxAgeSeconds?: number;
+    }): Promise<IRelyingPartyBearerHandoffOpening>;
     /** `abandonLogin` for a bearer login: the provider came back without a code. */
     abandonBearerLogin(callbackUrlArg: URL): Promise<void>;
     /**
@@ -210,9 +310,11 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      * access and refresh token answer, and the old access token stops working.
      * Rotation is strict — a client serializes its refreshes — because a
      * refresh token that comes back after it was spent ends the whole session.
-     * The provider login is checked on the way: a login idp.global ended ends
-     * the session here (`invalid_bearer_grant`), an unreachable provider fails
-     * with `AuthorityTokenError('authority_unavailable')` and spends nothing.
+     * The provider login of a bearer login is checked on the way: a login
+     * idp.global ended ends the session here (`invalid_bearer_grant`), an
+     * unreachable provider fails with `AuthorityTokenError('authority_unavailable')`
+     * and spends nothing. A session `openBearerHandoff` opened has no provider
+     * login (no `idpSubject` is stored) and rotates without the provider.
      */
     refreshBearerTokens(refreshTokenArg: unknown): Promise<IRelyingPartyBearerTokens>;
     /**
@@ -235,8 +337,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 +365,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. */
@@ -270,6 +390,12 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
     private createProviderSession;
     /** Where a bearer attempt's outcome goes, while its return target is still configured; `null` otherwise. */
     private bearerDeliveryOfAttempt;
+    /**
+     * Stores a new hand-off of a session, bound to the client's challenge, and
+     * answers its code, which is stored only as a hash. The code lives
+     * `BEARER_HANDOFF_MAX_AGE_SECONDS` at most and never past the session.
+     */
+    private storeBearerHandoff;
     /** Stores the next token generation of a live session and answers its tokens; none of them is stored in the clear. */
     private issueBearerTokens;
     /** A spent hand-off code or refresh token came back: whoever holds it, the session ends. */
@@ -282,6 +408,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 +465,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