@warlock.js/access 5.34.1 → 5.34.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/access` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Merge package orientation into the grouped skill index and remove the duplicate overview topic; preserve that orientation in generated LLM projections.
+
 ## 5.32.0 - 2026-10-18
 
 ### Changed

package/llms-full.txt

@@ -4,6 +4,62 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/access/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
+## Package orientation
+
+---
+description: 'Authorization (RBAC + ABAC) for Warlock apps: what a signed-in user is allowed to do. Exports `can`, `authorize`, `gate`, `gateAny`, `definePolicy`, `hasRole`, `access`, `DefaultAccessResolver`, `AccessResolver`, `AccessErrorCodes`. Use for: "check a permission", "restrict this route to users who can update orders", "only the owner can edit", "roles and permissions", "per-tenant roles", "custom role storage". Not this package: login, tokens, user-type gating → @warlock.js/auth; request validation → @warlock.js/seal.'
+---
+
+# @warlock.js/access
+
+Access is the authorization engine. You supply one adapter, an `AccessResolver`, that reads a user's roles and permissions from your storage; then `can(user, "orders.update")` and `gate("orders.update")` work. Two halves: permissions (RBAC grants) and policies (ABAC conditions). Server-only; reads `request.locals.user`, so it sits beside `@warlock.js/auth`.
+
+## The 80% path
+
+1. Use this index for orientation and choose a task below.
+2. Configure the required resolver: `configure-access.md` (`DefaultAccessResolver` for a code-defined catalog, or the ejected DB one); custom storage in `implement-resolver.md`.
+3. Gate routes and check in code: `check-permissions.md`.
+4. Add "only their own / only while pending" rules: `define-policies.md`.
+5. Assign and revoke roles: `manage-roles.md`.
+
+## Conventions and pitfalls
+
+- Two stages: class-level (`gate`, `can`) asks "can they at all?"; instance-level (`authorize` with a `resource`) runs the policy on the loaded row.
+- Decisions fail closed; a missing resolver is a config error, not a default allow.
+- Stack `gate` after `authMiddleware`; access does not authenticate.
+- After changing a user's roles, flush the cache (`access.flush`) or old grants linger.
+- Only need "is admin"? `authMiddleware("admin")` from auth is enough.
+- Do not value-import from client code; type-only imports are fine.
+
+## The mental model in one paragraph
+
+The package owns the **engine** — wildcard matching, caching, ABAC policies, fail-closed decisions. You hand it **one required adapter**, an `AccessResolver`, that reads a user's roles + permissions from however YOUR app stores them (the role→permission catalog lives inside the resolver). Then `can(user, "orders.update")` and `gate("orders.update")` just work. The two concepts inside are **permissions** (RBAC grants) and **policies** (ABAC conditions) — which is why the package is called `access`, not either half.
+
+## When to reach for it
+
+- A Warlock app (already on `@warlock.js/auth`) that needs per-action / per-resource authorization beyond auth's user-type gate.
+- **Multi-tenant** role scoping — `editor` in tenant A, `viewer` in tenant B.
+- "Only their own / only in their tenant / only while pending" conditions → ABAC policies.
+
+Skip if you only need "is the user an admin" — `authMiddleware("admin")` from `@warlock.js/auth` already covers coarse type gating.
+
+## The two-stage model (important)
+
+- **Class-level** (no resource): _"can this user update orders at all?"_ → `gate("orders.update")` in middleware, `can(user, "orders.update")` in code. Cheap, cached, runs before the controller.
+- **Instance-level** (a resource): _"can they update THIS order?"_ → `authorize(user, "orders.update", { resource: order })` in the service, after you load the row. Runs the registered policy on top of the grant.
+
+## What it deliberately doesn't do
+
+- **Authentication.** Use `@warlock.js/auth`; `access` reads `request.locals.user`.
+- **Ship a permission admin UI.** The engine reads permission strings; whether the catalog is code-defined (`DefaultAccessResolver`) or DB-managed (the ejected `DatabaseAccessResolver`) is your resolver's choice — the package ships no admin screens.
+- **ReBAC graphs / row-level query scoping.** Use a policy for "own resource"; graph-scale relationships are out of scope.
+
+## See also
+
+- The `warlock-js-auth` skill index — authentication, the layer below.
+- The `protect-routes` topic of the `warlock-js-auth` skill — `authMiddleware`; stack `gate` after it.
+
+
 ## check-permissions  `@warlock.js/access/check-permissions/SKILL.md`
 
 ---
@@ -431,53 +487,3 @@ If roles live on the user (a `roles` column) or in a token claim, you don't use
 - The `implement-resolver` topic — non-table role storage.
 
 
-## overview  `@warlock.js/access/overview/SKILL.md`
-
----
-name: overview
-description: "@warlock.js/access overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/access` — overview
-
-Authorization for Warlock apps. `@warlock.js/auth` answers _who you are_; `access` answers _what you can do_.
-
-Server-only: `package.json` declares `"warlock": { "environment": "server" }`. `@warlock.js/web`'s build refuses app client code that value-imports this package; type-only imports are allowed, and server loaders/controllers/modules are unaffected.
-
-## The mental model in one paragraph
-
-The package owns the **engine** — wildcard matching, caching, ABAC policies, fail-closed decisions. You hand it **one required adapter**, an `AccessResolver`, that reads a user's roles + permissions from however YOUR app stores them (the role→permission catalog lives inside the resolver). Then `can(user, "orders.update")` and `gate("orders.update")` just work. The two concepts inside are **permissions** (RBAC grants) and **policies** (ABAC conditions) — which is why the package is called `access`, not either half.
-
-## When to reach for it
-
-- A Warlock app (already on `@warlock.js/auth`) that needs per-action / per-resource authorization beyond auth's user-type gate.
-- **Multi-tenant** role scoping — `editor` in tenant A, `viewer` in tenant B.
-- "Only their own / only in their tenant / only while pending" conditions → ABAC policies.
-
-Skip if you only need "is the user an admin" — `authMiddleware("admin")` from `@warlock.js/auth` already covers coarse type gating.
-
-## The two-stage model (important)
-
-- **Class-level** (no resource): _"can this user update orders at all?"_ → `gate("orders.update")` in middleware, `can(user, "orders.update")` in code. Cheap, cached, runs before the controller.
-- **Instance-level** (a resource): _"can they update THIS order?"_ → `authorize(user, "orders.update", { resource: order })` in the service, after you load the row. Runs the registered policy on top of the grant.
-
-## Skills index
-
-- `configure-access` — the required resolver (`DefaultAccessResolver` vs the ejected `DatabaseAccessResolver`), cache + tenant.
-- `check-permissions` — `can` / `cannot` / `canAll` / `canAny` / `authorize*` + the `gate*` middleware.
-- `define-policies` — `definePolicy` for ownership / tenant / state conditions (ABAC).
-- `manage-roles` — assign / revoke via the ejected `UserRole` + `access.flush`, `hasRole` / `hasAnyRole` / `hasAllRoles`.
-- `implement-resolver` — connect the engine to your storage (a DB catalog, a column, a pivot, a token claim).
-
-## What it deliberately doesn't do
-
-- **Authentication.** Use `@warlock.js/auth`; `access` reads `request.locals.user`.
-- **Ship a permission admin UI.** The engine reads permission strings; whether the catalog is code-defined (`DefaultAccessResolver`) or DB-managed (the ejected `DatabaseAccessResolver`) is your resolver's choice — the package ships no admin screens.
-- **ReBAC graphs / row-level query scoping.** Use a policy for "own resource"; graph-scale relationships are out of scope.
-
-## See also
-
-- The `overview` topic of the `warlock-js-auth` skill — authentication, the layer below.
-- The `protect-routes` topic of the `warlock-js-auth` skill — `authMiddleware`; stack `gate` after it.
-
-

