Setu-TS
    Preparing search index...

    Interface IAuthSessionService

    The one owner of "who is signed in" for a session.

    Registered by AuthPlugin when its signIn option is configured. A password login, a federated sign-in, a passkey assertion and a SAML assertion all record their principal through IAuthSessionService.signIn, and the plugin's own authentication strategy reads that record back — so an application needs no hand-written middleware to turn its session into a principal.

    import { CAPABILITIES, type IAuthSessionService } from '@setu-ts/common';

    const auth = ctx.services.get<IAuthSessionService>(CAPABILITIES.AUTH_SESSION);
    await auth.signIn(ctx, principal, { methods: ['pwd'] });

    0.8.0

    interface IAuthSessionService {
        current(ctx: IRequestContext): IPrincipal | null;
        pending(ctx: IRequestContext): PendingSignIn | null;
        signIn(
            ctx: IRequestContext,
            principal: IPrincipal,
            options: SignInOptions,
        ): Promise<SignInOutcome>;
        signOut(ctx: IRequestContext): void;
    }
    Index
    current pending signIn signOut

    • Reads the signed-in principal of the request's session, without running the authentication strategy chain.

      This is the snapshot recorded at sign-in: an implementation's per-request re-checks (@setu-ts/auth-plugin's refreshPrincipal and sessionStamp) do not run here, so a session they have ended can still be returned. Decide who may act from ctx.request.user, which the strategy chain re-checked.

      Parameters

      Returns IPrincipal | null

      The principal, or null when the session holds no identity

      If the session middleware did not run for this request

    • Reads the pending second-factor record, if one exists.

      A pending record is written by IAuthSessionService.signIn when the mfa.required option answers true and the methods hold no second factor. It is consumed by the package's own verifiers (TOTP, passkeys), which promote it to the signed-in key after a successful factor check.

      Parameters

      Returns PendingSignIn | null

      The pending record, or null when none is stored or it has expired (an expired record can never be completed, so it is not reported)

      If the session middleware did not run for this request

      0.8.0

    • Records principal as the signed-in identity of the request's session.

      The write happens inside the session, so it is committed by the session middleware after the handler returns — the service never issues a Set-Cookie itself. The session id is regenerated, because a session id a caller planted before authentication must not survive into the authenticated session (session fixation).

      When the signIn.mfa.required option answers true and the methods hold no second factor, the principal is stored in a pending record instead and the outcome is { status: 'second-factor-required' }.

      Requires the session middleware to have run for this request; it throws otherwise, exactly as ISessionService.from does.

      Parameters

      Returns Promise<SignInOutcome>

      Resolves once the record has been written

      If the session middleware did not run for this request

    • Ends the signed-in session.

      What is revoked depends on the session strategy, and callers must know which one they run. On the store strategy (SessionPlugin({ store: … })) the stored entry is deleted, so a cookie copied before this call stops authenticating immediately. On the default encrypted-cookie strategy there is nothing server-side to delete: a cookie copied before sign-out keeps authenticating until its maxAge expires, because the payload the cookie carries is itself the session. Use the store strategy wherever sign-out has to mean revocation.

      Parameters

      Returns void

      If the session middleware did not run for this request

    Settings
    Member Visibility

    On This Page
    Methods