@idp.global/sdk 19.2.1 → 19.3.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, 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 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.
@@ -50,6 +54,11 @@ 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;
@@ -79,6 +88,10 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
     constructor(optionsArg: IRelyingPartySessionsOptions<TPrincipal>);
     /** Whether provider logins are offered at all. */
     get providerLoginEnabled(): 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,
@@ -157,6 +170,65 @@ 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
@@ -174,13 +246,40 @@ export declare class RelyingPartySessions<TPrincipal extends object | undefined
      */
     private tokenAfterForeignRefresh;
     private requireProvider;
+    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;
     /**
@@ -219,6 +318,14 @@ 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;
     /**
      * 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