@nmnmcc/ability 0.1.0 → 0.3.0

package/README.md

@@ -1,251 +1,434 @@
 # @nmnmcc/ability
 
-An Effect-style authorization library inspired by CASL.
+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.
 
-## Installation
+The library is made with [Effect](https://effect.website) only:
 
-```sh
-yarn add @nmnmcc/ability
-```
+- 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".
 
-The public API is a module of functions:
+## Requirements
 
-- `Ability.define` synchronously builds an immutable ability from a generator DSL.
-- `Ability.check` is the only authorization check API and returns `Effect<void, AuthorizationError | PredicateError | ConditionError>`.
-- There is no synchronous `can` / `cannot` / `allows` API. Boolean checks are derived with Effect combinators.
-- ORM adapters and `accessibleBy`-style helpers are intentionally out of scope.
+- 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.
 
-## Basic usage
+## Install
 
-```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
-}
+```sh
+pnpm add @nmnmcc/ability effect
+```
 
-type Subjects = {
-  readonly Post: Post
-}
+## Overview
 
-const ability = Ability.define<Subjects>()(function* (ability) {
-  yield* ability.allow("read", "Post")
+```ts
+import {
+	Authorizer,
+	Condition,
+	Decision,
+	Domain,
+	Policy,
+	Principal,
+	Resource,
+	Rule,
+} from "@nmnmcc/ability"
+import * as AbilityHttpApi from "@nmnmcc/ability/HttpApi"
+```
 
-  yield* ability.allow("update", "Post", {
-    fields: ["title", "body"],
-    when: (post) => post.authorId === "u1"
-  })
+| 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. |
 
-  yield* ability.deny("delete", "Post", {
-    when: (post) => post.published,
-    reason: "Published posts cannot be deleted"
-  })
-})
+## First Steps
 
-const program = Effect.gen(function* () {
-  const post = {} as Post
+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:
 
-  yield* Ability.check(ability, {
-    action: "update",
-    subject: "Post",
-    value: post,
-    field: "title"
-  })
-})
+```ts
+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] })
 ```
 
-Denied checks fail through the Effect error channel:
+Make a policy. Each `yield*` gives one rule. The function runs at once and gives
+back the policy:
 
 ```ts
-const guarded = Ability.check(ability, {
-  action: "delete",
-  subject: "Post",
-  value: {
-    id: "p1",
-    authorId: "u1",
-    published: true,
-    title: "Hello",
-    body: "World"
-  }
-}).pipe(
-  Effect.catchTag("AuthorizationError", (error) => Effect.succeed(error.reason))
-)
+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",
+	})
+})
 ```
 
-## CASL-style rules
+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.
 
-Use `manage` for any action and `all` for any subject:
+Get a decision:
 
 ```ts
