function replacePrincipal
Since 0.1.0
replacePrincipal(
request: IRequest,
principal: IPrincipal
): void

Replaces request.user deliberately, bypassing the single-write guard.

This is the framework's authoritative identity write: auth-plugin's authMiddleware calls it, because a global registration plus a route-level one is a supported composition and both runs must be allowed to write. An application performing step-up authentication or impersonation calls it for the same reason — the boundary the guard draws is explicit intent versus implicit assignment, not one write per request.

Safe to call on a request that was never sealed.

Examples

Example 1

// Step-up: upgrade the principal after a second factor is verified.
replacePrincipal(ctx.request, { ...ctx.request.user!, roles: elevated });

Parameters

request: IRequest

The request whose principal is being replaced

principal: IPrincipal

The principal to install

Return Type

void

Usage

import { replacePrincipal } from "common/src/index.ts";