anbaric 1.32.0 → 1.33.0

package/docs/README.md

@@ -26,6 +26,7 @@ What the framework gives you, one capability at a time.
 - [Documents and secrets](features/documents-and-secrets.md) — the JSON and secret stores
 - [The SQL store](features/sql-store.md) — a relational database for structured data
 - [Auditing](features/auditing.md) — the record of who changed what
+- [Entitlements](features/entitlements.md) — what a user has been granted, checked per request
 - [Serving a web UI](features/serving-a-web-ui.md) — putting your data on a page
 - [The admin console and widgets](features/admin-console-and-widgets.md) — dashboards and plugins
 - [Deploying](features/deploying.md) — from laptop to Anbaric Cloud

package/docs/api/environment.md

@@ -35,6 +35,7 @@ defaulting to a local implementation otherwise).
 | `ANBARIC_SECRET_STORE_TYPE` | the secret store | in-memory (encrypted) |
 | `ANBARIC_SQL_STORE_TYPE` | the SQL store (`sqlite` / `cloud`\|`postgres`) | SQLite |
 | `ANBARIC_SESSION_RESOLVER_TYPE` | how `Human.fromSession` resolves sessions | in-memory |
+| `ANBARIC_ENTITLEMENTS_TYPE` | how `hasEntitlement` is answered (`cloud` → platform) | permissive (always `true`) |
 
 ## Store configuration
 

package/docs/api/typescript.md

@@ -10,6 +10,7 @@ import {
     Job, PropertyDefinition,
     Code, Human, SystemActor, Agent, OpenAIAgent, RemoteLLMAgenticAction,
     JsonStoreFactory, SecretStoreFactory, SqlStoreFactory,
+    registerEntitlement, hasEntitlement,
 } from "anbaric";
 
 import type {Actor, ActorType, JsonSchema} from "anbaric";

package/docs/features/entitlements.md

@@ -0,0 +1,79 @@
+# Entitlements
+
+Roles say what kind of user someone is. **Entitlements** say what a particular
+user has been given: access to a beta feature, an export capability, a paid
+tier. Your app declares the entitlements it cares about and asks whether the
+signed-in user holds one; administrators hand them out from the console.
+
+## Declare what you check
+
+Register each entitlement once, at startup. That makes it visible in the
+console so it can be granted, and gives it a note explaining what it unlocks.
+
+```ts
+import {registerEntitlement} from "anbaric";
+
+await registerEntitlement("export", "Can export reports as CSV");
+await registerEntitlement("beta", "Sees features still in preview");
+```
+
+Registration is idempotent and scoped to your app - `export` in your app is a
+different entitlement from `export` in another.
+
+## Check the signed-in user
+
+`hasEntitlement` takes the incoming request (it reads the `anbaric_session`
+cookie, exactly as `Human.fromSession` does) or a raw session token, resolves
+the user, and answers for **your app**:
+
+```ts
+import {hasEntitlement} from "anbaric";
+
+server.on("request", async (request, response) => {
+    if (request.url === "/export") {
+        if (! await hasEntitlement(request, "export")) {
+            response.writeHead(403).end("You don't have the export entitlement");
+            return;
+        }
+        ...
+    }
+});
+```
+
+A request with no session, or one the platform can't resolve, is simply not
+entitled - `hasEntitlement` returns `false` rather than throwing.
+
+## Global entitlements
+
+Some entitlements aren't about one app. A **global entitlement** belongs to no
+app and is created in the console, never by `registerEntitlement`. Every tenant
+starts with one, `access`.
+
+A grant can be scoped too. Granting a user `access` **for your app** and
+granting them `access` **globally** both make `hasEntitlement(request, "access")`
+return `true` in your app; only the global grant also satisfies every other app.
+
+| Definition | Grant | `hasEntitlement(request, "access")` in `my-app` |
+| --- | --- | --- |
+| global `access` | `my-app` / `access` | true |
+| global `access` | global / `access` | true (and in every other app) |
+| global `access` | `other-app` / `access` | false |
+
+## Granting
+
+Apps can't grant. An administrator opens **Entitlements** in the console, picks
+the user, the entitlement and its scope, and adds a note; the same page revokes
+grants and creates global entitlements. Every grant records who made it.
+
+## Locally
+
+There's no console on your laptop, so the local implementation is
+**permissive**: `hasEntitlement` always returns `true`. Your code paths run
+unchanged; deployed, the platform answers for real. As with every other
+service, the switch is the environment (`ANBARIC_ENTITLEMENTS_TYPE`), set by the
+platform - don't set it yourself.
+
+## Next
+
+- [Authorization with actors and roles](../patterns/authorization.md) - roles, predicates and attribution
+- [Environment and factories](../api/environment.md)

package/docs/patterns/authorization.md

@@ -53,6 +53,27 @@ if (!user.roles.includes("manager")) {
 await machine.updateJob(jobId, new Map([["approved", true]]), user);
 ```
 
+## Grant capabilities with entitlements
+
+Roles describe a kind of user; an **entitlement** is something a specific user
+has been given - a beta feature, an export capability, a paid tier. Declare the
+ones your app checks at startup and test them against the request, the same way
+you resolve the actor:
+
+```ts
+import {hasEntitlement, registerEntitlement} from "anbaric";
+
+await registerEntitlement("export", "Can export reports as CSV");   // at startup
+
+if (! await hasEntitlement(request, "export")) {                     // per request
+    response.writeHead(403).end("You don't have the export entitlement");
+    return;
+}
+```
+
+Administrators grant and revoke them from the console's **Entitlements** page;
+locally every check passes. See [Entitlements](../features/entitlements.md).
+
 ## Design tips
 
 - **Least privilege.** Give actors the narrowest roles that let them do their job;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "Everything needed to write an Anbaric app: state machines, jobs, document and secret stores, local in-memory implementations and the Anbaric Cloud clients",
   "license": "MIT",
   "type": "module",
@@ -24,9 +24,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.32.0",
-    "anbaric-data-store": "^1.32.0",
-    "anbaric-state-machine": "^1.32.0",
-    "anbaric-tsapi": "^1.32.0"
+    "anbaric-impl-cloud": "^1.33.0",
+    "anbaric-data-store": "^1.33.0",
+    "anbaric-state-machine": "^1.33.0",
+    "anbaric-tsapi": "^1.33.0"
   }
 }