package/llms.txt

@@ -6,9 +6,9 @@
 
 ## Skills
 
+- [Package orientation](@warlock.js/access/skills/index.md): Authorization (RBAC + ABAC) for Warlock apps: what a signed-in user is allowed to do. Exports `can`, `authorize`, `gate`, `gateAny`, `definePolicy`, `hasRole`, `access`, `DefaultAccessResolver`, `AccessResolver`, `AccessErrorCodes`. Use for: "check a permission", "restrict this route to users who can update orders", "only the owner can edit", "roles and permissions", "per-tenant roles", "custom role storage". Not this package: login, tokens, user-type gating → @warlock.js/auth; request validation → @warlock.js/seal.
 - [check-permissions](@warlock.js/access/check-permissions/SKILL.md): Check permissions in `@warlock.js/access` — `can` / `cannot` / `canAll` / `canAny` (boolean), `authorize` / `authorizeAll` / `authorizeAny` (throw 403), and the `gate` / `gateAny` / `gateAll` route middleware. Class-level vs instance-level (pass a `resource` to run its policy). TRIGGER: `can(`, `authorize(`, `canAll`, `canAny`, `gate`, `gateAny`, `gateAll`, "check a permission", "protect route by permission", "403 forbidden", "any vs all permissions". Skip: ownership / tenant conditions — the `define-policies` topic; role checks — the `manage-roles` topic.
 - [configure-access](@warlock.js/access/configure-access/SKILL.md): Configure `@warlock.js/access` — the REQUIRED `resolver` (the quickstart `DefaultAccessResolver` over a fixed code map vs the ejected, DB-backed `DatabaseAccessResolver`), `cache: { ttl }`, and the ambient tenant via the resolver's optional `resolveTenant()`. TRIGGER: `AccessConfigurations`, `config.access`, `src/config/access.ts`, "set up permissions", "DefaultAccessResolver", "DatabaseAccessResolver", "access cache ttl", "access tenant". Skip: checking permissions — the `check-permissions` topic; custom storage — the `implement-resolver` topic.
 - [define-policies](@warlock.js/access/define-policies/SKILL.md): ABAC conditions in `@warlock.js/access` — `definePolicy(permission, (user, resource, ctx) => boolean)` adds an instance-level rule (ownership / tenant / state) on top of the RBAC grant, evaluated when an authorization check carries a `resource`. TRIGGER: `definePolicy`, "ownership check", "only their own", "can edit this specific record", "ABAC", "policy", "resource-level permission", `authorize(user, perm, { resource })`. Skip: plain grant checks — the `check-permissions` topic.
 - [implement-resolver](@warlock.js/access/implement-resolver/SKILL.md): Connect `@warlock.js/access` to your role/permission storage by implementing the `AccessResolver` contract (`resolveRoles` / `resolvePermissions`, optional `resolveTenant`) — for a DB-backed catalog, a user column, a pivot table, a token claim, or an external directory. The engine owns matching / caching / policies; the resolver only fetches. TRIGGER: `AccessResolver`, `DatabaseAccessResolver`, `resolveTenant`, "custom resolver", "where do roles come from", "roles in a token claim", "permissions from an external API", "implement resolver". Skip: the quickstart `DefaultAccessResolver` — the `configure-access` topic.
 - [manage-roles](@warlock.js/access/manage-roles/SKILL.md): Assign and read roles in `@warlock.js/access` — the ejected `UserRole.assign` / `UserRole.revoke` (the `user_roles` table) followed by `access.flush`, plus `hasRole` / `hasAnyRole` / `hasAllRoles`. The role→permission catalog is the ejected `Role` table (dynamic). TRIGGER: `UserRole.assign`, `UserRole.revoke`, `access.flush`, `hasRole`, `hasAnyRole`, `hasAllRoles`, `Role` table, "give a user a role", "assign role", "check a user role", "roles per tenant". Skip: permission checks — the `check-permissions` topic; resolver choice — the `configure-access` topic.
