@plinthjs/authorization 0.1.0 → 0.1.2

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