@idp.global/sdk 19.2.1 → 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, 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,14 @@ 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. */
+export declare const RELYING_PARTY_DEFAULT_BEARER_ACCESS_TOKEN_MAX_AGE_SECONDS: number;
 /**
  * How long ending a session waits for the provider to take its tokens back.
  * The local session is already revoked when that call runs.
@@ -36,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;
@@ -50,19 +64,51 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
     };
     /** the prefix of the login routes; a login never returns into it */
     loginPathPrefix?: string;
+    /**
+     * absent: no bearer hand-off mode. Needs `provider` and the bearer models
+     * (`createRelyingPartyModels` binds them).
+     */
+    bearer?: IRelyingPartyBearerOptions;
     hooks?: IRelyingPartyHooks;
     /** 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`
@@ -76,9 +122,15 @@ 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. */
+    get bearerReturnTargets(): Readonly<Required<IRelyingPartyBearerReturnTargets>> | undefined;
     /**
      * How long one replica holds the right to rotate a session's tokens. The
      * provider detects reuse of a superseded refresh token and kills the family,
@@ -96,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:
@@ -129,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;
     /**
@@ -157,14 +223,90 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      * session this very attempt created.
      */
     finalizeLogin(cookieHeaderArg: string | null | undefined): Promise<string>;
+    /**
+     * Starts a bearer login for one of the application's own clients: the same
+     * provider login as `startLogin`, but the outcome goes to the return target
+     * the client named — exactly one of the configured targets of its kind —
+     * and it sets no cookie. The login is bound to the client's S256 challenge
+     * instead of a browser: whoever claims its hand-off code has to present the
+     * verifier. Every field of the request is checked as untrusted input.
+     */
+    startBearerLogin(requestArg: IRelyingPartyBearerLoginRequest, optionsArg?: IRelyingPartyLoginOptions): Promise<IRelyingPartyBearerLoginStart>;
+    /**
+     * Where the outcome of a login callback goes when it belongs to a bearer
+     * login: the client kind, the return target and the client's `state`, read
+     * without consuming anything. `null` for a cookie login, an unknown state,
+     * and a return target that is no longer configured — the callback is then
+     * not answered as a bearer login at all.
+     */
+    bearerDeliveryOf(callbackUrlArg: URL): Promise<IRelyingPartyBearerDelivery | null>;
+    /**
+     * Consumes a bearer login's attempt exactly once, exchanges the code, admits
+     * the principal and opens its session — everything `completeLogin` does,
+     * with the same failures — and answers a single-use hand-off code bound to
+     * the client's challenge. The code lives `BEARER_HANDOFF_MAX_AGE_SECONDS`
+     * at most and only its hash is stored. A code nobody claims ends its session.
+     */
+    completeBearerLogin(callbackUrlArg: URL): Promise<IRelyingPartyBearerHandoff>;
+    /** `abandonLogin` for a bearer login: the provider came back without a code. */
+    abandonBearerLogin(callbackUrlArg: URL): Promise<void>;
+    /**
+     * Trades a hand-off code and the verifier of its challenge for the first
+     * access and refresh token of the session. The code is consumed by the first
+     * claim whatever its verifier: a wrong verifier ends the session, and so
+     * does the code coming back after it was claimed (RFC 6749 §4.1.2). A code
+     * that expired unclaimed ends its session too.
+     */
+    claimBearerHandoff(codeArg: unknown, codeVerifierArg: unknown): Promise<IRelyingPartyBearerTokens>;
+    /**
+     * Rotates a bearer session's tokens: the refresh token is spent, a new
+     * 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.
+     */
+    refreshBearerTokens(refreshTokenArg: unknown): Promise<IRelyingPartyBearerTokens>;
+    /**
+     * The live session behind a bearer access token, or `null`: the token of the
+     * session's current generation, not expired, its session live and its
+     * principal active. A read touches the session at most once a minute.
+     */
+    resolveBearerAccessToken(accessTokenArg: unknown): Promise<IRelyingPartyLiveSession<TPrincipal> | null>;
+    /** `resolveBearerAccessToken` for an `Authorization: Bearer <token>` header. */
+    resolveBearerSession(authorizationHeaderArg: string | null | undefined): Promise<IRelyingPartyLiveSession<TPrincipal> | null>;
+    /**
+     * Ends the session of a bearer token — a live access token or the current
+     * refresh token — like `endSession`. A refresh token that was already spent
+     * is reuse and ends the session as such. Answers whether this call ended it.
+     */
+    endBearerSession(tokenArg: unknown): Promise<boolean>;
     /**
      * An access token of this login session that is usable right now. A token
      * within `ACCESS_TOKEN_REFRESH_SKEW_MS` of its expiry — or one whose expiry
      * 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;
     /**
@@ -174,15 +316,56 @@ 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. */
+    private newLoginAttempt;
+    /**
+     * The provider half of a consumed attempt: exchanges the code, admits the
+     * principal and opens the session. Nothing of a failed login survives: its
+     * tokens are handed back before the failure leaves.
+     */
+    private openProviderLogin;
     private newSessionDoc;
     private csrfTokenOf;
     private opening;
     private snapshot;
     /** A session document that is live right now with its active principal, touched at most once a minute. */
     private liveSession;
+    /**
+     * Stores the session of a provider login and links it to its attempt.
+     * `beforeOpenedArg` stores what the session is handed out with besides its
+     * cookie; like the hook after it, a throw discards the session.
+     */
     private createProviderSession;
+    /** Where a bearer attempt's outcome goes, while its return target is still configured; `null` otherwise. */
+    private bearerDeliveryOfAttempt;
+    /** 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. */
+    private bearerCredentialReused;
+    /**
+     * Takes a hand-off whose code expired unclaimed and ends its session, which
+     * nothing can reach any more. The caller has read it expired; expiry never
+     * moves, so only a claim in between can stop this.
+     */
+    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
@@ -219,6 +402,25 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      * start. A sweep that cannot run never blocks a sign-in.
      */
     private sweepExpiredAttempts;
+    /**
+     * One bounded page per bearer login start, oldest first: hand-offs whose
+     * code expired unclaimed end their session, and hand-offs and token
+     * generations an hour past their expiry are removed — an unclaimed hand-off
+     * only after its session was ended. A sweep that cannot run never blocks a
+     * 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