@nmnmcc/ability 1.0.0 → 2.0.0

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:
 
@@ -15,6 +15,8 @@ The library is made with [Effect](https://effect.website) only:
 - An `Authorizer` is an Effect service. A "no" goes into the error channel. When
   a policy can not be loaded, the check fails, so an error is never a "yes".
 
+Version 2.0 changed the API. See [MIGRATION.md](MIGRATION.md) to move from 1.x.
+
 ## Requirements
 
 - Use strict type checking. Without it, the types do not give all of their
@@ -36,9 +38,7 @@ import {
 	Decision,
 	Domain,
 	Policy,
-	Principal,
 	Resource,
-	Rule,
 } from "@nmnmcc/ability"
 import * as AbilityHttpApi from "@nmnmcc/ability/HttpApi"
 ```
@@ -46,13 +46,12 @@ import * as AbilityHttpApi from "@nmnmcc/ability/HttpApi"
 | Module       | What it is                                                                  |
 | ------------ | --------------------------------------------------------------------------- |
 | `Resource`   | A kind of thing to act on, with its actions, its Schema, and a path.        |
-| `Principal`  | The Schema of the one who asks.                                             |
-| `Domain`     | The principal and all the resources. Every other type comes from it.        |
+| `Domain`     | The principal Schema and all the resources. Every type comes from it.       |
 | `Condition`  | A test on a resource value, as plain data.                                  |
-| `Rule`       | An allow rule or a deny rule.                                               |
-| `Policy`     | A tree of rules that gives a decision, a residual condition, and fields.    |
+| `Policy`     | Rules, and a tree of rules that gives a decision, a residual and fields.    |
 | `Decision`   | `Allow`, `Deny` or `NotApplicable`.                                         |
 | `Authorizer` | An Effect service that checks the principal of the current request.         |
+| `Limits`     | The limits that keep every walk and every decoder small.                    |
 | `HttpApi`    | Annotations and a middleware for `effect/http-api`. A separate entry point. |
 
 ## First Steps
@@ -63,9 +62,9 @@ the same time:
 
 ```ts
 import { Effect, Schema } from "effect"
-import { Decision, Domain, Policy, Principal, Resource } from "@nmnmcc/ability"
+import { Decision, Domain, Policy, Resource } from "@nmnmcc/ability"
 
-class User extends Principal.Class<User>("User")({
+class User extends Schema.Class<User>("User")({
 	id: Schema.String,
 }) {}
 
@@ -140,35 +139,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.
@@ -183,9 +182,12 @@ _.allow("read", "*", {
   and the resource may be lists.
 - 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, also none: `settings.*` covers
-  `settings.model`, and `**.secret` covers `secret` and `settings.secret`.
+- `fields` makes the rule about some fields only. A field name covers the fields
+  below it too, so `settings` covers `settings.model`. In a pattern, `*` stands
+  for any text inside one part of a name, as in `secret*`. `**` stands for any
+  number of parts, also none, and it must be a whole part: `**.secret` covers
+  `secret` and `settings.secret`. A pattern that matches no field of the
+  resources of the rule is an error, so a mistake in a name shows at once.
 - `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 })`.
 
@@ -193,11 +195,23 @@ An allow rule with fields covers a request for the whole value: "may update some
 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".
+To know if a kind has a field that a pattern fits, the library reads the shape
+of the Schema of the kind: its fields and the keys of its records. A name in a
+pattern fits a key of a record when the Schema of the keys takes it. A part with
+a star fits any key.
+
+`Policy.define` checks every rule against the domain when the policy is made. A
+rule with a mistake is a `PolicyError`, with each problem and its path. For a
+name with a mistake, it gives the name that you may mean:
+
+```text
+A rule does not fit the domain: The field "titel" is not a field of every
+resource of the rule. Did you mean "title"?
+```
+
+A condition reads only the data fields of a value: an own field that a loop over
+the keys sees. A rule that names a getter of a class is a `PolicyError`. Use a
+predicate for a value that comes from code.
 
 ## Conditions
 
@@ -216,8 +230,8 @@ 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
@@ -225,8 +239,13 @@ 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 Bot can not go into a rule for a Trigger. Make conditions
-with the builder: a node made by hand is not a condition in the types.
+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, or a spread of a node, is not
+a condition, in the types or when the code runs.
+
+A condition may have at most 100000 nodes and 500 levels, with a shared part
+counted for each place. The builder throws an error for a larger condition. So
+no condition can make a check slow or fill the stack.
 
 ## Policies
 
@@ -257,11 +276,15 @@ 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.
+A policy tree may have at most 256 levels and 100000 nodes, with its rules and
+the nodes of their conditions, and a shared part counted for each place. A
+combinator throws an error for a larger tree, and the policy Schema does not
+decode one. The decoder reads at most 1000000 objects and array items, so no
+input can fill the stack or take a very long time. A field path may have at most
+5 parts.
+
+A shared part of a tree is decided again for each place, so its predicates run
+each time, and `Policy.explain` lists its rules each time.
 
 For example, a user token may never do more than its member, and the platform
 has deny rules for everyone:
@@ -298,9 +321,7 @@ 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.
+fails.
 
 ### Scopes
 
@@ -341,32 +362,19 @@ list query for the scope:
   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.
+- `Unknown`: the policy has a predicate, or the search went past its budget.
+
+`Condition.satisfiable` does the search. 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. The search tries one
+value from each part, one field at a time.
+
+The search reads the shape of the Schema of the resource: the fields, their
+literals, `null` for a nullable or optional field, and finite or integer
+numbers. It does not read other checks, such as a minimum length. A check only
+keeps values out, so the shape holds every real value and more. So `All` and
+`None` are right for every value of the Schema. `Some` means that, by the shape,
+a value may get either answer. A check may still stop one of the examples.
 
 "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.
@@ -400,7 +408,7 @@ 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. 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/openbot-rbac.ts` shows how.
+it could change the query. `examples/multi-tenant.ts` shows how.
 
 ## JSON
 
@@ -425,21 +433,27 @@ request, loads its policy, and keeps the policy in a cache.
 ```ts
 class Identity extends Context.Service<Identity, User>()("app/Identity") {}
 
-class Auth extends Authorizer.Service<Auth, { requires: Identity }>()(
-	"app/Auth",
-	Blog,
-) {}
+class Auth extends Authorizer.Service<Auth>()("app/Auth", {
+	domain: Blog,
+	principal: Identity,
+}) {}
 
 const AuthLive = Authorizer.layer(Auth, {
-	principal: Identity,
 	policy: (user) => loadPolicyOf(user),
 	cache: { capacity: 1000, timeToLive: "30 seconds" },
 })
 ```
 
-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`.
+The error type and the service type of every check come from the `principal`
+Effect.
+
+The cache key of a principal is the text of its JSON form, from the Schema of
+the principal of the domain. A principal is kept only when the value that the
+Schema decodes from that form is equal to it, so two principals with one key are
+equal. The loader always gets that decoded copy, also with no cache, so it must
+decide by the data of the principal, not by the identity of its objects. Give
+`cache: { key }` to make the key in another way, or `cache: false` to load the
+policy for each check.
 
 Use it in a handler:
 
@@ -493,12 +507,11 @@ 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, {
-	principal: Identity,
 	policy: loadPolicyOf,
 	decider: (request) =>
 		requests
@@ -547,9 +560,9 @@ 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:
+query from the same requirement, 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", {
@@ -560,13 +573,23 @@ const create = HttpApiEndpoint.post("create", "/users/:user/posts", {
 	}),
 ])
 
+const postsOfUser = AbilityHttpApi.lists(Auth, "read", "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"] ?? ""),
-	}),
-])
+}).annotate(AbilityHttpApi.Required, [postsOfUser])
+
+const PostsLive = HttpApiBuilder.group(Api, "posts", (handlers) =>
+	Effect.map(Auth, (auth) =>
+		handlers.handle("list", () =>
+			postsOfUser
+				.filter(auth)
+				.pipe(Effect.flatMap(toSql), Effect.flatMap(Posts.query)),
+		),
+	),
+)
 ```
 
 A path parameter may be `undefined`. A scope with `undefined` in it is a defect,
@@ -580,10 +603,43 @@ group without the middleware is not checked.
 one for every other method. `AbilityHttpApi.errors` gives the errors with HTTP
 status codes: 403, 503, and 409.
 
+## Limits
+
+Each limit keeps a walk, a decoder or a search small, so no input can fill the
+stack or take a very long time. An input past a limit is an error, as in "A
+condition has 100001 nodes. The most is 100000.". In an `Authorizer`, such an
+error is never a "yes". The `Limits` module gives each value.
+
+| Limit            | Value   | What it limits                                          |
+| ---------------- | ------- | ------------------------------------------------------- |
+| `fieldPathParts` | 5       | The parts of a field path, as in `settings.model`.      |
+| `patternParts`   | 16      | The parts of a field pattern.                           |
+| `conditionNodes` | 100000  | The nodes of a condition, a shared part for each place. |
+| `conditionDepth` | 500     | The levels of a condition.                              |
+| `residualNodes`  | 10000   | The nodes of a residual condition.                      |
+| `policyDepth`    | 256     | The levels of a policy tree.                            |
+| `policyNodes`    | 100000  | The nodes of a policy tree, with its rules.             |
+| `jsonNodes`      | 1000000 | The objects and items that a decoder reads.             |
+| `catalogFields`  | 10000   | The fields of the Schema of a resource.                 |
+| `searchSteps`    | 1000000 | The steps of one search, as in `Policy.coverage`.       |
+| `searchFields`   | 256     | The fields that one search may test.                    |
+
 ## 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,21 +1,15 @@
 import { Condition, Opaque } from "./Condition.js";
 import { Any, CommonAction, Kind, Principal } from "./Domain.js";
-import { Decision } from "./Decision.js";
 import { Coverage, FieldlessTarget, KindRequest, KindTarget, Policy, Request, ResidualReads, Target as Target$1 } from "./Policy.js";
+import { Decision } from "./Decision.js";
+import { Forbidden as Forbidden$1, Pending as Pending$1, PolicyUnavailable as PolicyUnavailable$1 } from "./internal/authorizer.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 };
+  export { AnyServiceClass, Authorizer, 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.
  *
@@ -23,10 +17,13 @@ declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbi
  * @category errors
  * @since 0.3.0
  */
-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>;
+export declare const Forbidden: typeof Forbidden$1;
+/**
+ * @stability stable
+ * @category errors
+ * @since 0.3.0
+ */
+export type Forbidden = Forbidden$1;
 /**
  * The error when the policy of the principal can not be loaded. The cause is
  * kept, but it is not shown to the client.
@@ -35,11 +32,13 @@ declare const PolicyUnavailable_base: Schema.Class<PolicyUnavailable, Schema.Tag
  * @category errors
  * @since 0.3.0
  */
-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>;
+export declare const PolicyUnavailable: typeof PolicyUnavailable$1;
+/**
+ * @stability stable
+ * @category errors
+ * @since 0.3.0
+ */
+export type PolicyUnavailable = PolicyUnavailable$1;
 /**
  * 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.
@@ -48,25 +47,13 @@ declare const Pending_base: Schema.Class<Pending, Schema.TaggedStruct<"Pending",
  * @category errors
  * @since 0.3.0
  */
-export declare class Pending extends Pending_base {}
+export declare const Pending: typeof Pending$1;
 /**
- * The services and the errors of the principal and the decider of an
- * authorizer.
- *
  * @stability stable
- * @category models
+ * @category errors
  * @since 0.3.0
  */
-export interface Config {
-  readonly requires?: unknown;
-  readonly error?: unknown;
-}
-type RequiresOf<C> = C extends {
-  readonly requires: infer R;
-} ? R : never;
-type ErrorOf<C> = C extends {
-  readonly error: infer E;
-} ? E : never;
+export type Pending = Pending$1;
 /**
  * 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
@@ -125,7 +112,7 @@ export interface Authorizer<D extends Any, 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>;
+  readonly policy: Effect.Effect<Policy<D, Opaque<E>>, 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. */
@@ -143,13 +130,13 @@ export interface Authorizer<D extends Any, E, R> {
    * 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>;
+  readonly filter: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Condition<ResidualReads<D, T["kind"]>, Opaque<E>>, PolicyUnavailable | E, R>;
   /**
    * 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 coverage: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Coverage<E, never, Opaque, ResidualReads<D, T["kind"]>>, PolicyUnavailable | E, R>;
+  readonly coverage: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Coverage<ResidualReads<D, T["kind"]>, Opaque<E>>, PolicyUnavailable | E, R>;
   /** Gives the fields of a value that the principal may use. */
   readonly permittedFields: (target: FieldlessTarget<D>) => Effect.Effect<ReadonlyArray<string>, PolicyUnavailable | E, R>;
   /**
@@ -168,11 +155,13 @@ export interface Authorizer<D extends Any, E, R> {
  */
 export interface ServiceClass<Self, Id extends string, D extends Any, E, R> extends Context.ServiceClass<Self, Id, Authorizer<D, E, R>> {
   readonly domain: D;
+  /** The Effect that gives the principal of the current request. */
+  readonly principal: Effect.Effect<Principal<D>, E, R>;
   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: <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 filter: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Condition<ResidualReads<D, T["kind"]>, Opaque<E>>, PolicyUnavailable | E, R | Self>;
+  readonly coverage: <const T extends KindTarget<D>>(target: T) => Effect.Effect<Coverage<ResidualReads<D, T["kind"]>, Opaque<E>>, PolicyUnavailable | E, R | Self>;
   readonly permittedFields: (target: FieldlessTarget<D>) => Effect.Effect<ReadonlyArray<string>, PolicyUnavailable | E, R | Self>;
 }
 /**
@@ -184,6 +173,7 @@ export interface ServiceClass<Self, Id extends string, D extends Any, E, R> exte
  */
 export type AnyServiceClass = Context.Key<any, any> & {
   readonly domain: Any;
+  readonly principal: Effect.Effect<any, any, any>;
 };
 /**
  * Makes an authorizer service class for a domain.
@@ -192,7 +182,11 @@ export type AnyServiceClass = Context.Key<any, any> & {
  * @category constructors
  * @since 0.3.0
  */
-export declare const Service: <Self, C extends Config = {}>() => <const Id extends string, D extends Any>(id: Id, domain: D) => ServiceClass<Self, Id, D, ErrorOf<C>, RequiresOf<C>>;
+export declare const Service: <Self>() => <const Id extends string, D extends Any, E = never, R = never>(id: Id, options: {
+  readonly domain: D;
+  /** Gives the principal of the current request. */
+  readonly principal: Effect.Effect<Principal<NoInfer<D>>, E, R>;
+}) => ServiceClass<Self, Id, D, E, R>;
 /**
  * The options of {@link layer}.
  *
@@ -201,14 +195,12 @@ export declare const Service: <Self, C extends Config = {}>() => <const Id exten
  * @since 0.3.0
  */
 export interface Options<D extends Any, E, R, EL, RL, RP> {
-  /** Gives the principal of the current request. */
-  readonly principal: Effect.Effect<Principal<D>, E, R>;
   /**
    * Loads the policy of a principal. A failure becomes
    * {@link PolicyUnavailable}. The services of the predicates of the policy
    * are taken when the layer is built.
    */
-  readonly policy: (principal: Principal<D>) => Effect.Effect<Policy<D, E, RP, any>, EL, RL>;
+  readonly policy: (principal: Principal<D>) => Effect.Effect<Policy<D, Opaque<E, RP>>, EL, RL>;
   /**
    * Answers when no rule gives an answer. Without a decider, such a request
    * fails with {@link Forbidden}.
@@ -218,15 +210,19 @@ 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.
+   * The key of a principal is the text of its JSON form, from the Schema of
+   * the principal of the domain. A principal is kept only when the value that
+   * the Schema decodes from that form is `Equal` to it. The loader always
+   * gets that decoded copy, also with no cache, so two principals with one
+   * key get one policy, and the cache can not change an answer. So the loader
+   * must decide by the data of the principal, not by the identity of its
+   * objects. A principal with no JSON form is not kept, and the loader gets
+   * it as it is. Give `key` to make the key in another way.
    */
   readonly cache?: {
     readonly capacity?: number;
     readonly timeToLive?: Duration.Input;
+    readonly key?: (principal: Principal<D>) => string | undefined;
   } | false;
 }
 /**

package/dist/Authorizer.d.ts.map

@@ -1 +1 @@
-{"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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"}
+{"version":3,"file":"Authorizer.d.ts","names":["Internal.Forbidden","Internal.PolicyUnavailable","Internal.Pending","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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"}