@idp.global/sdk 18.0.1 → 18.2.0

package/dist_ts_relyingparty/classes.relyingpartysessions.d.ts

@@ -0,0 +1,223 @@
+import { type IOidcProvider } from './classes.idpoidcprovider.js';
+import type { IRelyingPartyModels } from './classes.rpmodels.js';
+import type { IAuthorityTokenSource, IProviderToken, IRelyingPartyHooks, IRelyingPartyLiveSession, 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. */
+export declare const RELYING_PARTY_DEFAULT_CSRF_LABEL: string;
+/** A sign-in transaction has to survive an interactive login at the provider, not a working day. */
+export declare const LOGIN_ATTEMPT_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.
+ */
+export declare const TOKEN_REVOCATION_BUDGET_MS = 3000;
+/** How long before its expiry the provider access token is rotated. */
+export declare const ACCESS_TOKEN_REFRESH_SKEW_MS = 60000;
+/**
+ * What the refresh lock adds on top of the provider request it has to cover:
+ * the claim and the store around it, and clock disagreement between replicas.
+ */
+export declare const REFRESH_LOCK_MARGIN_MS = 20000;
+export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefined = undefined> {
+    models: IRelyingPartyModels;
+    /**
+     * `isActive` principals, or a `resolve` that answers the principal itself;
+     * its answer is then the `principal` of every live session.
+     */
+    principals: TRelyingPartyPrincipals<TPrincipal>;
+    /** absent: no provider login; sessions are opened by the application only */
+    provider?: IOidcProvider;
+    /** the application's public origin, e.g. `https://app.example`; cookies are `Secure` exactly on https */
+    publicOrigin: string;
+    /** 32 bytes; seals the PKCE verifier and the provider tokens at rest */
+    sessionEncryptionKey: Buffer;
+    /** 32 bytes; the CSRF HMAC key */
+    csrfKey: Buffer;
+    /** the label the CSRF HMAC starts with; an application with live sessions keeps its own */
+    csrfLabel?: string;
+    sessionMaxAgeSeconds?: number;
+    /**
+     * defaults: `__Host-idp_rp_session` / `__Host-idp_rp_intent` on https,
+     * without the prefix otherwise. A `__Host-` or `__Secure-` name needs an
+     * https origin and is refused on http.
+     */
+    cookieNames?: {
+        session?: string;
+        intent?: string;
+    };
+    /** the prefix of the login routes; a login never returns into it */
+    loginPathPrefix?: string;
+    hooks?: IRelyingPartyHooks;
+    /** the clock every comparison reads; tests step it instead of sleeping */
+    now?: () => number;
+}
+/**
+ * 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.
+ *
+ * `TPrincipal` is what a `principals.resolve` answers; with `isActive`
+ * principals it stays `undefined`.
+ */
+export declare class RelyingPartySessions<TPrincipal extends object | undefined = undefined> implements IAuthorityTokenSource {
+    #private;
+    readonly publicOrigin: string;
+    readonly secureCookies: boolean;
+    readonly sessionCookieName: string;
+    readonly intentCookieName: string;
+    readonly loginPathPrefix: string;
+    readonly sessionMaxAgeSeconds: number;
+    constructor(optionsArg: IRelyingPartySessionsOptions<TPrincipal>);
+    /** Whether provider logins are offered at all. */
+    get providerLoginEnabled(): boolean;
+    /**
+     * 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,
+     * so the lock strictly outlives its longest possible holder: one provider
+     * request at its full deadline plus the margin.
+     */
+    get refreshLockMs(): number;
+    /**
+     * Opens a session the application authenticated itself (a local password
+     * login). It carries no provider tokens.
+     */
+    openSession(optionsArg: {
+        principalId: string;
+    }): Promise<IRelyingPartySessionOpening>;
+    /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
+    resolveCookieSession(cookieHeaderArg: string | null | undefined): Promise<IResolvedRelyingPartySession<TPrincipal> | null>;
+    /**
+     * Re-checks a session by its id with the same strength as a cookie request:
+     * live, its principal active, and touched under the liveness it was read
+     * with. What a pinned socket connection runs per request.
+     */
+    revalidateSession(sessionIdArg: string): Promise<IRelyingPartySession | null>;
+    /** `revalidateSession`, answering the principal the same read resolved as well. */
+    revalidateLiveSession(sessionIdArg: string): Promise<IRelyingPartyLiveSession<TPrincipal> | null>;
+    /** Whether a session is live right now, without touching it; what a sweep asks. */
+    isSessionLive(sessionIdArg: string): Promise<boolean>;
+    /** Whether a candidate is the CSRF token of a resolved (or just opened) session, compared in constant time. */
+    validateCsrf(resolvedArg: {
+        csrfToken: string;
+    }, candidateArg: unknown): boolean;
+    /** Ends one session; see `endSession`. */
+    logout(sessionIdArg: string): Promise<boolean>;
+    /**
+     * Revokes a session once, with one conditional update: a touch running
+     * beside it cannot write the revocation away, and a second call finds
+     * nothing. Its provider tokens go back within `TOKEN_REVOCATION_BUDGET_MS`,
+     * after the local revocation, which never depends on the provider. Answers
+     * whether this call ended it.
+     */
+    endSession(sessionIdArg: string, reasonArg?: TRelyingPartySessionEndReason): Promise<boolean>;
+    /**
+     * Ends every live session of a principal but `keepSessionId` (a password
+     * change keeps the session that asked for it) and answers how many ended.
+     */
+    endSessionsOfPrincipal(principalIdArg: string, optionsArg?: {
+        keepSessionId?: string;
+    }): Promise<number>;
+    clearSessionCookie(): string;
+    clearIntentCookie(): string;
+    /**
+     * Starts a sign-in transaction: one attempt document with the PKCE verifier
+     * sealed next to it, and an intent cookie that binds the callback to this
+     * browser.
+     */
+    startLogin(returnPathArg: unknown): Promise<IRelyingPartyLoginStart>;
+    /**
+     * Consumes the attempt exactly once, exchanges the code, admits the
+     * principal and opens a session. A replayed callback, a foreign intent
+     * cookie and an expired attempt all find nothing to consume. Nothing of a
+     * failed login survives: its tokens are handed back before the failure
+     * leaves.
+     */
+    completeLogin(callbackUrlArg: URL, cookieHeaderArg: string | null | undefined): Promise<IRelyingPartySessionOpening>;
+    /**
+     * The provider sent the browser back without a code. The attempt is
+     * consumed so its state can never complete afterwards; a callback that
+     * matches no open attempt leaves nothing to do.
+     */
+    abandonLogin(callbackUrlArg: URL, cookieHeaderArg: string | null | undefined): Promise<void>;
+    /**
+     * The last step of a login: the browser arrives with both cookies, and the
+     * return path is released only when the session cookie belongs to the
+     * session this very attempt created.
+     */
+    finalizeLogin(cookieHeaderArg: string | null | undefined): Promise<string>;
+    /**
+     * 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.
+     */
+    liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken>;
+    private refreshProviderToken;
+    private runProviderRefresh;
+    /**
+     * Another replica is rotating this session right now. Whatever it has
+     * written by the time this request looks again is used; otherwise the
+     * request fails closed and the next one finds the rotated pair.
+     */
+    private tokenAfterForeignRefresh;
+    private requireProvider;
+    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;
+    private createProviderSession;
+    /** Revokes a session that was never handed out and erases its sealed tokens. */
+    private discardUnopenedSession;
+    /**
+     * Tells the application a session ended. Its hook never stands between the
+     * local revocation and the provider revocation: a throw or a rejection is
+     * reported as `hook_failed` and the end runs on.
+     */
+    private notifySessionEnded;
+    /**
+     * The conditional revocation every end of a session runs. Answers the
+     * sealed tokens it took off the session when this call revoked it, `null`
+     * when the session was already over.
+     */
+    private revokeSession;
+    /** The provider says the login is over: the session ends here without asking it anything more. */
+    private endProviderSession;
+    /**
+     * Hands the tokens of an ended session back, best-effort and within the
+     * budget. A sealed value this deployment can no longer open is skipped.
+     */
+    private revokeSealedTokens;
+    private revokeRotatedTokens;
+    private revokeCompletionTokens;
+    private revokeToken;
+    /**
+     * Runs a best-effort provider step under `TOKEN_REVOCATION_BUDGET_MS`. What
+     * is still in flight at the deadline keeps running and ends on the provider
+     * client's own request timeout; only the waiting stops. The timer is cleared
+     * on every path and unreferenced.
+     */
+    private withinRevocationBudget;
+    /** A sealed value this deployment can still open, or `undefined`. */
+    private openSealed;
+    /**
+     * Removes attempts an hour past their expiry, one bounded page per login
+     * start. A sweep that cannot run never blocks a sign-in.
+     */
+    private sweepExpiredAttempts;
+    /**
+     * 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
+     * `console.error` instead.
+     */
+    private emit;
+}