@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/LICENSE +1 -1
- package/README.md +1 -1
- package/dist/index.cjs +31 -32
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +47 -48
- package/dist/index.d.ts +47 -48
- package/dist/index.js +31 -32
- package/dist/index.js.map +1 -1
- package/package.json +7 -8
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Authorization responses
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
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
|
|
51
|
+
/** Whether the decision allows the action - the `Response::allowed` equivalent. */
|
|
52
52
|
allowed(): boolean;
|
|
53
|
-
/** Whether the decision denies the action
|
|
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
|
|
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
|
|
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)
|
|
61
|
+
* `403` downstream) - the `Response::status` equivalent.
|
|
62
62
|
*/
|
|
63
63
|
status(): number | null;
|
|
64
64
|
/**
|
|
65
|
-
* Assert this response allows the action
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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})
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
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
|
|
51
|
+
/** Whether the decision allows the action - the `Response::allowed` equivalent. */
|
|
52
52
|
allowed(): boolean;
|
|
53
|
-
/** Whether the decision denies the action
|
|
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
|
|
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
|
|
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)
|
|
61
|
+
* `403` downstream) - the `Response::status` equivalent.
|
|
62
62
|
*/
|
|
63
63
|
status(): number | null;
|
|
64
64
|
/**
|
|
65
|
-
* Assert this response allows the action
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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})
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 };
|