@plinthjs/authorization 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,271 @@
1
+ /**
2
+ * Authorization responses — the Laravel `Illuminate\Auth\Access\Response` equivalent. A
3
+ * {@link Response} is the rich result of an authorization check: it carries an allowed/denied
4
+ * verdict plus an optional human-readable message, an optional error code, and (for denials) an
5
+ * optional HTTP status. Gate check callbacks may return a bare boolean (which the {@link Gate}
6
+ * normalizes into a {@link Response}) or build one explicitly via
7
+ * {@link Response.allow}/{@link Response.deny}/{@link Response.denyWithStatus} to attach a message
8
+ * the UI can surface or a status the HTTP layer should render (e.g. a `404` that hides existence).
9
+ */
10
+ /**
11
+ * `Response` — the `Illuminate\Auth\Access\Response` equivalent. Immutable result of an
12
+ * authorization decision: it is either allowed or denied, optionally with a message, an error
13
+ * code, and (when denied) an HTTP status override. Construct one through the
14
+ * {@link Response.allow}/{@link Response.deny}/{@link Response.denyWithStatus} factories rather
15
+ * than the constructor.
16
+ */
17
+ declare class Response {
18
+ private readonly granted;
19
+ private readonly msg;
20
+ private readonly errCode;
21
+ private readonly statusCode;
22
+ /**
23
+ * @param granted Whether the decision allows the action.
24
+ * @param msg Optional human-readable explanation (typically used on denial).
25
+ * @param errCode Optional machine-readable error code attached to the decision.
26
+ * @param statusCode Optional HTTP status a denial should render as (defaults to `403` downstream).
27
+ */
28
+ private constructor();
29
+ /**
30
+ * Build an allowing response — the `Response::allow` equivalent. The optional `message` and
31
+ * `code` are preserved so callers can surface a reason even on success.
32
+ */
33
+ static allow(message?: string, code?: string | number): Response;
34
+ /**
35
+ * Build a denying response — the `Response::deny` equivalent. The optional `message` and `code`
36
+ * describe why the action was refused.
37
+ */
38
+ static deny(message?: string, code?: string | number): Response;
39
+ /**
40
+ * Build a denying response that should render with the given HTTP status — the
41
+ * `Response::denyWithStatus` equivalent. The status is carried onto the
42
+ * {@link AuthorizationError} thrown by {@link Response.authorize}, so the HTTP exception handler
43
+ * renders e.g. a `404` instead of the default `403`.
44
+ */
45
+ static denyWithStatus(status: number, message?: string, code?: string | number): Response;
46
+ /**
47
+ * Build a denying response that renders as a `404 Not Found` — the `Response::denyAsNotFound`
48
+ * equivalent, used to hide a resource's existence from unauthorized users.
49
+ */
50
+ static denyAsNotFound(message?: string, code?: string | number): Response;
51
+ /** Whether the decision allows the action — the `Response::allowed` equivalent. */
52
+ allowed(): boolean;
53
+ /** Whether the decision denies the action — the `Response::denied` equivalent. */
54
+ denied(): boolean;
55
+ /** The attached message, or `null` when none was given — the `Response::message` equivalent. */
56
+ message(): string | null;
57
+ /** The attached error code, or `null` when none was given — the `Response::code` equivalent. */
58
+ code(): string | number | null;
59
+ /**
60
+ * The HTTP status a denial should render as, or `null` when none was set (denials default to
61
+ * `403` downstream) — the `Response::status` equivalent.
62
+ */
63
+ status(): number | null;
64
+ /**
65
+ * Assert this response allows the action — the `Response::authorize` equivalent. Returns the
66
+ * response (for chaining) when allowed; otherwise throws so a denial bubbles up to the caller.
67
+ *
68
+ * @throws {AuthorizationError} when {@link Response.denied}, carrying this response (and its
69
+ * status, when one was set via {@link Response.denyWithStatus}).
70
+ */
71
+ authorize(): this;
72
+ }
73
+
74
+ /**
75
+ * The authorization failure — the Laravel `Illuminate\Auth\Access\AuthorizationException` equivalent.
76
+ * Thrown by {@link Gate.authorize}/{@link Response.authorize} when an ability is denied. It carries a
77
+ * structural `status` (read by `@plinthjs/http`'s exception handler so the response renders with the
78
+ * right code — `403` by default, or whatever the denying {@link Response} set via `denyWithStatus`/
79
+ * `denyAsNotFound`) alongside the response and its error code, so callers can inspect why.
80
+ */
81
+
82
+ /**
83
+ * `AuthorizationError` — the `Illuminate\Auth\Access\AuthorizationException` equivalent. Carries the
84
+ * denying {@link Response} (so callers can read its message/code) and a structural `status` so
85
+ * `@plinthjs/http`'s handler renders it without this package depending on the HTTP layer. The status is
86
+ * the response's own (e.g. `404` from `denyAsNotFound`), falling back to the Laravel `403`.
87
+ */
88
+ declare class AuthorizationError extends Error {
89
+ /** The HTTP status this renders as — the denying response's status, or the default `403`. */
90
+ readonly status: number;
91
+ /** The error code attached to the denying {@link Response}, when any. */
92
+ readonly code: string | number | null;
93
+ /** The full denying {@link Response} that triggered this error. */
94
+ readonly response: Response;
95
+ /**
96
+ * @param response The denying {@link Response}; its message becomes the error message.
97
+ */
98
+ constructor(response: Response);
99
+ }
100
+
101
+ /**
102
+ * The authorization gate — the Laravel `Illuminate\Auth\Access\Gate` equivalent. A {@link Gate}
103
+ * holds the registry of named abilities (defined via callbacks) and resource policies, then answers
104
+ * authorization questions about them: `allows`/`denies`/`check` return booleans, `inspect` returns
105
+ * the raw {@link Response} (including any HTTP status a denial set via `denyWithStatus`),
106
+ * `authorize` throws an {@link AuthorizationError} on denial, and `allowIf`/`denyIf` authorize
107
+ * ad-hoc conditions. `has` reports whether abilities are defined and `abilities` lists them.
108
+ * `before` hooks can short-circuit a decision (e.g. super-admins) and `after` hooks fill in a
109
+ * verdict when nothing else decided. Guests (a `null`/`undefined` user) are denied unless a
110
+ * `before` allows them.
111
+ */
112
+
113
+ /**
114
+ * The result an ability/hook callback may return. A bare boolean is normalized into a
115
+ * {@link Response}; `undefined` from a hook means "no opinion — keep resolving".
116
+ */
117
+ type AbilityResult = boolean | Response;
118
+ /**
119
+ * An ability callback — the closure passed to `Gate::define`. Receives the authenticated user
120
+ * followed by the check's extra arguments and returns a boolean or {@link Response}. The gate denies
121
+ * guests before this runs, so `user` is always a real user here. The extra args are typed loosely so
122
+ * callbacks may declare their own concrete parameter types (e.g. `(user, post: Post) => ...`).
123
+ */
124
+ type AbilityCallback<User> = (user: User, ...args: any[]) => AbilityResult;
125
+ /**
126
+ * A `before` hook — the `Gate::before` equivalent. Runs ahead of every check; returning a boolean
127
+ * or {@link Response} short-circuits the decision, while `undefined` defers to the ability/policy.
128
+ */
129
+ type BeforeCallback<User> = (user: User, ability: string, args: unknown[]) => AbilityResult | undefined;
130
+ /**
131
+ * An `after` hook — the `Gate::after` equivalent. Runs only when no `before` hook or ability/policy
132
+ * produced a decision; returning a boolean or {@link Response} supplies the verdict.
133
+ */
134
+ type AfterCallback<User> = (user: User, ability: string, args: unknown[]) => AbilityResult | undefined;
135
+ /**
136
+ * The condition accepted by {@link Gate.allowIf}/{@link Gate.denyIf} — a boolean, a prebuilt
137
+ * {@link Response}, or a callback receiving the gate's default user (set via {@link Gate.forUser};
138
+ * `null`/`undefined` for guests) and returning either.
139
+ */
140
+ type GateCondition<User> = AbilityResult | ((user: User | null | undefined) => AbilityResult);
141
+ /** A resource policy — a plain object (or class instance) whose methods are ability callbacks. */
142
+ type Policy<User> = Record<string, AbilityCallback<User>>;
143
+ /** A key used to look up a policy: either a string tag or a class constructor. */
144
+ type PolicyKey = string | (new (...args: never[]) => unknown);
145
+ /**
146
+ * `Gate` — the `Illuminate\Auth\Access\Gate` equivalent. Registers abilities and policies, then
147
+ * resolves authorization decisions for a user. The user type is generic; pass the application's
148
+ * user shape (it always includes the guest sentinels `null`/`undefined`).
149
+ *
150
+ * @typeParam User The authenticated user shape; checks may also receive `null`/`undefined` guests.
151
+ */
152
+ declare class Gate<User = unknown> {
153
+ private readonly defaultUser?;
154
+ private readonly abilityCallbacks;
155
+ private readonly policies;
156
+ private readonly beforeCallbacks;
157
+ private readonly afterCallbacks;
158
+ /**
159
+ * @param defaultUser The user implicitly used when a check omits one — set by {@link Gate.forUser}.
160
+ */
161
+ constructor(defaultUser?: User | null | undefined);
162
+ /**
163
+ * Define a named ability — the `Gate::define` equivalent. The callback receives the user and the
164
+ * check's extra arguments and returns a boolean or {@link Response}. Redefining replaces it.
165
+ */
166
+ define(ability: string, callback: AbilityCallback<User>): this;
167
+ /**
168
+ * Whether every given ability has been defined (directly via {@link Gate.define} or
169
+ * {@link Gate.resource}) — the `Gate::has` equivalent. Policy methods are not consulted, matching
170
+ * Laravel.
171
+ */
172
+ has(ability: string | readonly string[]): boolean;
173
+ /** The names of every defined ability — the `Gate::abilities` listing. */
174
+ abilities(): string[];
175
+ /**
176
+ * Register a policy for a resource key — the `Gate::policy` equivalent. `resourceKey` is either a
177
+ * class constructor or a string tag; when an ability is not defined directly, the gate resolves it
178
+ * to `policy[ability](user, resource, ...args)` using the matching policy.
179
+ */
180
+ policy(resourceKey: PolicyKey, policy: Policy<User>): this;
181
+ /**
182
+ * Register the standard resource abilities for a policy — the `Gate::resource` equivalent. Defines
183
+ * `{name}.viewAny`, `{name}.view`, `{name}.create`, `{name}.update`, and `{name}.delete` (override
184
+ * the list via `abilities`), each dispatching to the matching method on `policy`. The policy's
185
+ * method receives the user and the check's extra arguments, e.g. `allows('posts.update', user, post)`
186
+ * routes to `policy.update(user, post)`. Methods absent from the policy resolve to a denial.
187
+ */
188
+ resource(name: string, policy: Policy<User>, abilities?: readonly string[]): this;
189
+ /**
190
+ * Register a `before` hook — the `Gate::before` equivalent. Hooks run in registration order ahead
191
+ * of every check; the first to return a boolean/{@link Response} decides, `undefined` defers.
192
+ */
193
+ before(callback: BeforeCallback<User | null | undefined>): this;
194
+ /**
195
+ * Register an `after` hook — the `Gate::after` equivalent. Hooks run only when nothing else
196
+ * decided; the first to return a boolean/{@link Response} supplies the verdict.
197
+ */
198
+ after(callback: AfterCallback<User | null | undefined>): this;
199
+ /**
200
+ * Return a gate bound to `user` as its default — the `Gate::forUser` equivalent. The returned gate
201
+ * shares this gate's abilities, policies, and hooks (by reference) so later registrations are seen.
202
+ */
203
+ forUser(user: User | null | undefined): Gate<User>;
204
+ /**
205
+ * Resolve the raw {@link Response} for an ability — the `Gate::inspect` equivalent. Runs `before`
206
+ * hooks (short-circuiting), then the ability or resolved policy method, then `after` hooks. A guest
207
+ * with no allowing decision is denied. When no callback exists at all the result is a denial.
208
+ */
209
+ inspect(ability: string, user?: User | null | undefined, ...args: unknown[]): Response;
210
+ /** Whether the ability is allowed — the `Gate::allows` equivalent. */
211
+ allows(ability: string, user?: User | null, ...args: unknown[]): boolean;
212
+ /** Whether the ability is denied — the `Gate::denies` equivalent. */
213
+ denies(ability: string, user?: User | null, ...args: unknown[]): boolean;
214
+ /** Alias of {@link Gate.allows} — the `Gate::check` equivalent. */
215
+ check(ability: string, user?: User | null, ...args: unknown[]): boolean;
216
+ /** Whether *any* of the abilities is allowed — the `Gate::any` equivalent. */
217
+ any(abilities: string[], user?: User | null, ...args: unknown[]): boolean;
218
+ /** Whether *none* of the abilities is allowed — the `Gate::none` equivalent. */
219
+ none(abilities: string[], user?: User | null, ...args: unknown[]): boolean;
220
+ /**
221
+ * Assert the ability and return its allowing {@link Response} — the `Gate::authorize` equivalent.
222
+ *
223
+ * @throws {AuthorizationError} when the ability is denied, carrying the denying response.
224
+ */
225
+ authorize(ability: string, user?: User | null, ...args: unknown[]): Response;
226
+ /**
227
+ * Authorize when an ad-hoc condition holds — the `Gate::allowIf` equivalent. `condition` is a
228
+ * boolean, a {@link Response}, or a callback receiving the gate's default user. Returns the
229
+ * allowing {@link Response}; a falsy/denying condition throws an {@link AuthorizationError}
230
+ * carrying `message`/`code`.
231
+ */
232
+ allowIf(condition: GateCondition<User>, message?: string, code?: string | number): Response;
233
+ /**
234
+ * Deny when an ad-hoc condition holds — the `Gate::denyIf` equivalent. The inverse of
235
+ * {@link Gate.allowIf}: a truthy condition throws, a falsy one authorizes.
236
+ */
237
+ denyIf(condition: GateCondition<User>, message?: string, code?: string | number): Response;
238
+ /** Evaluate an ad-hoc condition and authorize it — Laravel's `authorizeOnDemand`. */
239
+ private authorizeOnDemand;
240
+ /**
241
+ * Resolve the callback for an ability: a directly defined one wins, otherwise look for a policy
242
+ * keyed by the first argument (a string tag or the resource's constructor) exposing the ability.
243
+ */
244
+ private resolve;
245
+ /**
246
+ * Find the policy registered for a model — the `Gate::getPolicyFor` equivalent. Resolves a string
247
+ * tag, a class constructor, or an instance (by its constructor) to its policy, or `undefined` when
248
+ * none is registered.
249
+ */
250
+ getPolicyFor(model: unknown): Policy<User> | undefined;
251
+ }
252
+
253
+ /**
254
+ * @plinthjs/authorization — the Laravel `Illuminate\Auth\Access` equivalent.
255
+ *
256
+ * A {@link Gate} that registers named abilities and resource {@link Policy} objects, then answers
257
+ * authorization questions: `allows`/`denies`/`check` booleans, `inspect` for the raw {@link Response},
258
+ * `any`/`none` across several abilities, and `authorize` which throws {@link AuthorizationError} on
259
+ * denial. `resource` registers the standard `viewAny`/`view`/`create`/`update`/`delete` abilities for
260
+ * a policy, `getPolicyFor` looks a policy up by model, `has`/`abilities` report what is defined,
261
+ * `allowIf`/`denyIf` authorize ad-hoc conditions, `before`/`after` hooks short-circuit or backfill
262
+ * decisions, `forUser` binds a default user, and guests (`null`/`undefined`) are denied unless a
263
+ * `before` hook allows them. {@link Response} carries an allow/deny verdict plus an optional message,
264
+ * code, and (via `denyWithStatus`/`denyAsNotFound`) an HTTP status for the denial, and its
265
+ * `authorize` throws when denied. {@link AuthorizationError} carries a structural `status` (the
266
+ * response's, defaulting to `403`) so `@plinthjs/http`'s handler renders it correctly.
267
+ */
268
+ /** The Mason version this build of `authorization` ships with. */
269
+ declare const VERSION = "0.1.0";
270
+
271
+ export { type AbilityCallback, type AbilityResult, type AfterCallback, AuthorizationError, type BeforeCallback, Gate, type GateCondition, type Policy, Response, VERSION };
@@ -0,0 +1,271 @@
1
+ /**
2
+ * Authorization responses — the Laravel `Illuminate\Auth\Access\Response` equivalent. A
3
+ * {@link Response} is the rich result of an authorization check: it carries an allowed/denied
4
+ * verdict plus an optional human-readable message, an optional error code, and (for denials) an
5
+ * optional HTTP status. Gate check callbacks may return a bare boolean (which the {@link Gate}
6
+ * normalizes into a {@link Response}) or build one explicitly via
7
+ * {@link Response.allow}/{@link Response.deny}/{@link Response.denyWithStatus} to attach a message
8
+ * the UI can surface or a status the HTTP layer should render (e.g. a `404` that hides existence).
9
+ */
10
+ /**
11
+ * `Response` — the `Illuminate\Auth\Access\Response` equivalent. Immutable result of an
12
+ * authorization decision: it is either allowed or denied, optionally with a message, an error
13
+ * code, and (when denied) an HTTP status override. Construct one through the
14
+ * {@link Response.allow}/{@link Response.deny}/{@link Response.denyWithStatus} factories rather
15
+ * than the constructor.
16
+ */
17
+ declare class Response {
18
+ private readonly granted;
19
+ private readonly msg;
20
+ private readonly errCode;
21
+ private readonly statusCode;
22
+ /**
23
+ * @param granted Whether the decision allows the action.
24
+ * @param msg Optional human-readable explanation (typically used on denial).
25
+ * @param errCode Optional machine-readable error code attached to the decision.
26
+ * @param statusCode Optional HTTP status a denial should render as (defaults to `403` downstream).
27
+ */
28
+ private constructor();
29
+ /**
30
+ * Build an allowing response — the `Response::allow` equivalent. The optional `message` and
31
+ * `code` are preserved so callers can surface a reason even on success.
32
+ */
33
+ static allow(message?: string, code?: string | number): Response;
34
+ /**
35
+ * Build a denying response — the `Response::deny` equivalent. The optional `message` and `code`
36
+ * describe why the action was refused.
37
+ */
38
+ static deny(message?: string, code?: string | number): Response;
39
+ /**
40
+ * Build a denying response that should render with the given HTTP status — the
41
+ * `Response::denyWithStatus` equivalent. The status is carried onto the
42
+ * {@link AuthorizationError} thrown by {@link Response.authorize}, so the HTTP exception handler
43
+ * renders e.g. a `404` instead of the default `403`.
44
+ */
45
+ static denyWithStatus(status: number, message?: string, code?: string | number): Response;
46
+ /**
47
+ * Build a denying response that renders as a `404 Not Found` — the `Response::denyAsNotFound`
48
+ * equivalent, used to hide a resource's existence from unauthorized users.
49
+ */
50
+ static denyAsNotFound(message?: string, code?: string | number): Response;
51
+ /** Whether the decision allows the action — the `Response::allowed` equivalent. */
52
+ allowed(): boolean;
53
+ /** Whether the decision denies the action — the `Response::denied` equivalent. */
54
+ denied(): boolean;
55
+ /** The attached message, or `null` when none was given — the `Response::message` equivalent. */
56
+ message(): string | null;
57
+ /** The attached error code, or `null` when none was given — the `Response::code` equivalent. */
58
+ code(): string | number | null;
59
+ /**
60
+ * The HTTP status a denial should render as, or `null` when none was set (denials default to
61
+ * `403` downstream) — the `Response::status` equivalent.
62
+ */
63
+ status(): number | null;
64
+ /**
65
+ * Assert this response allows the action — the `Response::authorize` equivalent. Returns the
66
+ * response (for chaining) when allowed; otherwise throws so a denial bubbles up to the caller.
67
+ *
68
+ * @throws {AuthorizationError} when {@link Response.denied}, carrying this response (and its
69
+ * status, when one was set via {@link Response.denyWithStatus}).
70
+ */
71
+ authorize(): this;
72
+ }
73
+
74
+ /**
75
+ * The authorization failure — the Laravel `Illuminate\Auth\Access\AuthorizationException` equivalent.
76
+ * Thrown by {@link Gate.authorize}/{@link Response.authorize} when an ability is denied. It carries a
77
+ * structural `status` (read by `@plinthjs/http`'s exception handler so the response renders with the
78
+ * right code — `403` by default, or whatever the denying {@link Response} set via `denyWithStatus`/
79
+ * `denyAsNotFound`) alongside the response and its error code, so callers can inspect why.
80
+ */
81
+
82
+ /**
83
+ * `AuthorizationError` — the `Illuminate\Auth\Access\AuthorizationException` equivalent. Carries the
84
+ * denying {@link Response} (so callers can read its message/code) and a structural `status` so
85
+ * `@plinthjs/http`'s handler renders it without this package depending on the HTTP layer. The status is
86
+ * the response's own (e.g. `404` from `denyAsNotFound`), falling back to the Laravel `403`.
87
+ */
88
+ declare class AuthorizationError extends Error {
89
+ /** The HTTP status this renders as — the denying response's status, or the default `403`. */
90
+ readonly status: number;
91
+ /** The error code attached to the denying {@link Response}, when any. */
92
+ readonly code: string | number | null;
93
+ /** The full denying {@link Response} that triggered this error. */
94
+ readonly response: Response;
95
+ /**
96
+ * @param response The denying {@link Response}; its message becomes the error message.
97
+ */
98
+ constructor(response: Response);
99
+ }
100
+
101
+ /**
102
+ * The authorization gate — the Laravel `Illuminate\Auth\Access\Gate` equivalent. A {@link Gate}
103
+ * holds the registry of named abilities (defined via callbacks) and resource policies, then answers
104
+ * authorization questions about them: `allows`/`denies`/`check` return booleans, `inspect` returns
105
+ * the raw {@link Response} (including any HTTP status a denial set via `denyWithStatus`),
106
+ * `authorize` throws an {@link AuthorizationError} on denial, and `allowIf`/`denyIf` authorize
107
+ * ad-hoc conditions. `has` reports whether abilities are defined and `abilities` lists them.
108
+ * `before` hooks can short-circuit a decision (e.g. super-admins) and `after` hooks fill in a
109
+ * verdict when nothing else decided. Guests (a `null`/`undefined` user) are denied unless a
110
+ * `before` allows them.
111
+ */
112
+
113
+ /**
114
+ * The result an ability/hook callback may return. A bare boolean is normalized into a
115
+ * {@link Response}; `undefined` from a hook means "no opinion — keep resolving".
116
+ */
117
+ type AbilityResult = boolean | Response;
118
+ /**
119
+ * An ability callback — the closure passed to `Gate::define`. Receives the authenticated user
120
+ * followed by the check's extra arguments and returns a boolean or {@link Response}. The gate denies
121
+ * guests before this runs, so `user` is always a real user here. The extra args are typed loosely so
122
+ * callbacks may declare their own concrete parameter types (e.g. `(user, post: Post) => ...`).
123
+ */
124
+ type AbilityCallback<User> = (user: User, ...args: any[]) => AbilityResult;
125
+ /**
126
+ * A `before` hook — the `Gate::before` equivalent. Runs ahead of every check; returning a boolean
127
+ * or {@link Response} short-circuits the decision, while `undefined` defers to the ability/policy.
128
+ */
129
+ type BeforeCallback<User> = (user: User, ability: string, args: unknown[]) => AbilityResult | undefined;
130
+ /**
131
+ * An `after` hook — the `Gate::after` equivalent. Runs only when no `before` hook or ability/policy
132
+ * produced a decision; returning a boolean or {@link Response} supplies the verdict.
133
+ */
134
+ type AfterCallback<User> = (user: User, ability: string, args: unknown[]) => AbilityResult | undefined;
135
+ /**
136
+ * The condition accepted by {@link Gate.allowIf}/{@link Gate.denyIf} — a boolean, a prebuilt
137
+ * {@link Response}, or a callback receiving the gate's default user (set via {@link Gate.forUser};
138
+ * `null`/`undefined` for guests) and returning either.
139
+ */
140
+ type GateCondition<User> = AbilityResult | ((user: User | null | undefined) => AbilityResult);
141
+ /** A resource policy — a plain object (or class instance) whose methods are ability callbacks. */
142
+ type Policy<User> = Record<string, AbilityCallback<User>>;
143
+ /** A key used to look up a policy: either a string tag or a class constructor. */
144
+ type PolicyKey = string | (new (...args: never[]) => unknown);
145
+ /**
146
+ * `Gate` — the `Illuminate\Auth\Access\Gate` equivalent. Registers abilities and policies, then
147
+ * resolves authorization decisions for a user. The user type is generic; pass the application's
148
+ * user shape (it always includes the guest sentinels `null`/`undefined`).
149
+ *
150
+ * @typeParam User The authenticated user shape; checks may also receive `null`/`undefined` guests.
151
+ */
152
+ declare class Gate<User = unknown> {
153
+ private readonly defaultUser?;
154
+ private readonly abilityCallbacks;
155
+ private readonly policies;
156
+ private readonly beforeCallbacks;
157
+ private readonly afterCallbacks;
158
+ /**
159
+ * @param defaultUser The user implicitly used when a check omits one — set by {@link Gate.forUser}.
160
+ */
161
+ constructor(defaultUser?: User | null | undefined);
162
+ /**
163
+ * Define a named ability — the `Gate::define` equivalent. The callback receives the user and the
164
+ * check's extra arguments and returns a boolean or {@link Response}. Redefining replaces it.
165
+ */
166
+ define(ability: string, callback: AbilityCallback<User>): this;
167
+ /**
168
+ * Whether every given ability has been defined (directly via {@link Gate.define} or
169
+ * {@link Gate.resource}) — the `Gate::has` equivalent. Policy methods are not consulted, matching
170
+ * Laravel.
171
+ */
172
+ has(ability: string | readonly string[]): boolean;
173
+ /** The names of every defined ability — the `Gate::abilities` listing. */
174
+ abilities(): string[];
175
+ /**
176
+ * Register a policy for a resource key — the `Gate::policy` equivalent. `resourceKey` is either a
177
+ * class constructor or a string tag; when an ability is not defined directly, the gate resolves it
178
+ * to `policy[ability](user, resource, ...args)` using the matching policy.
179
+ */
180
+ policy(resourceKey: PolicyKey, policy: Policy<User>): this;
181
+ /**
182
+ * Register the standard resource abilities for a policy — the `Gate::resource` equivalent. Defines
183
+ * `{name}.viewAny`, `{name}.view`, `{name}.create`, `{name}.update`, and `{name}.delete` (override
184
+ * the list via `abilities`), each dispatching to the matching method on `policy`. The policy's
185
+ * method receives the user and the check's extra arguments, e.g. `allows('posts.update', user, post)`
186
+ * routes to `policy.update(user, post)`. Methods absent from the policy resolve to a denial.
187
+ */
188
+ resource(name: string, policy: Policy<User>, abilities?: readonly string[]): this;
189
+ /**
190
+ * Register a `before` hook — the `Gate::before` equivalent. Hooks run in registration order ahead
191
+ * of every check; the first to return a boolean/{@link Response} decides, `undefined` defers.
192
+ */
193
+ before(callback: BeforeCallback<User | null | undefined>): this;
194
+ /**
195
+ * Register an `after` hook — the `Gate::after` equivalent. Hooks run only when nothing else
196
+ * decided; the first to return a boolean/{@link Response} supplies the verdict.
197
+ */
198
+ after(callback: AfterCallback<User | null | undefined>): this;
199
+ /**
200
+ * Return a gate bound to `user` as its default — the `Gate::forUser` equivalent. The returned gate
201
+ * shares this gate's abilities, policies, and hooks (by reference) so later registrations are seen.
202
+ */
203
+ forUser(user: User | null | undefined): Gate<User>;
204
+ /**
205
+ * Resolve the raw {@link Response} for an ability — the `Gate::inspect` equivalent. Runs `before`
206
+ * hooks (short-circuiting), then the ability or resolved policy method, then `after` hooks. A guest
207
+ * with no allowing decision is denied. When no callback exists at all the result is a denial.
208
+ */
209
+ inspect(ability: string, user?: User | null | undefined, ...args: unknown[]): Response;
210
+ /** Whether the ability is allowed — the `Gate::allows` equivalent. */
211
+ allows(ability: string, user?: User | null, ...args: unknown[]): boolean;
212
+ /** Whether the ability is denied — the `Gate::denies` equivalent. */
213
+ denies(ability: string, user?: User | null, ...args: unknown[]): boolean;
214
+ /** Alias of {@link Gate.allows} — the `Gate::check` equivalent. */
215
+ check(ability: string, user?: User | null, ...args: unknown[]): boolean;
216
+ /** Whether *any* of the abilities is allowed — the `Gate::any` equivalent. */
217
+ any(abilities: string[], user?: User | null, ...args: unknown[]): boolean;
218
+ /** Whether *none* of the abilities is allowed — the `Gate::none` equivalent. */
219
+ none(abilities: string[], user?: User | null, ...args: unknown[]): boolean;
220
+ /**
221
+ * Assert the ability and return its allowing {@link Response} — the `Gate::authorize` equivalent.
222
+ *
223
+ * @throws {AuthorizationError} when the ability is denied, carrying the denying response.
224
+ */
225
+ authorize(ability: string, user?: User | null, ...args: unknown[]): Response;
226
+ /**
227
+ * Authorize when an ad-hoc condition holds — the `Gate::allowIf` equivalent. `condition` is a
228
+ * boolean, a {@link Response}, or a callback receiving the gate's default user. Returns the
229
+ * allowing {@link Response}; a falsy/denying condition throws an {@link AuthorizationError}
230
+ * carrying `message`/`code`.
231
+ */
232
+ allowIf(condition: GateCondition<User>, message?: string, code?: string | number): Response;
233
+ /**
234
+ * Deny when an ad-hoc condition holds — the `Gate::denyIf` equivalent. The inverse of
235
+ * {@link Gate.allowIf}: a truthy condition throws, a falsy one authorizes.
236
+ */
237
+ denyIf(condition: GateCondition<User>, message?: string, code?: string | number): Response;
238
+ /** Evaluate an ad-hoc condition and authorize it — Laravel's `authorizeOnDemand`. */
239
+ private authorizeOnDemand;
240
+ /**
241
+ * Resolve the callback for an ability: a directly defined one wins, otherwise look for a policy
242
+ * keyed by the first argument (a string tag or the resource's constructor) exposing the ability.
243
+ */
244
+ private resolve;
245
+ /**
246
+ * Find the policy registered for a model — the `Gate::getPolicyFor` equivalent. Resolves a string
247
+ * tag, a class constructor, or an instance (by its constructor) to its policy, or `undefined` when
248
+ * none is registered.
249
+ */
250
+ getPolicyFor(model: unknown): Policy<User> | undefined;
251
+ }
252
+
253
+ /**
254
+ * @plinthjs/authorization — the Laravel `Illuminate\Auth\Access` equivalent.
255
+ *
256
+ * A {@link Gate} that registers named abilities and resource {@link Policy} objects, then answers
257
+ * authorization questions: `allows`/`denies`/`check` booleans, `inspect` for the raw {@link Response},
258
+ * `any`/`none` across several abilities, and `authorize` which throws {@link AuthorizationError} on
259
+ * denial. `resource` registers the standard `viewAny`/`view`/`create`/`update`/`delete` abilities for
260
+ * a policy, `getPolicyFor` looks a policy up by model, `has`/`abilities` report what is defined,
261
+ * `allowIf`/`denyIf` authorize ad-hoc conditions, `before`/`after` hooks short-circuit or backfill
262
+ * decisions, `forUser` binds a default user, and guests (`null`/`undefined`) are denied unless a
263
+ * `before` hook allows them. {@link Response} carries an allow/deny verdict plus an optional message,
264
+ * code, and (via `denyWithStatus`/`denyAsNotFound`) an HTTP status for the denial, and its
265
+ * `authorize` throws when denied. {@link AuthorizationError} carries a structural `status` (the
266
+ * response's, defaulting to `403`) so `@plinthjs/http`'s handler renders it correctly.
267
+ */
268
+ /** The Mason version this build of `authorization` ships with. */
269
+ declare const VERSION = "0.1.0";
270
+
271
+ export { type AbilityCallback, type AbilityResult, type AfterCallback, AuthorizationError, type BeforeCallback, Gate, type GateCondition, type Policy, Response, VERSION };