-const ability = Ability.define<Subjects>()(function* (ability) {
-  yield* ability.allow("manage", "all")
-  yield* ability.deny("delete", "Post", {
-    conditions: { published: true }
-  })
+const writer = User.make({ id: "u1" })
+const post = Post.make({
+	id: "p1",
+	authorId: "u1",
+	published: true,
+	title: "Hello",
+	body: "World",
 })
+
+const decision = Policy.decideSync(policy, {
+	principal: writer,
+	action: "delete",
+	resource: post,
+})
+
+decision._tag // "Deny"
+Decision.reason(decision) // "No one may delete a published post"
 ```
 
-`allow` and `deny` accept arrays:
+## Resources
+
+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.
+
+There are two ways to make a resource:
 
 ```ts
-yield* ability.allow(["read", "update"], "Post", {
-  fields: ["title", "body"],
-  conditions: { authorId: "u1" }
+// 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
+	}
+}
+
+// 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 })
 ```
 
-`conditions` use Mongo-style object matching through `@ucast/mongo2js` for in-memory objects only:
+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
-yield* ability.allow("read", "Post", {
-  conditions: {
-    tags: { $in: ["effect"] },
-    comments: { $elemMatch: { authorId: "u1" } }
-  }
+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")),
 })
 ```
 
-`conditions` and `when` are combined with AND. Predicate failures remain typed Effect failures.
-
-Action aliases can expand one rule into several checkable actions:
+## 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 ability = Ability.define<Subjects>()(
-  function* (ability) {
-    yield* ability.allow("modify", "Post", {
-      fields: ["title", "body"]
-    })
-  },
-  {
-    actionAliases: {
-      modify: ["update", "delete"]
-    } as const
-  }
+const policy = Policy.define(Blog, { algorithm: "lastApplicable" })(
+	function* (_) {
+		// ...
+	},
 )
-
-yield* Ability.check(ability, {
-  action: "update",
-  subject: "Post",
-  value: post,
-  field: "title"
-})
 ```
 
-Aliases are one-directional: a `modify` rule matches `update`, but separate `update` and `delete` rules do not imply `modify`.
+Put policies together:
 
-## Subjects and fields
+| 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. |
 
-DTOs can be wrapped without mutation:
+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",
-  value: Ability.subject("Post", post)
-})
+const forToken = Policy.all([memberPolicy, tokenPolicy]).pipe(
+	Policy.ceiling(platformPolicy),
+)
 ```
 
-You can also pass `detectSubjectType` to `define` or `make`.
+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.
+
+## Questions to a Policy
+
+| 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.      |
+
+`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.
 
-Fields support dot paths and CASL-style patterns:
+## Queries
+
+Change a residual condition into a query with `Condition.fold`. You give one
+function for each kind of node:
 
 ```ts
-yield* ability.allow("update", "Post", {
-  fields: ["title", "comments.**"]
+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}`,
 })
+
+const where =
+	yield *
+	toSql(Policy.residual(policy, { principal, action: "read", kind: "Post" }))
 ```
 
-To filter request payloads, compute permitted fields as an Effect:
+`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.
+
+## JSON
+
+A policy with no predicates can become JSON:
 
 ```ts
-const fields = yield* Ability.permittedFields(ability, {
-  action: "update",
-  subject: "Post",
-  value: post
-}, {
-  fieldsFrom: (rule) => rule.fields ?? ["title", "body"]
-})
+const PolicySchema = Policy.schema(Blog)
+
+const json = Schema.encodeSync(PolicySchema)(policy)
+const again = Schema.decodeUnknownSync(PolicySchema)(json)
 ```
 
-For debugging or extensions, inspect indexed rules as Effects:
+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.
+
+## Authorizer
+
+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 rules = yield* Ability.rulesFor(ability, {
-  action: "update",
-  subject: "Post",
-  field: "title"
-})
+class Identity extends Context.Service<Identity, User>()("app/Identity") {}
 
-const rule = yield* Ability.relevantRuleFor(ability, {
-  action: "delete",
-  subject: "Post",
-  value: post
-})
+class Auth extends Authorizer.Service<Auth, { requires: Identity }>()(
+	"app/Auth",
+	Blog,
+) {}
 
-const actions = yield* Ability.actionsFor(ability, {
-  subject: "Post"
+const AuthLive = Authorizer.layer(Auth, {
+	principal: Identity,
+	policy: (user) => loadPolicyOf(user),
+	cache: { capacity: 1000, timeToLive: "30 seconds" },
 })
 ```
 
-## Raw rules and dynamic updates
-
-Raw rules are JSON-safe and do not include `when` predicates:
+Use it in a handler:
 
 ```ts
-const ability = yield* Ability.fromRawRules<Subjects>([
-  { action: "read", subject: "Post", conditions: { authorId: "u1" } },
-  { action: "delete", subject: "Post", inverted: true, reason: "No deletes" }
-])
-
-const rules = yield* Ability.toRawRules(ability)
+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" })
 ```
 
-Use `AbilityExtra` for compact raw-rule transport and ORM-independent rule transforms:
+| 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.          |
 
-```ts
-import { AbilityExtra } from "@nmnmcc/ability"
+A check on a kind (`{ action, kind }`) passes only when the policy allows the
+act on every value of the kind.
 
-const packed = AbilityExtra.packRules(rules)
-const unpacked = AbilityExtra.unpackRules(packed)
+The errors of a check:
 
-const defaults = yield* AbilityExtra.rulesToFields(ability, {
-  action: "read",
-  subject: "Post"
-})
+- `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 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: () => ({})
-  }
-)
+### 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:
+
+```ts
+Authorizer.layer(Auth, {
+	principal: Identity,
+	policy: loadPolicyOf,
+	decider: (request) =>
+		requests
+			.create(request)
+			.pipe(Effect.flatMap((ticket) => Authorizer.Pending.make({ ticket }))),
+})
 ```
 
-Rule transforms fail with `QueryGenerationError` when a relevant rule contains a `when` predicate, because function predicates cannot be serialized into a query.
+When the answer comes, keep it as a rule, for example in a grant policy that
+comes first: `Policy.firstOf([grants, rules])`.
 
-`Ability` stays immutable. Use `AbilityRef` when an application needs to replace the current ability:
+## HttpApi
 
-```ts
-import { AbilityRef } from "@nmnmcc/ability"
+`@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:
 
-const ref = AbilityRef.make(ability)
+```ts
+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"]),
+	),
+])
 
-const unsubscribe = yield* AbilityRef.on(ref, "updated", () =>
-  Effect.sync(() => {
-    console.log("ability updated")
-  }))
+const health = HttpApiEndpoint.get("health", "/health").annotate(
+	AbilityHttpApi.Required,
+	[],
+)
 
-yield* AbilityRef.set(ref, nextAbility)
-unsubscribe()
+const AuthorizationLive = AbilityHttpApi.layer(Authorization, Auth)
 ```
 
-See [examples/basic.ts](./examples/basic.ts), [examples/advanced.ts](./examples/advanced.ts), and [tests/Ability.test.ts](./tests/Ability.test.ts).
+`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
+
+```sh
+node examples/basic.ts
+node examples/authorizer.ts
+node examples/openbot-rbac.ts
+```