@aooth/arbac 0.1.3 → 0.1.4

package/README.md

@@ -33,6 +33,44 @@ Full docs, API reference, and recipes: **https://aooth.moost.org/arbac/**
 - [Codegen CLI](https://aooth.moost.org/arbac/codegen)
 - [API reference](https://aooth.moost.org/api/arbac)
 
+## Deny is binary on (resource, action)
+
+`.deny(resource, action)` short-circuits the entire `(resource, action)` tuple — there is no scope or filter parameter. Once a deny rule's action regex matches, `evaluate()` returns `{ allowed: false }` immediately, before any other role's `allow` scopes are even constructed (see `arbac-core/src/arbac.ts:126-131`).
+
+If you need "hide rows where condition X", express it as an `allow` with a filter that excludes X, not as a partial deny:
+
+```ts
+// ✗ Not supported — no row-level deny.
+// .deny("tasks", "query", { scope: { filter: { status: "secret" } } })
+
+// ✓ Use a filtered allow instead.
+allowTableRead<UserAttrs, Scope>("tasks", {
+  scope: (attrs) => ({
+    filter: { tenantId: attrs.tenantId, status: { $ne: "secret" } },
+  }),
+});
+```
+
+Pinned by `UNION-03` and `UNION-05` in `packages/e2e-demo/test/arbac-union.spec.ts` — unscoped deny short-circuits sibling allows, and wildcard `.deny("tasks", "*")` 403s both row-allow (`markDone`) and set-allow (`new`) tuples.
+
+## Scopes from multiple roles union via `$or` — permissive wins
+
+When a user has multiple roles that each `allow` the same `(resource, action)`, their scopes are merged disjunctively via `mergeScopeFilters` (see `packages/arbac/src/scope/filter.ts`). A row matches if ANY scope's filter matches. Consequence: if one scope has no filter (rule registered without `scope`, or with `filter: undefined` / `filter: {}`), the union widens to universe and the more restrictive filters in sibling scopes are silently dropped.
+
+```ts
+// Role "viewer" — tenant-scoped read on tasks.
+.use(allowTableRead("tasks", {
+  scope: (attrs) => ({ filter: { tenantId: attrs.tenantId } }),
+}))
+
+// Role "tasks-everywhere" — unscoped read on tasks (e.g., for an audit role).
+.allow("tasks", "query")  // no scope ← contributes universe to the union
+
+// A user with both roles sees ALL tasks (universe wins), not just their tenant.
+```
+
+This is the natural `$or` semantic: union of "tenant rows" and "all rows" is "all rows". The takeaway: don't grant an unscoped allow on a resource that other roles are trying to filter. Pinned by the `transformArbacFilter` empty-vs-undefined coercion tests in `packages/arbac-moost/src/db/shared-read-helpers.spec.ts`.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/arbac",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Batteries-included RBAC: builder API, privilege factories, scope merge utilities",
   "keywords": [
     "access-control",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@aooth/arbac-core": "0.1.3"
+    "@aooth/arbac-core": "0.1.4"
   },
   "scripts": {
     "build": "vp pack",