@nmnmcc/ability 0.3.0 → 1.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 Authorization tools for Effect programs. Authorization means the work of
 deciding if a principal may do an act. A principal is the one who asks: a
-person, a user token, or a Bot.
+person, an API token, or another service.
 
 The library is made with [Effect](https://effect.website) only:
 
@@ -140,35 +140,35 @@ There are two ways to make a resource:
 
 ```ts
 // A Schema class. Its body may have its own getters and methods.
-class Bot extends Resource.Class<Bot>()("Bot", {
+class Document extends Resource.Class<Document>()("Document", {
 	actions: ["read", "update"],
-	fields: { id: Schema.String, ownerUserId: Schema.NullOr(Schema.String) },
+	fields: { id: Schema.String, ownerId: Schema.NullOr(Schema.String) },
 }) {
-	get shared() {
-		return this.ownerUserId === null
+	get orphaned() {
+		return this.ownerId === null
 	}
 }
 
 // Plain objects with a `_tag` field.
-const Trigger = Resource.make("Trigger", {
+const Comment = Resource.make("Comment", {
 	actions: ["read", "write"],
-	fields: { id: Schema.String, enabled: Schema.Boolean },
+	fields: { id: Schema.String, hidden: Schema.Boolean },
 })
-const trigger = Trigger.make({ id: "t1", enabled: true })
+const comment = Comment.make({ id: "c1", hidden: false })
 ```
 
 A resource may have a path. The path puts the resource in a tree, so one rule
 can cover a part of the tree:
 
 ```ts
-class Bot extends Resource.Class<Bot>()("Bot", {
+class Document extends Resource.Class<Document>()("Document", {
 	actions: ["read", "update"],
 	fields: {
 		id: Schema.String,
 		organizationId: Schema.String,
-		ownerUserId: Schema.NullOr(Schema.String),
+		teamId: Schema.NullOr(Schema.String),
 	},
-	path: (f) => ["org", f.organizationId, "user", f.ownerUserId, "bot", f.id],
+	path: (f) => ["org", f.organizationId, "team", f.teamId, "doc", f.id],
 }) {}
 
 // Every resource of the organization of the principal.
@@ -184,14 +184,20 @@ _.allow("read", "*", {
 - The action `"*"` means every action. The resource `"*"` means every resource.
 - `when` is the condition. It gets a builder with the types of the resource.
 - `fields` makes the rule about some fields only. `*` stands for any part of one
-  field name, and `**` for any number of parts: `settings.*` covers
-  `settings.model`.
+  field name, and `**` for any number of parts, also none: `settings.*` covers
+  `settings.model`, and `**.secret` covers `secret` and `settings.secret`.
 - `reason`, `id` and `meta` are kept with the rule. `meta` is extra data, such
   as the scope of a grant. Give its Schema to `Domain.make({ meta })`.
 
 An allow rule with fields covers a request for the whole value: "may update some
-fields" is a yes. A deny rule with fields does not stop a request for the whole
-value.
+fields" is a yes. This is true only for a kind that has one of these fields. A
+deny rule with fields does not stop a request for the whole value.
+
+To know if a kind has a field that a pattern fits, the library walks the Schema
+of the kind: its fields, the keys of its records, and the getters of its
+classes. For some key Schemas it can only try sample keys, so it may not find a
+field that is there. Then the answer for the whole value is "no", never a wrong
+"yes".
 
 ## Conditions
 
@@ -210,14 +216,19 @@ The builder in `when` has these functions:
 
 A missing field of a resource has the value `null`. A field of the principal
 that is `null` or missing is different: a test with it is always false, also
-with `ne`. So a guest with no `userId` never matches a Bot with no owner. To
-test for `null`, use a fixed value, as in `$.eq("ownerUserId", null)`.
+with `ne`. So a guest with no `userId` never matches a document with no owner.
+To test for `null`, use a fixed value, as in `$.eq("ownerId", null)`.
 
 `predicate` is the one way out of plain data. Its test may give a boolean or an
 `Effect`. The error type and the service type of the `Effect` go into the types
 of the policy and of every check. A policy with a predicate can not become JSON
 or a query, and the type system stops you when you try.
 
+A predicate also keeps the types of the value and the principal that it reads.
+So a predicate for a Document can not go into a rule for a Comment. Make
+conditions with the builder: a node made by hand is not a condition in the
+types.
+
 ## Policies
 
 A list of rules has a combining algorithm. It decides which rule gives the
@@ -247,6 +258,12 @@ Put policies together:
 | `Policy.firstOf([a, b])`      | The first policy that allows or denies.                          |
 | `Policy.ceiling(policy, cap)` | A deny from `cap` always wins. An allow from `cap` does nothing. |
 
+A policy tree may have at most 256 levels. A combinator throws an error for a
+deeper tree, and the policy Schema does not decode one. A deeper tree could fill
+the stack of a check. The JSON form of a policy may have at most 1000 levels of
+objects and arrays, so a deep input fails to decode before it fills the stack. A
+field path may have at most 256 parts.
+
 For example, a user token may never do more than its member, and the platform
 has deny rules for everyone:
 
@@ -268,6 +285,7 @@ authorizer with a decider asks the decider first.
 | `Policy.decideSync`      | The same, at once. Only for policies with no predicates.       |
 | `Policy.explain`         | The decision and the rules that were tested, for an audit log. |
 | `Policy.residual`        | The condition on resource values that the policy allows.       |
+| `Policy.coverage`        | If the policy allows all, none or some of a part of a kind.    |
 | `Policy.permittedFields` | The fields of a value that the policy lets a request use.      |
 
 `Policy.residual` puts the principal into every rule and gives a condition on
@@ -275,6 +293,85 @@ the resource fields only. It is `True` when the policy allows every value of the
 kind, and `False` when it allows none. Use it to ask "may this principal do this
 act on some value of this kind?", or to make a database query.
 
+When a rule that the request may use has a predicate, the residual is one
+predicate with the name `"policy"`. It runs the whole policy for each value, so
+it gives the same answers and the same failures as `Policy.decide`.
+
+A deep policy tree may give a very large residual. When it would have more than
+10000 nodes, `Policy.residual` throws an error, and a check in an `Authorizer`
+fails. It throws an error too when a rule that the request may use reads a
+getter of a class: the read may fail when the policy runs, and a smaller
+condition could leave it out.
+
+### Scopes
+
+A scope is a part of a kind, such as the posts of one writer. Give it as
+`within`, with the same builder as the condition of a rule. A scope is plain
+data: it may not have a predicate.
+
+There are three questions about a scope. Each one is a question about two sets:
+the values in the scope, and the values that the policy allows.
+
+| Question                               | Sets                | Function                        |
+| -------------------------------------- | ------------------- | ------------------------------- |
+| May the principal act on every value?  | scope ⊆ allowed     | `Policy.coverage` is `All`      |
+| Which values may the principal act on? | scope ∩ allowed     | `Policy.residual`               |
+| May the principal act on some value?   | scope ∩ allowed ≠ ∅ | `Policy.coverage` is not `None` |
+
+```ts
+const ownPosts = {
+	principal: writer,
+	action: "update",
+	kind: "Post",
+	within: ($) => $.eq("authorId", $.principal("id")),
+} satisfies Policy.KindRequest<typeof Blog>
+
+Policy.coverage(policy, ownPosts)._tag // "All"
+Policy.residual(policy, ownPosts) // authorId = "u1"
+```
+
+Use "every value" for an act on a value that does not exist yet. A new post has
+no id, but its author is known, so a check on the scope of its author tells if
+the writer may make it.
+
+`Policy.coverage` gives one of four answers. Each one has `condition`, the exact
+list query for the scope:
+
+- `All`: the policy allows every value in the scope.
+- `None`: the policy allows no value in the scope. An empty scope is `None` too,
+  so a scope with a mistake never gives a "yes".
+- `Some`: the policy allows some values and not others. It gives an example of
+  each, `allowed` and `refused`.
+- `Unknown`: the policy has a predicate, a condition tests a field that is not a
+  plain scalar, or the search went past its budget.
+
+The answer is exact. Each test in a condition compares one field with fixed
+values, so these values cut the values of the field into a few parts, and every
+value in one part gives the same answer. `Condition.satisfiable` tries one value
+from each part, one field at a time. It takes the values of each field from the
+Schema of the resource: its literals, `null` for a nullable or optional field,
+and finite or integer numbers. It does not know other Schema checks, such as a
+minimum length, so a field with such a check is not plain (see below).
+
+The search answers only for plain scalar fields: a string, a number, a boolean,
+a literal, `null`, or an optional field or a union of these, with no checks
+other than finite and integer checks, on a path of required fields of plain
+structs. For another field, such as a class, a record, a union of structs, a
+date or a field of `Schema.declare`, a value may have data that the Schema does
+not show, so the answer is `Unknown`. A check on a kind then says no.
+`Resource.isPlainField` tells if a field is plain. This is true for each rule
+that the request may use, also for a test that a smaller condition leaves out: a
+read of a field that is not plain, such as a getter, may fail in a check.
+
+A "yes" also needs a value of the whole kind, so each required field of the kind
+must surely have values, also a field that the condition does not test. A
+required field with a check other than finite and integer checks, such as a
+minimum length, may have no value, so then the answer is `Unknown` in place of
+`All` or `Some`. `Resource.hasValue` tells if a Schema surely has a value.
+
+"Some" means that some value of the Schema is allowed. It does not mean that
+such a value is in your database. To know that, run the condition as a query.
+
 ## Queries
 
 Change a residual condition into a query with `Condition.fold`. You give one
@@ -292,15 +389,19 @@ const toSql = Condition.fold<string>({
 	not: (part) => `NOT ${part}`,
 })
 
-const where =
-	yield *
-	toSql(Policy.residual(policy, { principal, action: "read", kind: "Post" }))
+const program = Effect.gen(function* () {
+	const where = yield* toSql(
+		Policy.residual(policy, { principal, action: "read", kind: "Post" }),
+	)
+})
 ```
 
 `fold` fails with `Untranslatable` on a predicate, unless you give a `predicate`
 function too. Take care with `null`: in this library `ne` is true when the field
 is `null`, but in SQL `x <> 'a'` is not true when `x` is `NULL`. Use
-`IS DISTINCT FROM` or a similar form.
+`IS DISTINCT FROM` or a similar form. Give the values to the database as bound
+parameters. A value from a principal may have a quote in it, and in the SQL text
+it could change the query. `examples/multi-tenant.ts` shows how.
 
 ## JSON
 
@@ -337,19 +438,32 @@ const AuthLive = Authorizer.layer(Auth, {
 })
 ```
 
+Two principals with the same data get one policy from the cache. So the loader
+must decide by the data of the principal only. When it tests that an object of
+the principal is a given object, as `role === admin` does, give `cache: false`.
+
 Use it in a handler:
 
 ```ts
-yield * Auth.check({ action: "update", resource: post })
-yield * Auth.check({ action: "read", kind: "Post" })
-yield *
-	Auth.guard(
+const handler = Effect.gen(function* () {
+	yield* Auth.check({ action: "update", resource: post })
+	yield* Auth.check({ action: "read", kind: "Post" })
+	yield* Auth.guard(
 		{ action: "update", resource: post },
 		{
 			hide: () => PostNotFound.make({ id: post.id }),
 		},
 	)
-const where = yield * Auth.filter({ action: "read", kind: "Post" })
+	const where = yield* Auth.filter({ action: "read", kind: "Post" })
+	// A new post of the writer: every post of this author may be made.
+	yield* Auth.check({
+		action: "update",
+		kind: "Post",
+		within: ($) => $.eq("authorId", $.principal("id")),
+	})
+	const covered = yield* Auth.coverage({ action: "delete", kind: "Post" })
+	const showDeleteButton = covered._tag !== "None"
+})
 ```
 
 | Function          | What it does                                                                  |
@@ -357,12 +471,18 @@ const where = yield * Auth.filter({ action: "read", kind: "Post" })
 | `check`           | Succeeds with `void`, or fails with `Forbidden`.                              |
 | `guard`           | Fails with your error when the principal may not read the value, then checks. |
 | `filter`          | Gives the residual condition, for a list query.                               |
+| `coverage`        | Tells if the principal may act on all, none or some values in a scope.        |
 | `decide`          | Gives the decision. It does not fail on a "no".                               |
 | `permittedFields` | Gives the fields that the principal may use.                                  |
 | `invalidate`      | Removes a cached policy, after a change to the rules of a principal.          |
 
 A check on a kind (`{ action, kind }`) passes only when the policy allows the
-act on every value of the kind.
+act on every value of the kind. With `within`, it passes only when the policy
+allows the act on every value in the scope, and the scope is not empty. The
+decider is asked only when no value in the scope is denied.
+
+`filter` gives `False` when the principal may act on no value. Then the list is
+empty, and that is not an error.
 
 The errors of a check:
 
@@ -374,8 +494,8 @@ The errors of a check:
 ### Deciders
 
 When no rule gives an answer, the authorizer asks the decider, if there is one.
-A decider may answer at once, or fail with `Pending` when a person or a Bot must
-answer later:
+A decider may answer at once, or fail with `Pending` when a person or another
+service must answer later:
 
 ```ts
 Authorizer.layer(Auth, {
@@ -418,17 +538,65 @@ const health = HttpApiEndpoint.get("health", "/health").annotate(
 	[],
 )
 
+// The checks run only in a group that uses the middleware.
+const posts = HttpApiGroup.make("posts")
+	.add(update, health)
+	.middleware(Authorization)
+
 const AuthorizationLive = AbilityHttpApi.layer(Authorization, Auth)
 ```
 
+An act on a part of a kind takes a scope from the path parameters. A list takes
+`lists`: the middleware does not check every value, because the handler gets its
+query with `Auth.filter`, with the same scope. An empty list is not an error,
+unless you give `nonEmpty: true`. Then the middleware needs a coverage of `All`
+or `Some`, so `Unknown` fails too:
+
+```ts
+const create = HttpApiEndpoint.post("create", "/users/:user/posts", {
+	params: { user: Schema.String },
+}).annotate(AbilityHttpApi.Required, [
+	AbilityHttpApi.requires(Auth, "update", "Post", {
+		within: (params) => ($) => $.eq("authorId", params["user"] ?? ""),
+	}),
+])
+
+const list = HttpApiEndpoint.get("list", "/users/:user/posts", {
+	params: { user: Schema.String },
+}).annotate(AbilityHttpApi.Required, [
+	AbilityHttpApi.lists(Auth, "read", "Post", {
+		within: (params) => ($) => $.eq("authorId", params["user"] ?? ""),
+	}),
+])
+```
+
+A path parameter may be `undefined`. A scope with `undefined` in it is a defect,
+so give another value for it.
+
+The annotations and the layer do nothing alone. Give the middleware to every
+group with `.middleware(Authorization)`, or to the whole API. An endpoint in a
+group without the middleware is not checked.
+
 `GroupRequired` gives a default for a whole group: one list for GET requests and
 one for every other method. `AbilityHttpApi.errors` gives the errors with HTTP
 status codes: 403, 503, and 409.
 
 ## Examples
 
+Each example is a small program. Run it with Node.js, which runs `.ts` files
+itself:
+
 ```sh
 node examples/basic.ts
-node examples/authorizer.ts
-node examples/openbot-rbac.ts
 ```
+
+| Example                       | What it shows                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `examples/basic.ts`           | A blog: a domain, a policy, field rules and a decision with a reason.                            |
+| `examples/authorizer.ts`      | Team documents: an authorizer service with a cache, `guard`, `filter`, coverage and a decider.   |
+| `examples/multi-tenant.ts`    | A task tracker for many teams: roles, API tokens, a platform limit, scopes and SQL list queries. |
+| `examples/field-access.ts`    | A staff list: rules for some fields, field patterns and `permittedFields`.                       |
+| `examples/stored-policies.ts` | A help desk: policies kept as JSON, `meta` on rules, checks when a policy loads, and `explain`.  |
+| `examples/predicates.ts`      | Meeting rooms: a predicate that asks an Effect service, its error type, and `provideContext`.    |
+| `examples/algorithms.ts`      | File sharing: the four combining algorithms, `any`, `firstOf` and `ceiling`.                     |
+| `examples/http-api.ts`        | A notes API: the `effect/http-api` middleware, one-value checks, list scopes and closed routes.  |

package/dist/Authorizer.d.ts

@@ -1,15 +1,21 @@
 import { Condition, Opaque } from "./Condition.js";
-import { Any, AnyAction, Principal } from "./Domain.js";
+import { Any, CommonAction, Kind, Principal } from "./Domain.js";
 import { Decision } from "./Decision.js";
-import { KindRequest, KindTarget, Policy, Request, Target as Target$1 } from "./Policy.js";
-import { Forbidden as Forbidden$1, Pending as Pending$1, PolicyUnavailable as PolicyUnavailable$1 } from "./internal/authorizer.js";
+import { Coverage, FieldlessTarget, KindRequest, KindTarget, Policy, Request, ResidualReads, Target as Target$1 } from "./Policy.js";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
 import * as Duration from "effect/Duration";
 declare namespace Authorizer_d_exports {
   export { AnyServiceClass, Authorizer, Config, DeciderRequest, Forbidden, GuardOptions, Options, Pending, PolicyUnavailable, Service, ServiceClass, Target, layer };
 }
+declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {
+  readonly action: Schema.String;
+  readonly kind: Schema.String;
+  readonly field: Schema.optionalKey<Schema.String>;
+  readonly reason: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * The error when a policy says no.
  *
@@ -17,13 +23,10 @@ declare namespace Authorizer_d_exports {
  * @category errors
  * @since 0.3.0
  */
-export declare const Forbidden: typeof Forbidden$1;
-/**
- * @stability stable
- * @category errors
- * @since 0.3.0
- */
-export type Forbidden = Forbidden$1;
+export declare class Forbidden extends Forbidden_base {}
+declare const PolicyUnavailable_base: Schema.Class<PolicyUnavailable, Schema.TaggedStruct<"PolicyUnavailable", {
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
 /**
  * The error when the policy of the principal can not be loaded. The cause is
  * kept, but it is not shown to the client.
@@ -32,13 +35,11 @@ export type Forbidden = Forbidden$1;
  * @category errors
  * @since 0.3.0
  */
-export declare const PolicyUnavailable: typeof PolicyUnavailable$1;
-/**
- * @stability stable
- * @category errors
- * @since 0.3.0
- */
-export type PolicyUnavailable = PolicyUnavailable$1;
+export declare class PolicyUnavailable extends PolicyUnavailable_base {}
+declare const Pending_base: Schema.Class<Pending, Schema.TaggedStruct<"Pending", {
+  readonly ticket: Schema.String;
+  readonly reason: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * The error when a decider must wait for an answer. `ticket` names the
  * request that waits, so the client can come back for the answer.
@@ -47,13 +48,7 @@ export type PolicyUnavailable = PolicyUnavailable$1;
  * @category errors
  * @since 0.3.0
  */
-export declare const Pending: typeof Pending$1;
-/**
- * @stability stable
- * @category errors
- * @since 0.3.0
- */
-export type Pending = Pending$1;
+export declare class Pending extends Pending_base {}
 /**
  * The services and the errors of the principal and the decider of an
  * authorizer.
@@ -75,7 +70,8 @@ type ErrorOf<C> = C extends {
 /**
  * What a check is about: an act on a resource value, or an act on a kind of
  * resource. A check on a kind passes only when the policy allows the act on
- * every value of the kind.
+ * every value of the kind. With a scope (`within`), it passes when the policy
+ * allows the act on every value in the scope, and the scope is not empty.
  *
  * @stability stable
  * @category models
@@ -97,12 +93,23 @@ export type DeciderRequest<D> = Request<D> | KindRequest<D>;
  * @category models
  * @since 0.3.0
  */
-export interface GuardOptions<D, E2> {
-  /** The action that lets the principal see the resource. The default is `"read"`. */
-  readonly read?: AnyAction<D>;
+export type GuardOptions<D, E2, K extends string = Kind<D>> = {
   /** The error when the principal may not see the resource. */
   readonly hide: () => E2;
-}
+} & ("read" extends CommonAction<D, K> ? {
+  /**
+   * The action that lets the principal see the resource. It must be an
+   * action of every kind in `K`. The default is `"read"`.
+   */
+  readonly read?: CommonAction<D, K>;
+} : {
+  /**
+   * The action that lets the principal see the resource. It must be an
+   * action of every kind in `K`. Some kind in `K` has no `"read"`
+   * action, so you must give it.
+   */
+  readonly read: CommonAction<D, K>;
+});
 /**
  * The service.
  *
@@ -114,8 +121,11 @@ export interface Authorizer<D extends Any, E, R> {
   readonly domain: D;
   /** The principal of the current request. */
   readonly principal: Effect.Effect<Principal<D>, E, R>;
-  /** The policy of the principal of the current request. */
-  readonly policy: Effect.Effect<Policy<D, E>, PolicyUnavailable | E, R>;
+  /**
+   * The policy of the principal of the current request. Its predicates have
+   * the services of the layer. It may have predicates, so it is opaque.
+   */
+  readonly policy: Effect.Effect<Policy<D, E, never, Opaque>, PolicyUnavailable | E, R>;
   /** Gives the decision of the policy. It does not ask the decider. */
   readonly decide: (target: Target$1<D>) => Effect.Effect<Decision, PolicyUnavailable | E, R>;
   /** Succeeds when the principal may do the act, and fails when it may not. */
@@ -126,14 +136,22 @@ export interface Authorizer<D extends Any, E, R> {
    * answer "not found" to a principal that may not know that a resource
    * exists.
    */
-  readonly guard: <E2>(target: Target$1<D>, options: GuardOptions<D, E2>) => Effect.Effect<void, E2 | Forbidden | Pending | PolicyUnavailable | E, R>;
+  readonly guard: <const T extends Target$1<D>, E2>(target: T, options: GuardOptions<D, E2, T["resource"]["_tag"]>) => Effect.Effect<void, E2 | Forbidden | Pending | PolicyUnavailable | E, R>;
+  /**
+   * Gives the condition on resource values that the principal may act on,
+   * inside the scope of the target when it has one. Change it into a query
+   * with `Condition.fold`. It is `False` when the principal may act on no
+   * value, so the list is empty: it is not an error.
+   */
+  readonly filter: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Condition<E, never, Opaque, ResidualReads<D, T["kind"]>>, PolicyUnavailable | E, R>;
   /**
-   * Gives the condition on resource values that the principal may act on.
-   * Change it into a query with `Condition.fold`.
+   * Tells if the principal may act on all, none or some of the values in
+   * the scope of the target. See `Policy.coverage`. Use it to show a button
+   * only when the answer is not `None`.
    */
-  readonly filter: (target: KindTarget<D>) => Effect.Effect<Condition<E, never, Opaque>, PolicyUnavailable | E, R>;
+  readonly coverage: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Coverage<E, never, Opaque, ResidualReads<D, T["kind"]>>, PolicyUnavailable | E, R>;
   /** Gives the fields of a value that the principal may use. */
-  readonly permittedFields: (target: Omit<Target$1<D>, "field">) => Effect.Effect<ReadonlyArray<string>, PolicyUnavailable | E, R>;
+  readonly permittedFields: (target: FieldlessTarget<D>) => Effect.Effect<ReadonlyArray<string>, PolicyUnavailable | E, R>;
   /**
    * Removes the cached policy of a principal, or of every principal. Call it
    * after a change to the rules or roles of a principal.
@@ -152,9 +170,10 @@ export interface ServiceClass<Self, Id extends string, D extends Any, E, R> exte
   readonly domain: D;
   readonly decide: (target: Target$1<D>) => Effect.Effect<Decision, PolicyUnavailable | E, R | Self>;
   readonly check: (target: Target<D>) => Effect.Effect<void, Forbidden | Pending | PolicyUnavailable | E, R | Self>;
-  readonly guard: <E2>(target: Target$1<D>, options: GuardOptions<D, E2>) => Effect.Effect<void, E2 | Forbidden | Pending | PolicyUnavailable | E, R | Self>;
-  readonly filter: (target: KindTarget<D>) => Effect.Effect<Condition<E, never, Opaque>, PolicyUnavailable | E, R | Self>;
-  readonly permittedFields: (target: Omit<Target$1<D>, "field">) => Effect.Effect<ReadonlyArray<string>, PolicyUnavailable | E, R | Self>;
+  readonly guard: <const T extends Target$1<D>, E2>(target: T, options: GuardOptions<D, E2, T["resource"]["_tag"]>) => Effect.Effect<void, E2 | Forbidden | Pending | PolicyUnavailable | E, R | Self>;
+  readonly filter: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Condition<E, never, Opaque, ResidualReads<D, T["kind"]>>, PolicyUnavailable | E, R | Self>;
+  readonly coverage: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Coverage<E, never, Opaque, ResidualReads<D, T["kind"]>>, PolicyUnavailable | E, R | Self>;
+  readonly permittedFields: (target: FieldlessTarget<D>) => Effect.Effect<ReadonlyArray<string>, PolicyUnavailable | E, R | Self>;
 }
 /**
  * Any service class made by {@link Service}.
@@ -198,6 +217,12 @@ export interface Options<D extends Any, E, R, EL, RL, RP> {
   /**
    * How the policies are kept. The default keeps 1000 policies for 30 seconds.
    * Give `false` to load the policy for each check.
+   *
+   * Two principals with the same data get one policy from the cache. So the
+   * loader must decide by the data of the principal only. When it tests that
+   * an object of the principal is a given object, as `role === admin` does,
+   * give `false`. A principal with objects in an array, a set or the keys of
+   * a map is not kept, because such tests are usual there.
    */
   readonly cache?: {
     readonly capacity?: number;

package/dist/Authorizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Authorizer.d.ts","names":["internal.Forbidden","internal.PolicyUnavailable","internal.Pending","Policy.Target","Policy.KindTarget","Policy.Request","Policy.KindRequest","Domain.AnyAction","Domain.Any","Domain.Principal","Policy.Policy","Decision.Decision","Condition.Opaque","Condition.Condition"],"sources":["../src/Authorizer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;qBAqDa,kBAAkBA;;;;;;YAOnB,YAAYA;;;;;;;;;qBAUX,0BAA0BC;;;;;;YAQ3B,oBAAoBA;;;;;;;;;qBAUnB,gBAAgBC;;;;;;YAOjB,UAAUA;;;;;;;;;iBAUL;WACP;WACA;;KAGL,WAAW,KAAK;WAAqB,gBAAgB;IAAM;KAC3D,QAAQ,KAAK;WAAqB,aAAa;IAAM;;;;;;;;;;YAW9C,OAAO,KAAKC,SAAc,KAAKC,WAAkB;;;;;;;;YASjD,eAAe,KAAKC,QAAe,KAAKC,YAAmB;;;;;;;;iBAStD,aAAa,GAAG;;WAEvB,OAAOC,UAAiB;;WAExB,YAAY;;;;;;;;;iBAUL,WAAW,UAAUC,KAAY,GAAG;WAC3C,QAAQ;;WAER,WAAW,OAAO,OAAOC,UAAiB,IAAI,GAAG;;WAEjD,QAAQ,OAAO,OAAOC,OAAc,GAAG,IAAI,oBAAoB,GAAG;;WAElE,SACR,QAAQP,SAAc,OAClB,OAAO,OAAOQ,UAAmB,oBAAoB,GAAG;;WAEpD,QACR,QAAQ,OAAO,OACX,OAAO,aAAa,YAAY,UAAU,oBAAoB,GAAG;;;;;;;WAO7D,QAAQ,IAChB,QAAQR,SAAc,IACtB,SAAS,aAAa,GAAG,QACrB,OAAO,aAAa,KAAK,YAAY,UAAU,oBAAoB,GAAG;;;;;WAKlE,SACR,QAAQC,WAAkB,OACtB,OAAO,OACXS,UAAoB,UAAUD,SAC9B,oBAAoB,GACpB;;WAGQ,kBACR,QAAQ,KAAKT,SAAc,iBACvB,OAAO,OAAO,uBAAuB,oBAAoB,GAAG;;;;;WAKxD,aAAa,YAAYM,UAAiB,OAAO,OAAO;;;;;;;;;;iBAWjD,aAChB,MACA,mBACA,UAAUD,KACV,GACA,WACS,QAAQ,aAAa,MAAM,IAAI,WAAW,GAAG,GAAG;WAChD,QAAQ;WACR,SACR,QAAQL,SAAc,OAClB,OAAO,OAAOQ,UAAmB,oBAAoB,GAAG,IAAI;WACxD,QACR,QAAQ,OAAO,OACX,OAAO,aAEX,YAAY,UAAU,oBAAoB,GAC1C,IAAI;WAEI,QAAQ,IAChB,QAAQR,SAAc,IACtB,SAAS,aAAa,GAAG,QACrB,OAAO,aAEX,KAAK,YAAY,UAAU,oBAAoB,GAC/C,IAAI;WAEI,SACR,QAAQC,WAAkB,OACtB,OAAO,OACXS,UAAoB,UAAUD,SAC9B,oBAAoB,GACpB,IAAI;WAEI,kBACR,QAAQ,KAAKT,SAAc,iBACvB,OAAO,OAAO,uBAAuB,oBAAoB,GAAG,IAAI;;;;;;;;;YAU1D,kBAAkB,QAAQ;WAC5B,QAAQK;;;;;;;;;qBAUL,UAAU,MAAM,UAAU,yBAChC,mBACN,UAAUA,KAEV,IAAI,IACJ,QAAQ,MACJ,aAAa,MAAM,IAAI,GAAG,QAAQ,IAAI,WAAW;;;;;;;;iBAUrC,QAAQ,UAAUA,KAAY,GAAG,GAAG,IAAI,IAAI;;WAEnD,WAAW,OAAO,OAAOC,UAAiB,IAAI,GAAG;;;;;;WAMjD,SACR,WAAWA,UAAiB,OACxB,OAAO,OAAOC,OAAc,GAAG,GAAG,UAAU,IAAI;;;;;WAK5C,WACR,SAAS,eAAe,OACpB,OAAO,OAAOC,UAAmB,UAAU,GAAG;;;;;WAK1C;aAEG;aACA,aAAa,SAAS;;;;;;;;;;qBAYtB,QACZ,MACA,mBACA,UAAUH,KACV,GACA,GACA,YACA,YACA,YAEA,SAAS,aAAa,MAAM,IAAI,GAAG,GAAG,IACtC,SAAS,QAAQ,GAAG,QAAQ,IAAI,QAAQ,IAAI,IAAI,IAAI,QAChD,MAAM,MAAM,aAAa,KAAK"}
+{"version":3,"file":"Authorizer.d.ts","names":["Policy.Target","Policy.KindTarget","Policy.Request","Policy.KindRequest","Domain.Kind","Domain.CommonAction","Domain.Any","Domain.Principal","Condition.Opaque","Policy.Policy","Decision.Decision","Policy.ResidualReads","Condition.Condition","Policy.Coverage","Policy.FieldlessTarget"],"sources":["../src/Authorizer.ts"],"mappings":"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"}