Documentation / @zerotal/auth / GateService

Class: GateService

GateService — authorization service.

Bound in the container as 'gate' by AuthProvider. Interact with it through the Gate facade or by resolving it from the container.

Example

// Register a policy:
Gate.registerPolicy(Post, PostPolicy);

// Define a closure-based ability (no model required):
Gate.defineAbility('publish-newsletter', (user) => user?.role === 'admin');

// Register a before hook (e.g. super-admin bypass):
Gate.before((user) => user?.isSuperAdmin ? true : undefined);

// Check in a controller:
Gate.allows('update', post);    // boolean
Gate.authorize('update', post); // throws ForbiddenError if denied

// Explicit policy form:
Gate.via(PostPolicy).allows('update', post);

Constructors

Constructor

new GateService(): GateService

Returns

GateService

Checking

allows()

allows(ability, model?): boolean

Defined in: auth/src/GateService.ts:93

Check an ability and return a boolean. Resolves through before-hooks, closure abilities, a registered policy for model's class, then the user's relational permissions. Never throws — any error in resolution denies.

Parameters

ability

string

The ability name to check.

model?

object

Optional model instance; selects the policy and is passed to the ability.

Returns

boolean

true when access is allowed.

authorize()

authorize(ability, model?): void

Defined in: auth/src/GateService.ts:105

Assert an ability, throwing when denied. On denial emits AuthorizationDenied.

Parameters

ability

string

The ability name to check.

model?

object

Optional model instance passed to the policy/ability.

Returns

void

Throws

when the ability is denied.

allowsAsync()

allowsAsync(ability, model?): Promise<boolean>

Defined in: auth/src/GateService.ts:124

Async variants of allows / authorize — await policy methods (and closure abilities) that return a Promise<boolean>. Use these when an ability needs to hit the database (e.g. a membership/admin lookup); the sync forms treat a returned Promise as truthy and would wrongly allow.

Parameters

ability

string

model?

object

Returns

Promise<boolean>

(allowsAsync) a promise resolving to true when allowed.

Throws

(authorizeAsync) when the ability is denied.

authorizeAsync()

authorizeAsync(ability, model?): Promise<void>

Defined in: auth/src/GateService.ts:129

Parameters

ability

string

model?

object

Returns

Promise<void>

Defining

registerPolicy()

registerPolicy<M>(ModelClass, PolicyClass): void

Defined in: auth/src/GateService.ts:51

Map a model class to the Policy that authorizes it. Once registered, allows/authorize with an instance of that model dispatch to the policy method named after the ability.

Type Parameters

M

M

Parameters

ModelClass

(...args) => M

The model constructor to authorize.

PolicyClass

PolicyClass<M>

The policy class whose methods are the abilities.

Returns

void

defineAbility()

defineAbility(ability, callback): this

Defined in: auth/src/GateService.ts:63

Parameters

ability

string

The ability name (e.g. 'update-post').

callback

AbilityCallback

Receives the current user and optional model; returns whether access is allowed.

Returns

this

before()

before(hook): this

Defined in: auth/src/GateService.ts:76

Register a before-hook that runs ahead of every check. Returning true/false short-circuits the check (grant/deny); returning undefined defers to the normal resolution. Returns this for chaining. See superAdmin for a common use.

Parameters

hook

BeforeHook

Returns

this

superAdmin()

superAdmin(role?): this

Defined in: auth/src/GateService.ts:222

Grant a role unconditional access via a before-hook (e.g. a super admin).

Parameters

role?

string = "super-admin"

The role granted unconditional access. Default 'super-admin'.

Returns

this

this for chaining.

Example

Gate.superAdmin();           // users with the 'super-admin' role bypass every check
Gate.superAdmin('owner');

Policies

via()

via<M>(PolicyClass): object

Defined in: auth/src/GateService.ts:152

Authorize against a specific Policy class explicitly, bypassing the model→policy registry. Returns an object with allows (boolean) and authorize (throws ForbiddenError on denial). model is optional for class-level abilities such as create.

Type Parameters

M

M

Parameters

PolicyClass

PolicyClass<M>

The policy class to dispatch to.

Returns

object

allows

allows: (ability, model?) => boolean

Parameters

ability

string

model?

M

Returns

boolean

authorize

authorize: (ability, model?) => void

Parameters

ability

string

model?

M

Returns

void

Example

Gate.via(PostPolicy).allows('update', post);
Gate.via(PostPolicy).authorize('create'); // no model instance needed