Interfaces
@system-inc/base-foundation · 515c140 · 5 symbols
AccessControlSettings
Access-control settings — registered at the worker level
(BaseSettings.accessControl) or contributed by a module
(ModuleSettings.accessControl).
Members
provider?:Constructor<SessionContextProvider>The application's SessionContextProvider implementation — the identity seam the session-access middleware resolves sessions through. Exactly one provider may be registered across the worker and all its modules; registering two different providers is a boot error, as is using
@RequireSessionAccess/@WithSessionAccesswith none registered.The class is resolved from the request-scoped DI container, so it can inject services (give it an injectable-family decorator if it has constructor dependencies).
SessionAccessOptions
A handler's effective access-control record: its
SessionAccessRequirements plus the enforcement mode. This is
what the decorators store in metadata (class + method options merge),
what the session-access middleware enforces, and what the
SessionContextProvider receives for option-dependent policy.
extends SessionAccessRequirements
Members
entitlements?:string[]The entitlements that are required to access the resource. If the user has any of these entitlements, they will be allowed to access the resource.
roles?:string[]The roles that are allowed to access the resource. If the user has any of these roles, they will be allowed to access the resource.
skipAuthorization?:booleanIf set to true, the user does not need to be authenticated to access the resource, but the session will be loaded if the user is authenticated.
Set by the decorator choice:
@WithSessionAccesssets it true,@RequireSessionAccessfalse.
SessionAccessRequirements
What a handler requires of the session — the parameter of
@RequireSessionAccess / @WithSessionAccess. Matching is any-of
for both lists; an absent or empty list requires nothing.
Whether the requirements are enforced (reject anonymous requests) or merely resolved-if-present is decided by which decorator you choose, not here — see import('./SessionAccessOptions').SessionAccessOptions for the handler's effective record including that mode.
Members
entitlements?:string[]The entitlements that are required to access the resource. If the user has any of these entitlements, they will be allowed to access the resource.
roles?:string[]The roles that are allowed to access the resource. If the user has any of these roles, they will be allowed to access the resource.
SessionContext
The identity resolved for an authenticated request.
Produced by the app's registered
import('./SessionContextProvider').SessionContextProvider and
stored on the request context under
import('./SessionContextRequestKey').SessionContextRequestKey.
Handlers read it to answer "who is making this request?"; the
framework's session-access middleware reads accessRoles /
entitlements to authorize handlers decorated with
@RequireSessionAccess.
The identity model is session + account + actor: accountId is who
authenticated; actorId is who is acting — the key modules use for
row ownership. An implementation may distinguish the two (e.g. an
account acting through one of several profiles) or set them equal.
Every member is deliberately required — handlers and modules read this
shape everywhere, so the cost of "not modeled" lands on the one
implementation, not on every read site. Each field has an honest
degenerate value for apps that don't model the concept: no actor
concept → actorId equals accountId (the account acts as itself)
and getActor() returns the account; no entitlements → [] (this
session holds none; entitlement-gated handlers correctly 403).
Members
accessRoles:readonly string[]The access roles assigned to the account, filtered by the provider to those currently valid (active, unexpired, scoped to the actor).
accountId:stringThe authenticated subject.
actorId:stringThe acting identity — the key modules use for row ownership.
entitlements:readonly string[]The entitlements assigned to the actor, filtered by the provider to those currently valid.
sessionId:stringThe session id.
getActor():Readonly<ActorType>Get the full actor object.
hasAccessRole(role:string | string[]):booleanDetermines if the session has a specific access role.
If the role provided is an array, it checks if any of the roles are present. If a single role is provided, it checks for that specific role.
hasEntitlement(entitlement:string | string[]):booleanDetermines if the session has a specific entitlement.
If the entitlement provided is an array, it checks if any of the entitlements are present. If a single entitlement is provided, it checks for that specific entitlement.
SessionContextProvider
The seam an application implements to plug its identity system into the framework's access control.
Register exactly one implementation via accessControl: { provider }
in the worker settings or a module's settings. The session-access
middleware resolves it from the request-scoped container to load the
identity for handlers decorated with @RequireSessionAccess /
@WithSessionAccess; authorization itself (role/entitlement matching,
401/403) is generic and stays in the middleware.
Members
resolve(requestContext:HandlerRequestContext,options:Readonly<SessionAccessOptions>):Promise<SessionContext<unknown> | null>Resolve the request into a SessionContext, or
nullwhen no valid session is present. Throwing is reserved for provider-policy failures (e.g. a required device identifier is missing, or the account is suspended) — plain "not signed in" isnull.Called once per decorated handler (a request that dispatches several decorated handlers, e.g. a GraphQL query, resolves each one), with that handler's merged SessionAccessOptions. This lets a provider apply option-dependent policy — e.g. enforce a device requirement only when authorization will run (
skipAuthorizationfalse). Providers whose identity lookup is expensive should cache it per request, e.g. by readingSessionContextRequestKey(where the middleware stores the previous resolution) before hitting the session store.