Reference

TraxCaller

Package Trax.Api.AuthNamespace Trax.Api.AuthSource TraxCaller.cs

NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.

The current caller, as a scoped service that never throws. Where an injected TraxPrincipal throws TraxPrincipalNotAvailableException for an anonymous caller, TraxCaller reports null, so it fits code that runs for anonymous and authenticated callers alike: row-level query filters, subscription resolvers, junctions shared by gated and ungated trains.

Signature

public sealed class TraxCaller
{
    public TraxCaller(IHttpContextAccessor httpContextAccessor, ITrustedExecutionScope trustedScope);
 
    public bool IsAuthenticated { get; }
    public bool IsTrusted { get; }
    public TraxPrincipal? Principal { get; }
}

Properties

PropertyValue
PrincipalThe request's TraxPrincipal, read from HttpContext.User, or null when there is no HttpContext, no user, or a user whose claims carry no trax:principal-id. Its Id is qualified by the scheme, TraxApiKey:alice.
IsAuthenticatedPrincipal is not null.
IsTrustedITrustedExecutionScope.IsTrusted: true inside a trusted execution scope. Trax opens one only around the authorization of a remote run's named train and of a system-owned state machine's invoked train, so a train's own code sees false. Nothing on the API's own HTTP surface sets it.

Behavior

Principal is read on every access, not when TraxCaller is built. A principal that authenticates later in the request is visible to code that reads it afterwards: Trax's query-model interceptor authenticates a multi-scheme host just before a GraphQL request executes, and an EF query filter that reads Principal when the query runs sees it.

On a subscription the socket's principal is set on the connection's HttpContext.User at connection_init, so a TraxCaller injected into a subscribe resolver sees the subscriber.

IsTrusted is true only where a host opens a trusted scope itself, so a filter that lets trusted execution see every row treats that code as the host's. A remote run's train sees false, as a scheduled run does. See The scheduler and remote workers are trusted.

TraxCaller is registered scoped by AddTraxPrincipalAccessor, which every AddTrax*Auth call runs. A host with no scheme registered in some environment calls AddTraxPrincipalAccessor() itself, or TraxCaller does not resolve there.

Examples

A row-level filter's caller, bound over TraxCaller so the data layer does not depend on Trax auth:

public interface ILendingCaller
{
    string? PrincipalId { get; }
    bool IsLibrarian { get; }
}
 
public sealed class TraxLendingCaller(TraxCaller caller) : ILendingCaller
{
    public string? PrincipalId => caller.Principal?.Id;
    public bool IsLibrarian => caller.Principal?.Roles.Contains("Librarian") == true;
}

A subscribe resolver that admits only a room's participants:

public async ValueTask<ISourceStream<ChatEvent>> SubscribeToChatEventAsync(
    Guid chatRoomId, TraxCaller caller, ChatDbContext db,
    ITopicEventReceiver receiver, CancellationToken ct)
{
    var userId = caller.Principal?.Id;
    if (userId is null || !await db.Participants.AnyAsync(p => p.RoomId == chatRoomId && p.UserId == userId, ct))
        throw new GraphQLException(ErrorBuilder.New().SetMessage("Not authorized.").SetCode("TRAX_AUTHORIZATION").Build());
    return await receiver.SubscribeAsync<ChatEvent>($"ChatRoom:{chatRoomId}", ct);
}

See also