@nmnmcc/ability 0.2.0 → 0.3.0

package/README.md

@@ -1,581 +1,434 @@
 # @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.
+| 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. |
 
-## Getting Started
+## First Steps
 
-Define your domain subjects as a type-level map:
+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
-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
-}
-
-type Subjects = {
-  readonly Post: Post
-}
+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] })
 ```
 
-Define an ability synchronously:
+Make a policy. Each `yield*` gives one rule. The function runs at once and gives
+back the policy:
 
 ```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"
-  })
+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",
+	})
 })
 ```
 
-Check permissions inside an Effect program:
+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.
 
-```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
-})
-```
-
-## Defining Rules
-
-**Syntax**
+Get a decision:
 
 ```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.
-
-**Example** (Multiple Actions)
-
-```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))
+decision._tag // "Deny"
+Decision.reason(decision) // "No one may delete a published post"
 ```
 
-`Ability.check` returns:
+## Resources
 
-```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
-  })
-)
-```
-
-There is no synchronous `can`, `cannot`, or `allows` API in this package.
-
-## Conditions And Fields
-
-Conditions use CASL's Mongo-style matcher and `MongoQuery` type.
-
-**Example** (Mongo-Style Conditions)
-
-```ts
-interface Comment {
-  readonly authorId: string
-  readonly body: string
-}
+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.
 
-interface PostWithComments extends Post {
-  readonly comments: ReadonlyArray<Comment>
-}
-
-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"}}
-    }
-  })
-})
-```
-
-Fields are typed as dot paths, with bounded recursion for predictable
-type-checking. CASL-style field patterns are also accepted.
-
-**Example** (Field Restrictions)
+There are two ways to make a resource:
 
 ```ts
-interface Address {
-  readonly city: string
-  readonly street: string
-}
-
-interface PostWithAddress extends Post {
-  readonly address: Address
+// 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: 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"
+// 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 })
 ```
 
-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.
-
-## Permitted Fields
-
-Use `Ability.permittedFields` to derive the request fields allowed by matching
-rules. Allow rules add fields; deny rules remove fields.
-
-**Syntax**
+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
-Ability.permittedFields(ability, request, {
-  fieldsFrom: (rule) => rule.fields ?? fallbackFields
+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")),
 })
 ```
 
-**Example**
+## 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: `settings.*` covers
+  `settings.model`.
+- `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.
+
+## 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.
+
+## 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.              |
 
 ```ts
-const fields = yield* Ability.permittedFields(
-  ability,
-  {
-    action: "update",
-    subject: "Post",
-    value: post
-  },
-  {
-    fieldsFrom: (rule) => rule.fields ?? ["id", "authorId", "published", "title", "body"]
-  }
+const policy = Policy.define(Blog, { algorithm: "lastApplicable" })(
+	function* (_) {
+		// ...
+	},
 )
 ```
 
-`fieldsFrom` is used when a matching rule does not declare explicit fields.
+Put policies together:
 
-## Subjects
+| 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. |
 
-A check request can provide the subject name explicitly:
+For example, a user token may never do more than its member, and the platform
+has deny rules for everyone:
 
 ```ts
-yield* Ability.check(ability, {
-  action: "read",
-  subject: "Post",
-  value: post
-})
+const forToken = Policy.all([memberPolicy, tokenPolicy]).pipe(
+	Policy.ceiling(platformPolicy),
+)
 ```
 
-You can also wrap a value with a subject name:
+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.
 
-```ts
-const wrapped = Ability.subject("Post", post)
+## Questions to a Policy
 
-yield* Ability.check(ability, {
-  action: "read",
-  value: wrapped
-})
+| 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.permittedFields` | The fields of a value that the policy lets a request use.      |
 
-const original = Ability.unwrapSubject(wrapped)
-```
+`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.
 
-`Ability.subject` is pure and does not mutate the wrapped object.
+## Queries
 
-If neither `subject` nor a typed subject wrapper is provided, configure subject
-detection:
+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("read", "Post")
-  },
-  {
-    detectSubjectType: (value) => (value as {readonly __typename: "Post"}).__typename
-  }
-)
-
-yield* Ability.check(ability, {
-  action: "read",
-  value: {
-    ...post,
-    __typename: "Post"
-  }
+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}`,
 })
-```
 
-Without a custom detector, subject detection falls back to constructor metadata
-when available.
+const where =
+	yield *
+	toSql(Policy.residual(policy, { principal, action: "read", kind: "Post" }))
+```
 
-## Action Aliases
+`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.
 
-Action aliases expand one rule action into additional checkable actions.
+## JSON
 
-**Example**
+A policy with no predicates can become JSON:
 
 ```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 PolicySchema = Policy.schema(Blog)
 
-yield* Ability.check(ability, {
-  action: "update",
-  subject: "Post",
-  value: post,
-  field: "title"
-})
+const json = Schema.encodeSync(PolicySchema)(policy)
+const again = Schema.decodeUnknownSync(PolicySchema)(json)
 ```
 
-Aliases are one-directional. A `modify` rule matches `update` and `delete`, but
-separate `update` and `delete` rules do not imply `modify`.
+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.
 
-Invalid aliases fail fast:
+## Authorizer
 
-- `manage` cannot be used as an alias name.
-- Aliases cannot target `manage`.
-- Aliases cannot target an empty list.
-- Cyclic aliases are rejected.
-
-## Raw Rules And Updates
-
-Raw rules are JSON-safe data structures.
-
-**Syntax**
-
-```ts
-Ability.fromRawRules<Subjects>(rules, options)
-Ability.toRawRules(ability)
-Ability.update(ability, rules)
-ability.pipe(Ability.update(rules))
-```
-
-**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.
-
-`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 actions = yield* ability.pipe(
-  Ability.actionsFor({
-    subject: "Post"
-  })
-)
+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" })
 ```
 
-`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.                               |
+| `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.
 
-`AbilityExtra` works with already-defined abilities and JSON-safe rules.
+The errors of a check:
 
-### Compact Rule Transport
+- `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`.
 
-```ts
-import {AbilityExtra} from "@nmnmcc/ability"
-
-const packed = AbilityExtra.packRules(rules)
-const unpacked = AbilityExtra.unpackRules(packed)
-```
-
-`packRules` converts raw rules into compact tuples. `unpackRules` restores the
-raw rule objects.
+### Deciders
 
-### 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
-
-This package uses the official CASL rule engine for indexing and Mongo-style
-condition matching, but it does not re-export CASL APIs.
 
-Import CASL APIs from `@casl/ability` when you need them:
-
-```ts
-import {AbilityBuilder, createMongoAbility, subject} from "@casl/ability"
-
-const {can, cannot, build} = new AbilityBuilder(createMongoAbility)
-
-can("read", "Post")
-cannot("delete", "Post", {published: true})
-
-const caslAbility = build()
-const canRead = caslAbility.can("read", subject("Post", post))
+const AuthorizationLive = AbilityHttpApi.layer(Authorization, Auth)
 ```
 
-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
+```