-- [overview](@warlock.js/access/overview/SKILL.md): @warlock.js/access overview for orientation and choosing the focused skill for the task.

package/package.json

@@ -5,12 +5,12 @@
     "environment": "server"
   },
   "peerDependencies": {
-    "@warlock.js/auth": "5.34.1",
-    "@warlock.js/cache": "5.34.1",
-    "@warlock.js/cascade": "5.34.1",
-    "@warlock.js/core": "5.34.1",
-    "@warlock.js/logger": "5.34.1",
-    "@warlock.js/seal": "5.34.1"
+    "@warlock.js/auth": "5.34.2",
+    "@warlock.js/cache": "5.34.2",
+    "@warlock.js/cascade": "5.34.2",
+    "@warlock.js/core": "5.34.2",
+    "@warlock.js/logger": "5.34.2",
+    "@warlock.js/seal": "5.34.2"
   },
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.34.1",
+  "version": "5.34.2",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/index.md

@@ -4,11 +4,11 @@ description: 'Authorization (RBAC + ABAC) for Warlock apps: what a signed-in use
 
 # @warlock.js/access
 
-Access is the authorization engine. You supply one adapter, an `AccessResolver`, that reads a user's roles and permissions from your storage; then `can(user, "orders.update")` and `gate("orders.update")` work. Two halves: permissions (RBAC grants) and policies (ABAC conditions). Server-only; reads `request.user`, so it sits beside `@warlock.js/auth`.
+Access is the authorization engine. You supply one adapter, an `AccessResolver`, that reads a user's roles and permissions from your storage; then `can(user, "orders.update")` and `gate("orders.update")` work. Two halves: permissions (RBAC grants) and policies (ABAC conditions). Server-only; reads `request.locals.user`, so it sits beside `@warlock.js/auth`.
 
 ## The 80% path
 
