@nmnmcc/ability 0.2.0 → 1.0.0

package/README.md

@@ -1,581 +1,589 @@
 # @nmnmcc/ability
 
-Authorization primitives for Effect programs, backed by CASL's rule engine.
+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.
 
-This package models authorization checks as `Effect` values and keeps failures
-in the typed error channel, while preserving the familiar CASL rule model:
-actions, subjects, fields, conditions, allow rules, and deny rules.
+The library is made with [Effect](https://effect.website) only:
+
+- Resources and principals are Schema classes. The types of rules, conditions
+  and checks all come from them.
+- A condition is plain data. You can test it on a value, make it smaller with
+  the principal, change it into a database query, and keep it as JSON.
+- A policy is a tree. Lists of rules are its leaves, and you put policies
+  together with `all`, `any`, `firstOf` and `ceiling`.
+- 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".
 
 ## Requirements
 
-- TypeScript projects should use strict type checking to get the full public API
-  guarantees.
-- `effect` and `@casl/ability` are peer dependencies.
-- CASL APIs are not re-exported. Import official CASL helpers directly from
-  `@casl/ability`.
+- Use strict type checking. Without it, the types do not give all of their
+  safety.
+- `effect` is a peer dependency. Your project must install it.
 
-## Installation
+## Install
 
 ```sh
-yarn add @nmnmcc/ability effect @casl/ability
+pnpm add @nmnmcc/ability effect
 ```
 
 ## Overview
 
-The main entry point is the following import:
-
 ```ts
-import {Ability, AbilityExtra} from "@nmnmcc/ability"
+import {
+	Authorizer,
+	Condition,
+	Decision,
+	Domain,
+	Policy,
+	Principal,
+	Resource,
+	Rule,
+} from "@nmnmcc/ability"
+import * as AbilityHttpApi from "@nmnmcc/ability/HttpApi"
 ```
 
-| Concept | Description |
-| ------- | ----------- |
-| `Ability` | An immutable, ordered set of authorization rules. |
-| `Rule` | A yieldable allow or deny rule recorded by `Ability.define`. |
-| `Ability.define` | Synchronously builds an `Ability` from a generator DSL. |
-| `Ability.check` | The authorization decision API. It succeeds with `void` or fails through the Effect error channel. |
-| `Ability.subject` | Wraps a plain object with an explicit subject name without mutating the object. |
-| `AbilityExtra` | Helpers for compact rule transport and rule-to-query transforms. |
-
-Important behavior:
-
-- Last matching rule wins.
-- `manage` means any action.
-- `all` means any subject.
-- Checks do not return booleans. Use Effect combinators to derive booleans when
-  needed.
-
-## Getting Started
-
-Define your domain subjects as a type-level map:
-
-```ts
-import {Effect} from "effect"
-import {Ability} from "@nmnmcc/ability"
-
-interface Post {
-  readonly id: string
-  readonly authorId: string
-  readonly published: boolean
-  readonly title: string
-  readonly body: string
-}
+| 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.        |
+| `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.    |
+| `Decision`   | `Allow`, `Deny` or `NotApplicable`.                                         |
+| `Authorizer` | An Effect service that checks the principal of the current request.         |
+| `HttpApi`    | Annotations and a middleware for `effect/http-api`. A separate entry point. |
 
-type Subjects = {
-  readonly Post: Post
-}
-```
+## First Steps
 
-Define an ability synchronously:
+Make the principal and the resources. `Resource.Class` works in the same way as
+`Schema.TaggedClass`. The class is a Schema, a constructor, and a resource at
+the same time:
 
 ```ts
-const ability = Ability.define<Subjects>()(function* (ability) {
-  yield* ability.allow("read", "Post")
-
-  yield* ability.allow("update", "Post", {
-    fields: ["title", "body"],
-    conditions: {authorId: "u1"},
-    reason: "Authors can edit their own content"
-  })
-
-  yield* ability.deny("delete", "Post", {
-    conditions: {published: true},
-    reason: "Published posts cannot be deleted"
-  })
-})
+import { Effect, Schema } from "effect"
+import { Decision, Domain, Policy, Principal, Resource } from "@nmnmcc/ability"
+
+class User extends Principal.Class<User>("User")({
+	id: Schema.String,
+}) {}
+
+class Post extends Resource.Class<Post>()("Post", {
+	actions: ["read", "update", "delete"],
+	fields: {
+		id: Schema.String,
+		authorId: Schema.String,
+		published: Schema.Boolean,
+		title: Schema.String,
+		body: Schema.String,
+	},
+}) {}
+
+const Blog = Domain.make({ principal: User, resources: [Post] })
 ```
 
-Check permissions inside an Effect program:
+Make a policy. Each `yield*` gives one rule. The function runs at once and gives
+back the policy:
 
 ```ts
-const post: Post = {
-  id: "p1",
-  authorId: "u1",
-  published: true,
-  title: "Hello",
-  body: "World"
-}
-
-const program = Effect.gen(function* () {
-  yield* Ability.check(ability, {
-    action: "update",
-    subject: "Post",
-    value: post,
-    field: "title"
-  })
-
-  const deleteResult = yield* Ability.check(ability, {
-    action: "delete",
-    subject: "Post",
-    value: post
-  }).pipe(
-    Effect.match({
-      onFailure: (error) =>
-        error._tag === "AuthorizationError" ? error.reason : "unexpected failure",
-      onSuccess: () => "deleted"
-    })
-  )
-
-  return deleteResult
+const policy = Policy.define(Blog)(function* (_) {
+	yield* _.allow("read", Post)
+
+	yield* _.allow("update", Post, {
+		fields: ["title", "body"],
+		when: ($) => $.eq("authorId", $.principal("id")),
+		reason: "Writers may change their own posts",
+	})
+
+	yield* _.deny("delete", Post, {
+		when: ($) => $.eq("published", true),
+		reason: "No one may delete a published post",
+	})
 })
 ```
 
-## Defining Rules
-
-**Syntax**
-
-```ts
-Ability.define<Subjects>()(
-  function* (ability) {
-    yield* ability.allow(action, subject, options)
-    yield* ability.deny(action, subject, options)
-  },
-  options
-)
-```
-
-`Ability.define` returns an `Ability` directly. It is not wrapped in `Effect`.
-The yielded `Rule` values are collected in order and stored immutably.
+The types check every name. `_.allow("fly", Post)` is a type error, because
+`fly` is not an action of `Post`. `$.eq("authorId", 5)` is a type error, because
+`authorId` is a string. `$.principal("name")` is a type error, because the
+principal has no `name` field.
 
-**Example** (Multiple Actions)
+Get a decision:
 
 ```ts
-const ability = Ability.define<Subjects>()(function* (ability) {
-  yield* ability.allow(["read", "update"], "Post", {
-    fields: ["title", "body"],
-    conditions: {authorId: "u1"}
-  })
+const writer = User.make({ id: "u1" })
+const post = Post.make({
+	id: "p1",
+	authorId: "u1",
+	published: true,
+	title: "Hello",
+	body: "World",
 })
-```
-
-**Example** (`manage` and `all`)
 
-```ts
-const ability = Ability.define<Subjects>()(function* (ability) {
-  yield* ability.allow("manage", "all")
-  yield* ability.deny("delete", "Post", {
-    conditions: {published: true},
-    reason: "Published posts cannot be deleted"
-  })
+const decision = Policy.decideSync(policy, {
+	principal: writer,
+	action: "delete",
+	resource: post,
 })
-```
-
-Rules are resolved from the end of the rule list. In the example above, the
-later `deny("delete", "Post")` can override the earlier `allow("manage", "all")`
-when its condition matches.
-
-## Checking Permissions
-
-**Syntax**
 
-```ts
-Ability.check(ability, request)
-ability.pipe(Ability.check(request))
-```
-
-`Ability.check` returns:
-
-```ts
-Effect.Effect<void, Ability.AuthorizationError | Ability.ConditionError | Ability.SubjectDetectionError>
-```
-
-- Success means the request is authorized.
-- `AuthorizationError` means no allow rule matched, or the winning rule was a
-  deny rule.
-- `ConditionError` means condition matching threw while evaluating a rule.
-- `SubjectDetectionError` means the request did not provide a subject and the
-  subject could not be detected from the value.
-
-**Example** (Boolean Derived From Effect)
-
-```ts
-const canUpdateTitle = yield* Ability.check(ability, {
-  action: "update",
-  subject: "Post",
-  value: post,
-  field: "title"
-}).pipe(
-  Effect.match({
-    onFailure: () => false,
-    onSuccess: () => true
-  })
-)
+decision._tag // "Deny"
+Decision.reason(decision) // "No one may delete a published post"
 ```
 
-There is no synchronous `can`, `cannot`, or `allows` API in this package.
+## Resources
 
-## Conditions And Fields
+A resource has a kind name, a list of actions, and Schema fields. Every value
+has a `_tag` field with the kind name. The library uses `_tag` to find the
+resource of a value.
 
-Conditions use CASL's Mongo-style matcher and `MongoQuery` type.
-
-**Example** (Mongo-Style Conditions)
+There are two ways to make a resource:
 
 ```ts
-interface Comment {
-  readonly authorId: string
-  readonly body: string
-}
-
-interface PostWithComments extends Post {
-  readonly comments: ReadonlyArray<Comment>
+// A Schema class. Its body may have its own getters and methods.
+class Bot extends Resource.Class<Bot>()("Bot", {
+	actions: ["read", "update"],
+	fields: { id: Schema.String, ownerUserId: Schema.NullOr(Schema.String) },
+}) {
+	get shared() {
+		return this.ownerUserId === null
+	}
 }
 
-type Subjects = {
-  readonly Post: PostWithComments
-}
-
-const ability = Ability.define<Subjects>()(function* (ability) {
-  yield* ability.allow("read", "Post", {
-    conditions: {
-      published: {$eq: false},
-      comments: {$elemMatch: {authorId: "u1"}}
-    }
-  })
+// Plain objects with a `_tag` field.
+const Trigger = Resource.make("Trigger", {
+	actions: ["read", "write"],
+	fields: { id: Schema.String, enabled: Schema.Boolean },
 })
+const trigger = Trigger.make({ id: "t1", enabled: true })
 ```
 
-Fields are typed as dot paths, with bounded recursion for predictable
-type-checking. CASL-style field patterns are also accepted.
-
-**Example** (Field Restrictions)
+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
-interface Address {
-  readonly city: string
-  readonly street: string
-}
-
-interface PostWithAddress extends Post {
-  readonly address: Address
-}
-
-type Subjects = {
-  readonly Post: PostWithAddress
-}
-
-const ability = Ability.define<Subjects>()(function* (ability) {
-  yield* ability.allow("update", "Post", {
-    fields: ["title", "address.**"],
-    conditions: {authorId: "u1"}
-  })
-})
-
-const post = {} as PostWithAddress
-
-yield* Ability.check(ability, {
-  action: "update",
-  subject: "Post",
-  value: post,
-  field: "address.city"
+class Bot extends Resource.Class<Bot>()("Bot", {
+	actions: ["read", "update"],
+	fields: {
+		id: Schema.String,
+		organizationId: Schema.String,
+		ownerUserId: Schema.NullOr(Schema.String),
+	},
+	path: (f) => ["org", f.organizationId, "user", f.ownerUserId, "bot", f.id],
+}) {}
+
+// Every resource of the organization of the principal.
+_.allow("read", "*", {
+	when: ($) => $.under("org", $.principal("organizationId")),
 })
 ```
 
-When you check a request without `value`, conditional allow rules can still
-authorize the action for the subject type. Pass `value` when you need object
-conditions to be evaluated for a specific resource. Conditional deny rules also
-need a value before their conditions can match; unconditional deny rules still
-apply without a value.
+## Rules
+
+- `_.allow(action, resource, options)` and `_.deny(...)` make rules. The action
+  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`.
+- `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. 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
+
+The builder in `when` has these functions:
+
+| Function                 | True when                                         |
+| ------------------------ | ------------------------------------------------- |
+| `eq`, `ne`               | The field is (not) equal to the value.            |
+| `lt`, `lte`, `gt`, `gte` | The field is less or greater. Numbers or strings. |
+| `in`                     | The field is equal to one of the values.          |
+| `exists`                 | The field is not `null` and not missing.          |
+| `under(...prefix)`       | The path of the resource starts with the prefix.  |
+| `and`, `or`, `not`       | Logic.                                            |
+| `principal(field)`       | Not a test. It gives a field of the principal.    |
+| `predicate(name, test)`  | The test function says yes. It may be an Effect.  |
+
+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)`.
+
+`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 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.
+
+## Policies
+
+A list of rules has a combining algorithm. It decides which rule gives the
+answer when more than one rule applies:
+
+| Algorithm                 | Winner                                   |
+| ------------------------- | ---------------------------------------- |
+| `denyOverrides` (default) | A deny rule wins over every allow rule.  |
+| `permitOverrides`         | An allow rule wins over every deny rule. |
+| `firstApplicable`         | The first rule that applies.             |
+| `lastApplicable`          | The last rule that applies.              |
 
-## Permitted Fields
+```ts
+const policy = Policy.define(Blog, { algorithm: "lastApplicable" })(
+	function* (_) {
+		// ...
+	},
+)
+```
 
-Use `Ability.permittedFields` to derive the request fields allowed by matching
-rules. Allow rules add fields; deny rules remove fields.
+Put policies together:
 
-**Syntax**
+| Combinator                    | Decision                                                         |
+| ----------------------------- | ---------------------------------------------------------------- |
+| `Policy.all([a, b])`          | Every policy must allow. One deny is enough to deny.             |
+| `Policy.any([a, b])`          | One allow is enough.                                             |
+| `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. |
 
-```ts
-Ability.permittedFields(ability, request, {
-  fieldsFrom: (rule) => rule.fields ?? fallbackFields
-})
-```
+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.
 
-**Example**
+For example, a user token may never do more than its member, and the platform
+has deny rules for everyone:
 
 ```ts
-const fields = yield* Ability.permittedFields(
-  ability,
-  {
-    action: "update",
-    subject: "Post",
-    value: post
-  },
-  {
-    fieldsFrom: (rule) => rule.fields ?? ["id", "authorId", "published", "title", "body"]
-  }
+const forToken = Policy.all([memberPolicy, tokenPolicy]).pipe(
+	Policy.ceiling(platformPolicy),
 )
 ```
 
-`fieldsFrom` is used when a matching rule does not declare explicit fields.
+A decision is one of three answers: `Allow`, `Deny`, or `NotApplicable`, when no
+rule gives an answer. A check treats `NotApplicable` as a "no", but an
+authorizer with a decider asks the decider first.
 
-## Subjects
+## Questions to a Policy
 
-A check request can provide the subject name explicitly:
+| Function                 | Answer                                                         |
+| ------------------------ | -------------------------------------------------------------- |
+| `Policy.decide`          | The decision for one resource value, as an `Effect`.           |
+| `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.      |
 
-```ts
-yield* Ability.check(ability, {
-  action: "read",
-  subject: "Post",
-  value: post
-})
-```
+`Policy.residual` puts the principal into every rule and gives a condition on
+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.
 
-You can also wrap a value with a subject name:
+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`.
 
-```ts
-const wrapped = Ability.subject("Post", post)
+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.
 
-yield* Ability.check(ability, {
-  action: "read",
-  value: wrapped
-})
+### Scopes
 
-const original = Ability.unwrapSubject(wrapped)
-```
+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.
 
-`Ability.subject` is pure and does not mutate the wrapped object.
+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.
 
-If neither `subject` nor a typed subject wrapper is provided, configure subject
-detection:
+| 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 ability = Ability.define<Subjects>()(
-  function* (ability) {
-    yield* ability.allow("read", "Post")
-  },
-  {
-    detectSubjectType: (value) => (value as {readonly __typename: "Post"}).__typename
-  }
-)
-
-yield* Ability.check(ability, {
-  action: "read",
-  value: {
-    ...post,
-    __typename: "Post"
-  }
-})
+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"
 ```
 
-Without a custom detector, subject detection falls back to constructor metadata
-when available.
-
-## Action Aliases
-
-Action aliases expand one rule action into additional checkable actions.
-
-**Example**
+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
+function for each kind of node:
 
 ```ts
-const ability = Ability.define<Subjects>()(
-  function* (ability) {
-    yield* ability.allow("modify", "Post", {
-      fields: ["title", "body"],
-      conditions: {authorId: "u1"}
-    })
-  },
-  {
-    actionAliases: {
-      modify: ["update", "delete"]
-    } as const
-  }
-)
+const toSql = Condition.fold<string>({
+	true: () => "TRUE",
+	false: () => "FALSE",
+	compare: (op, field, value) => `${field} ${sqlOperator(op)} ${quote(value)}`,
+	in: (field, values) => `${field} IN (${values.map(quote).join(", ")})`,
+	exists: (field) => `${field} IS NOT NULL`,
+	and: (parts) => `(${parts.join(" AND ")})`,
+	or: (parts) => `(${parts.join(" OR ")})`,
+	not: (part) => `NOT ${part}`,
+})
 
-yield* Ability.check(ability, {
-  action: "update",
-  subject: "Post",
-  value: post,
-  field: "title"
+const program = Effect.gen(function* () {
+	const where = yield* toSql(
+		Policy.residual(policy, { principal, action: "read", kind: "Post" }),
+	)
 })
 ```
 
-Aliases are one-directional. A `modify` rule matches `update` and `delete`, but
-separate `update` and `delete` rules do not imply `modify`.
+`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. 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.
 
-Invalid aliases fail fast:
+## JSON
 
-- `manage` cannot be used as an alias name.
-- Aliases cannot target `manage`.
-- Aliases cannot target an empty list.
-- Cyclic aliases are rejected.
+A policy with no predicates can become JSON:
 
-## Raw Rules And Updates
+```ts
+const PolicySchema = Policy.schema(Blog)
 
-Raw rules are JSON-safe data structures.
+const json = Schema.encodeSync(PolicySchema)(policy)
+const again = Schema.decodeUnknownSync(PolicySchema)(json)
+```
 
-**Syntax**
+Decoding checks every kind, action, field and principal field against the
+domain, and `meta` against the `meta` Schema of the domain. So a policy from a
+database can not name a field that does not exist.
 
-```ts
-Ability.fromRawRules<Subjects>(rules, options)
-Ability.toRawRules(ability)
-Ability.update(ability, rules)
-ability.pipe(Ability.update(rules))
-```
+## Authorizer
 
-**Example**
+An authorizer is an Effect service. It gets the principal of the current
+request, loads its policy, and keeps the policy in a cache.
 
 ```ts
-const ability = yield* Ability.fromRawRules<Subjects>([
-  {
-    action: "read",
-    subject: "Post",
-    conditions: {authorId: "u1"}
-  },
-  {
-    action: "delete",
-    subject: "Post",
-    inverted: true,
-    reason: "No deletes"
-  }
-])
+class Identity extends Context.Service<Identity, User>()("app/Identity") {}
 
-const rules = yield* Ability.toRawRules(ability)
+class Auth extends Authorizer.Service<Auth, { requires: Identity }>()(
+	"app/Auth",
+	Blog,
+) {}
 
-const nextAbility = yield* Ability.update(ability, [
-  {
-    action: "read",
-    subject: "Post"
-  }
-])
+const AuthLive = Authorizer.layer(Auth, {
+	principal: Identity,
+	policy: (user) => loadPolicyOf(user),
+	cache: { capacity: 1000, timeToLive: "30 seconds" },
+})
 ```
 
-`Ability.update` returns a new immutable ability and reuses the current ability
-options, including action aliases and subject detection.
+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`.
 
-`Ability.fromRawRules` and `Ability.update` can fail with:
-
-- `RawRuleError` for invalid raw rules.
-- `AliasError` for invalid action alias configuration.
-
-## Introspection
-
-The introspection helpers are also Effect values and support data-first and
-data-last usage.
-
-| Function | Behavior |
-| -------- | -------- |
-| `Ability.possibleRulesFor` | Returns rules that may apply before field and condition checks. |
-| `Ability.rulesFor` | Returns rules that may apply after field checks, but before condition checks. |
-| `Ability.relevantRuleFor` | Returns the winning rule after field and condition checks. |
-| `Ability.actionsFor` | Returns actions that have rules for a subject. |
-
-**Example**
+Use it in a handler:
 
 ```ts
-const rules = yield* Ability.rulesFor(ability, {
-  action: "update",
-  subject: "Post",
-  field: "title"
-})
-
-const rule = yield* Ability.relevantRuleFor(ability, {
-  action: "delete",
-  subject: "Post",
-  value: post
+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" })
+	// 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"
 })
-
-const actions = yield* ability.pipe(
-  Ability.actionsFor({
-    subject: "Post"
-  })
-)
 ```
 
-`possibleRulesFor`, `rulesFor`, and `actionsFor` can fail with
-`SubjectDetectionError`. `relevantRuleFor` can also fail with `ConditionError`.
+| Function          | What it does                                                                  |
+| ----------------- | ----------------------------------------------------------------------------- |
+| `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.          |
 
-## AbilityExtra
+A check on a kind (`{ action, kind }`) passes only when the policy allows the
+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.
 
-`AbilityExtra` works with already-defined abilities and JSON-safe rules.
+`filter` gives `False` when the principal may act on no value. Then the list is
+empty, and that is not an error.
 
-### Compact Rule Transport
+The errors of a check:
 
-```ts
-import {AbilityExtra} from "@nmnmcc/ability"
+- `Forbidden`: the policy says no. It has the action, the kind, the field, and
+  the reason of the rule.
+- `PolicyUnavailable`: the policy could not be loaded. It keeps the cause.
+- `Pending`: the decider must wait for an answer. It has a `ticket`.
 
-const packed = AbilityExtra.packRules(rules)
-const unpacked = AbilityExtra.unpackRules(packed)
-```
+### Deciders
 
-`packRules` converts raw rules into compact tuples. `unpackRules` restores the
-raw rule objects.
-
-### Default Fields From Conditions
-
-`rulesToFields` extracts scalar condition values from matching allow rules. This
-is useful when creating initial values from authorization rules.
+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:
 
 ```ts
-const defaults = yield* AbilityExtra.rulesToFields(ability, {
-  action: "read",
-  subject: "Post"
+Authorizer.layer(Auth, {
+	principal: Identity,
+	policy: loadPolicyOf,
+	decider: (request) =>
+		requests
+			.create(request)
+			.pipe(Effect.flatMap((ticket) => Authorizer.Pending.make({ ticket }))),
 })
 ```
 
-For a rule with `{conditions: {authorId: "u1"}}`, the returned object includes
-`{authorId: "u1"}`.
+When the answer comes, keep it as a rule, for example in a grant policy that
+comes first: `Policy.firstOf([grants, rules])`.
 
-### Rule-To-Query Conversion
+## HttpApi
 
-Use `rulesToCondition` when you own the logical query representation:
+`@nmnmcc/ability/HttpApi` checks requests in an `effect/http-api` server. Each
+endpoint says what it needs. An endpoint with no annotation is closed, so a new
+endpoint does nothing until you say what it needs:
 
 ```ts
-const condition = yield* AbilityExtra.rulesToCondition(
-  ability,
-  {
-    action: "read",
-    subject: "Post"
-  },
-  (rule) => rule.conditions ?? {},
-  {
-    and: (conditions) => ({$and: conditions}),
-    or: (conditions) => ({$or: conditions}),
-    not: (condition) => ({$not: condition}),
-    empty: () => ({})
-  }
-)
-```
-
-Use `rulesToQuery` for the built-in generic logical shape:
+import * as AbilityHttpApi from "@nmnmcc/ability/HttpApi"
+
+class Authorization extends HttpApiMiddleware.Service<
+	Authorization,
+	{ requires: Identity }
+>()("app/Authorization", { error: AbilityHttpApi.errors }) {}
+
+const update = HttpApiEndpoint.patch("update", "/posts/:id", {
+	params: { id: Schema.String },
+}).annotate(AbilityHttpApi.Required, [
+	AbilityHttpApi.requires(Auth, "update", "Post", (params) =>
+		Posts.find(params["id"]),
+	),
+])
 
-```ts
-const query = yield* ability.pipe(
-  AbilityExtra.rulesToQuery(
-    {
-      action: "read",
-      subject: "Post"
-    },
-    (rule) => rule.conditions ?? {}
-  )
+const health = HttpApiEndpoint.get("health", "/health").annotate(
+	AbilityHttpApi.Required,
+	[],
 )
-```
-
-Rule conversion callbacks may return plain values or Effects. If a conversion
-callback throws, the helper fails with `QueryGenerationError`.
 
-## CASL Peer Dependency
+// The checks run only in a group that uses the middleware.
+const posts = HttpApiGroup.make("posts")
+	.add(update, health)
+	.middleware(Authorization)
 
-This package uses the official CASL rule engine for indexing and Mongo-style
-condition matching, but it does not re-export CASL APIs.
+const AuthorizationLive = AbilityHttpApi.layer(Authorization, Auth)
+```
 
-Import CASL APIs from `@casl/ability` when you need them:
+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
-import {AbilityBuilder, createMongoAbility, subject} from "@casl/ability"
+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 {can, cannot, build} = new AbilityBuilder(createMongoAbility)
+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"] ?? ""),
+	}),
+])
+```
 
-can("read", "Post")
-cannot("delete", "Post", {published: true})
+A path parameter may be `undefined`. A scope with `undefined` in it is a defect,
+so give another value for it.
 
-const caslAbility = build()
-const canRead = caslAbility.can("read", subject("Post", post))
-```
+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.
 
-ORM adapters and `accessibleBy`-style helpers are not implemented here. Use the
-official CASL ecosystem packages for those integrations.
+`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
 
-- [examples/basic.ts](./examples/basic.ts)
-- [examples/advanced.ts](./examples/advanced.ts)
-- [tests/Ability.test.ts](./tests/Ability.test.ts)
+```sh
+node examples/basic.ts
+node examples/authorizer.ts
+node examples/openbot-rbac.ts
+```