@jantstack/adonis-authz 1.0.1 → 1.0.2

package/README.md

@@ -36,7 +36,7 @@ For the OpenFGA driver, also install its SDK (optional peer): `npm i @openfga/sd
 2. **Explicit deny wins.** A deny anywhere in the scope chain blocks the permission even if a role grants it. Removing the deny restores it.
 3. **Expiry is observable.** An assignment past its `expiresAt` grants nothing — enforced in SQL by the `database` driver and by an FGA *condition* in `openfga`, so no scheduler is needed.
 4. **Polymorphic holders.** Users, admins, API integrations — any model with a morph name. Two holders with the same uuid and different type never cross.
-5. **Deny by default.** Unknown permission, role without it, or no valid assignment → `false`. `authorize()` never throws.
+5. **Deny by default.** Unknown permission, role without it, or no valid assignment → `false`. `authorize()` doesn't throw on any of those: an *unanswerable* question is answered "no". A backend that is *unreachable* is a different matter — see below.
 6. **Idempotent writes.** Re-granting doesn't duplicate (it refreshes the expiry); re-revoking is a safe no-op.
 
 These aren't prose promises: they're `tests/…` cases in the contract suite below.
@@ -127,12 +127,20 @@ The import **copies**, it doesn't move: your `authz_*` tables stay intact, so ro
 
 ### Operational notes for this driver
 
-Two properties are worth knowing before you put it in front of production traffic — neither can grant access that wasn't granted, both fail towards *denied*:
+Choosing this driver adds a **second runtime dependency to every authorization check**: the catalog is read from your database and the facts from FGA. If FGA is unreachable, `authorize()` **throws** — it does not quietly return `false`.
+
+That is deliberate. Denying silently during an outage strips every user of their permissions with nothing to indicate why, and sends you looking for a misconfigured role that doesn't exist. Failing loudly says "the backend is down". Access is denied either way; only the diagnosis differs. Wrap the call if your endpoint needs a specific response, and alert on it.
+
+The `database` driver has no equivalent failure: authorization is available whenever your database is, which you need anyway.
+
+Three more properties worth knowing before putting it in front of production traffic — none of them can grant access that wasn't granted, all fail towards *denied*:
 
 - **Changing an expiry is not atomic.** FGA rejects deleting and writing the same tuple key in one transaction, so *replacing* an assignment's expiry is a delete followed by a write. Between the two, `authorize()` answers `false`, and a crash in that window loses the assignment; re-running the grant restores it (writes are idempotent). The driver reads the current tuple first, so this only happens when the expiry actually changes — a first grant is a plain write, and re-granting something identical (a seeder run again) touches nothing at all. That read is a shortcut, not a precondition: if it fails, or if a concurrent writer wins the race, the grant is still written.
 - **Expiry follows the app server's clock.** The `not_expired` condition is evaluated against a `current_time` your process sends with each check, so a skewed clock makes assignments expire early or late. Keep NTP running — the same requirement your JWTs already have.
 
-The `database` driver has neither property: both are consequences of the facts living in another system.
+- **There is no distributed transaction with your database.** A `grant` validates the role against the local catalog and then writes the tuple to FGA. Delete that role from the catalog afterwards and the tuple is orphaned — but `authorize()` finds no permission→role mapping for it and denies, so the inconsistency fails closed. `openfga:import` is likewise not atomic; it is idempotent, so a run that dies half-way is fixed by running it again.
+
+All of these are consequences of the facts living in another system, and none of them apply to the `database` driver.
 
 ## Compatibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jantstack/adonis-authz",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Driver-based authorization engine for AdonisJS + Lucid: hierarchical scopes with downward inheritance, explicit denies, expiring assignments and polymorphic holders. Ships a self-contained database driver and an OpenFGA driver, both judged by the same executable contract suite.",
   "type": "module",
   "license": "MIT",