-1. Orient with `overview.md`.
+1. Use this index for orientation and choose a task below.
 2. Configure the required resolver: `configure-access.md` (`DefaultAccessResolver` for a code-defined catalog, or the ejected DB one); custom storage in `implement-resolver.md`.
 3. Gate routes and check in code: `check-permissions.md`.
 4. Add "only their own / only while pending" rules: `define-policies.md`.
@@ -22,3 +22,31 @@ Access is the authorization engine. You supply one adapter, an `AccessResolver`,
 - After changing a user's roles, flush the cache (`access.flush`) or old grants linger.
 - Only need "is admin"? `authMiddleware("admin")` from auth is enough.
 - Do not value-import from client code; type-only imports are fine.
+
+## The mental model in one paragraph
+
+The package owns the **engine** — wildcard matching, caching, ABAC policies, fail-closed decisions. You hand it **one required adapter**, an `AccessResolver`, that reads a user's roles + permissions from however YOUR app stores them (the role→permission catalog lives inside the resolver). Then `can(user, "orders.update")` and `gate("orders.update")` just work. The two concepts inside are **permissions** (RBAC grants) and **policies** (ABAC conditions) — which is why the package is called `access`, not either half.
+
+## When to reach for it
+
+- A Warlock app (already on `@warlock.js/auth`) that needs per-action / per-resource authorization beyond auth's user-type gate.
+- **Multi-tenant** role scoping — `editor` in tenant A, `viewer` in tenant B.
+- "Only their own / only in their tenant / only while pending" conditions → ABAC policies.
+
+Skip if you only need "is the user an admin" — `authMiddleware("admin")` from `@warlock.js/auth` already covers coarse type gating.
+
+## The two-stage model (important)
+
+- **Class-level** (no resource): _"can this user update orders at all?"_ → `gate("orders.update")` in middleware, `can(user, "orders.update")` in code. Cheap, cached, runs before the controller.
+- **Instance-level** (a resource): _"can they update THIS order?"_ → `authorize(user, "orders.update", { resource: order })` in the service, after you load the row. Runs the registered policy on top of the grant.
+
+## What it deliberately doesn't do
+
+- **Authentication.** Use `@warlock.js/auth`; `access` reads `request.locals.user`.
+- **Ship a permission admin UI.** The engine reads permission strings; whether the catalog is code-defined (`DefaultAccessResolver`) or DB-managed (the ejected `DatabaseAccessResolver`) is your resolver's choice — the package ships no admin screens.
+- **ReBAC graphs / row-level query scoping.** Use a policy for "own resource"; graph-scale relationships are out of scope.
+
+## See also
+
+- The `warlock-js-auth` skill index — authentication, the layer below.
+- The `protect-routes` topic of the `warlock-js-auth` skill — `authMiddleware`; stack `gate` after it.

package/skills/overview/SKILL.md

@@ -1,46 +0,0 @@
----
-name: overview
-description: "@warlock.js/access overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/access` — overview
-
-Authorization for Warlock apps. `@warlock.js/auth` answers _who you are_; `access` answers _what you can do_.
-
-Server-only: `package.json` declares `"warlock": { "environment": "server" }`. `@warlock.js/web`'s build refuses app client code that value-imports this package; type-only imports are allowed, and server loaders/controllers/modules are unaffected.
-
-## The mental model in one paragraph
-
-The package owns the **engine** — wildcard matching, caching, ABAC policies, fail-closed decisions. You hand it **one required adapter**, an `AccessResolver`, that reads a user's roles + permissions from however YOUR app stores them (the role→permission catalog lives inside the resolver). Then `can(user, "orders.update")` and `gate("orders.update")` just work. The two concepts inside are **permissions** (RBAC grants) and **policies** (ABAC conditions) — which is why the package is called `access`, not either half.
-
-## When to reach for it
-
-- A Warlock app (already on `@warlock.js/auth`) that needs per-action / per-resource authorization beyond auth's user-type gate.
-- **Multi-tenant** role scoping — `editor` in tenant A, `viewer` in tenant B.
-- "Only their own / only in their tenant / only while pending" conditions → ABAC policies.
-
-Skip if you only need "is the user an admin" — `authMiddleware("admin")` from `@warlock.js/auth` already covers coarse type gating.
-
-## The two-stage model (important)
-
-- **Class-level** (no resource): _"can this user update orders at all?"_ → `gate("orders.update")` in middleware, `can(user, "orders.update")` in code. Cheap, cached, runs before the controller.
-- **Instance-level** (a resource): _"can they update THIS order?"_ → `authorize(user, "orders.update", { resource: order })` in the service, after you load the row. Runs the registered policy on top of the grant.
-
-## Skills index
-
-- `configure-access` — the required resolver (`DefaultAccessResolver` vs the ejected `DatabaseAccessResolver`), cache + tenant.
-- `check-permissions` — `can` / `cannot` / `canAll` / `canAny` / `authorize*` + the `gate*` middleware.
-- `define-policies` — `definePolicy` for ownership / tenant / state conditions (ABAC).
-- `manage-roles` — assign / revoke via the ejected `UserRole` + `access.flush`, `hasRole` / `hasAnyRole` / `hasAllRoles`.
-- `implement-resolver` — connect the engine to your storage (a DB catalog, a column, a pivot, a token claim).
-
-## What it deliberately doesn't do
-
-- **Authentication.** Use `@warlock.js/auth`; `access` reads `request.locals.user`.
-- **Ship a permission admin UI.** The engine reads permission strings; whether the catalog is code-defined (`DefaultAccessResolver`) or DB-managed (the ejected `DatabaseAccessResolver`) is your resolver's choice — the package ships no admin screens.
-- **ReBAC graphs / row-level query scoping.** Use a policy for "own resource"; graph-scale relationships are out of scope.
-
-## See also
-
-- The `overview` topic of the `warlock-js-auth` skill — authentication, the layer below.
-- The `protect-routes` topic of the `warlock-js-auth` skill — `authMiddleware`; stack `gate` after it.