@warlock.js/access 5.19.0 → 5.20.0

package/skills/implement-resolver/SKILL.md

@@ -1,106 +1,106 @@
----
-name: implement-resolver
-description: "Implement a resolver in @warlock.js/access; use when you need to implement resolver."
----
-
-# Implement a resolver
-
-The resolver is the ONE thing only you can write — your schema — and it's just a function over your own data. The engine does matching, caching, policies, and fail-closed for you.
-
-```ts
-export interface AccessResolver {
-  resolveRoles(user: Auth, tenant?: string): Promise<string[]>; //       powers hasRole
-  resolvePermissions(user: Auth, tenant?: string): Promise<string[]>; // powers can / authorize
-  resolveTenant?(user: Auth): string | undefined; //                     optional ambient tenant
-}
-```
-
-Register it: `access: { resolver: new MyResolver() }`.
-
-## The default: dynamic, DB-backed (ejected)
-
-`npx warlock add access` ejects this `DatabaseAccessResolver` — roles come from the `user_roles` table, permissions are joined through the `roles` catalog table. This is what most apps run, because admins manage roles + permissions at runtime.
-
-```ts
-import type { AccessResolver } from "@warlock.js/access";
-import type { Auth } from "@warlock.js/auth";
-import { Role } from "app/access/models/role";
-import { UserRole } from "app/access/models/user-role";
-
-export class DatabaseAccessResolver implements AccessResolver {
-  public async resolveRoles(user: Auth, tenant?: string): Promise<string[]> {
-    return UserRole.rolesFor(user, tenant);
-  }
-
-  public async resolvePermissions(user: Auth, tenant?: string): Promise<string[]> {
-    const names = await this.resolveRoles(user, tenant);
-
-    if (names.length === 0) return [];
-
-    const roles = await Role.query().whereIn("name", names).get();
-
-    return [...new Set(roles.flatMap((role) => role.permissions))];
-  }
-
-  // Multi-tenant? Uncomment to scope checks to the user's tenant. Derive it from
-  // the user — never trust client-supplied request input for the tenant boundary:
-  // public resolveTenant(user: Auth): string | undefined {
-  //   return user.get("organization_id");
-  // }
-}
-```
-
-## Other recipes
-
-**A single role column, permissions mapped in code**
-
-```ts
-class ColumnResolver implements AccessResolver {
-  public constructor(private readonly roles: Record<string, string[]>) {}
-  public async resolveRoles(user: Auth): Promise<string[]> {
-    return [user.get("role")].filter(Boolean);
-  }
-  public async resolvePermissions(user: Auth): Promise<string[]> {
-    return (await this.resolveRoles(user)).flatMap((role) => this.roles[role] ?? []);
-  }
-}
-```
-
-**Roles from a token claim (external IdP — no DB)**
-
-```ts
-class ClaimResolver implements AccessResolver {
-  public async resolveRoles(user: Auth): Promise<string[]> {
-    return user.get("decodedAccessToken")?.roles ?? [];
-  }
-  public async resolvePermissions(user: Auth): Promise<string[]> {
-    return user.get("decodedAccessToken")?.permissions ?? [];
-  }
-}
-```
-
-**Direct permissions per user (role is just a label)**
-
-```ts
-class DirectResolver implements AccessResolver {
-  public async resolveRoles(user: Auth): Promise<string[]> {
-    return [user.get("role")];
-  }
-  public async resolvePermissions(user: Auth): Promise<string[]> {
-    const rows = await UserPermission.query().where({ user_id: user.id }).get();
-    return rows.map((row) => row.get("name") as string);
-  }
-}
-```
-
-## Rules
-
-- **Only fetch — never cache inside the resolver.** The engine caches per `(user, tenant)`; caching twice causes stale grants. Invalidate with `access.flush(user, tenant)` when your data changes.
-- Return plain `string[]`. Wildcards (`orders.*`, `*`) in the returned permissions are honored by the engine.
-- `resolveRoles` and `resolvePermissions` may read **different** sources — roles and permissions are independent axes (a role can be a pure label with permissions granted directly).
-- Throwing from the resolver fails the check **closed** (denied + logged).
-
-## See also
-
-- [`@warlock.js/access/configure-access/SKILL.md`](@warlock.js/access/configure-access/SKILL.md) — the quickstart `DefaultAccessResolver`.
-```
+---
+name: implement-resolver
+description: '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` — `@warlock.js/access/configure-access/SKILL.md`.'
+---
+
+# Implement a resolver
+
+The resolver is the ONE thing only you can write — your schema — and it's just a function over your own data. The engine does matching, caching, policies, and fail-closed for you.
+
+```ts
+export interface AccessResolver {
+  resolveRoles(user: Auth, tenant?: string): Promise<string[]>; //       powers hasRole
+  resolvePermissions(user: Auth, tenant?: string): Promise<string[]>; // powers can / authorize
+  resolveTenant?(user: Auth): string | undefined; //                     optional ambient tenant
+}
+```
+
+Register it: `access: { resolver: new MyResolver() }`.
+
+## The default: dynamic, DB-backed (ejected)
+
+`npx warlock add access` ejects this `DatabaseAccessResolver` — roles come from the `user_roles` table, permissions are joined through the `roles` catalog table. This is what most apps run, because admins manage roles + permissions at runtime.
+
+```ts
+import type { AccessResolver } from "@warlock.js/access";
+import type { Auth } from "@warlock.js/auth";
+import { Role } from "app/access/models/role";
+import { UserRole } from "app/access/models/user-role";
+
+export class DatabaseAccessResolver implements AccessResolver {
+  public async resolveRoles(user: Auth, tenant?: string): Promise<string[]> {
+    return UserRole.rolesFor(user, tenant);
+  }
+
+  public async resolvePermissions(user: Auth, tenant?: string): Promise<string[]> {
+    const names = await this.resolveRoles(user, tenant);
+
+    if (names.length === 0) return [];
+
+    const roles = await Role.query().whereIn("name", names).get();
+
+    return [...new Set(roles.flatMap((role) => role.permissions))];
+  }
+
+  // Multi-tenant? Uncomment to scope checks to the user's tenant. Derive it from
+  // the user — never trust client-supplied request input for the tenant boundary:
+  // public resolveTenant(user: Auth): string | undefined {
+  //   return user.get("organization_id");
+  // }
+}
+```
+
+## Other recipes
+
+**A single role column, permissions mapped in code**
+
+```ts
+class ColumnResolver implements AccessResolver {
+  public constructor(private readonly roles: Record<string, string[]>) {}
+  public async resolveRoles(user: Auth): Promise<string[]> {
+    return [user.get("role")].filter(Boolean);
+  }
+  public async resolvePermissions(user: Auth): Promise<string[]> {
+    return (await this.resolveRoles(user)).flatMap((role) => this.roles[role] ?? []);
+  }
+}
+```
+
+**Roles from a token claim (external IdP — no DB)**
+
+```ts
+class ClaimResolver implements AccessResolver {
+  public async resolveRoles(user: Auth): Promise<string[]> {
+    return user.get("decodedAccessToken")?.roles ?? [];
+  }
+  public async resolvePermissions(user: Auth): Promise<string[]> {
+    return user.get("decodedAccessToken")?.permissions ?? [];
+  }
+}
+```
+
+**Direct permissions per user (role is just a label)**
+
+```ts
+class DirectResolver implements AccessResolver {
+  public async resolveRoles(user: Auth): Promise<string[]> {
+    return [user.get("role")];
+  }
+  public async resolvePermissions(user: Auth): Promise<string[]> {
+    const rows = await UserPermission.query().where({ user_id: user.id }).get();
+    return rows.map((row) => row.get("name") as string);
+  }
+}
+```
+
+## Rules
+
+- **Only fetch — never cache inside the resolver.** The engine caches per `(user, tenant)`; caching twice causes stale grants. Invalidate with `access.flush(user, tenant)` when your data changes.
+- Return plain `string[]`. Wildcards (`orders.*`, `*`) in the returned permissions are honored by the engine.
+- `resolveRoles` and `resolvePermissions` may read **different** sources — roles and permissions are independent axes (a role can be a pure label with permissions granted directly).
+- Throwing from the resolver fails the check **closed** (denied + logged).
+
+## See also
+
+- [`@warlock.js/access/configure-access/SKILL.md`](@warlock.js/access/configure-access/SKILL.md) — the quickstart `DefaultAccessResolver`.
+```

package/skills/index.md

@@ -0,0 +1,21 @@
+---
+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.user`, so it sits beside `@warlock.js/auth`.
+
+## The 80% path
+1. Orient with `overview.md`.
+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.

package/skills/manage-roles/SKILL.md

@@ -1,71 +1,71 @@
----
-name: manage-roles
-description: "Manage roles in @warlock.js/access; use when you need to manage roles."
----
-
-# Manage roles
-
-Role storage is **ejected into your app** (`npx warlock add access`): a `UserRole` table (who holds which role) and a `Role` catalog table (role → permissions). Both are dynamic — admins manage them at runtime. The package itself only reads them through the `DatabaseAccessResolver`.
-
-## Assign / revoke
-
-Assign and revoke with the ejected `UserRole` model. Both **flush the affected user's cached set for you** — no manual `access.flush` after a role change:
-
-```ts
-import { UserRole } from "app/access/models/user-role";
-
-await UserRole.assign(user, "editor", "tenant-1"); // editor in tenant-1 (auto-flushes that user)
-await UserRole.assign(user, "viewer", "tenant-2"); // viewer in tenant-2 — same user, different role
-
-await UserRole.revoke(user, "editor", "tenant-1"); // auto-flushes too
-```
-
-The `tenant` arg is optional — omit it for single-tenant apps (roles are stored globally). In a **multi-tenant** app, always pass the tenant: an omitted or unresolved tenant scopes to *global* roles only, never the union across tenants.
-
-### When you still need `access.flush`
-
-`assign` / `revoke` cover the common case. The cache keys off `(user, tenant)`, so flush manually only for **out-of-band** changes those two methods can't see:
-
-```ts
-import { access } from "@warlock.js/access";
-
-// A role's permission set changed in the `Role` catalog — every holder's cached
-// permissions are now stale, so flush each affected user:
-await access.flush(user, "tenant-1");
-
-// You changed a user's role membership WITHOUT UserRole (e.g. wrote the user's
-// `role` column directly, or a bulk SQL update):
-await access.flush(user, "tenant-1");
-```
-
-`access.flush(user, tenant)` is per-user — it has no "drop everything" form. For a sweeping catalog change with many holders, flush each affected user, or let the entries expire on their own (`cache.ttl`, default `10m`).
-
-## Read roles
-
-```ts
-import { hasAllRoles, hasAnyRole, hasRole } from "@warlock.js/access";
-
-await hasRole(user, "editor"); //              tenant is an optional 3rd arg
-await hasAnyRole(user, ["admin", "manager"]);
-await hasAllRoles(user, ["staff", "verified"]);
-```
-
-> **Prefer permission checks over role checks.** Role checks couple your code to the role taxonomy; `can(user, "orders.update")` survives a role rename. Reach for `hasRole` only for coarse UI gating.
-
-## The catalog (the `Role` table)
-
-A role's permissions live in the ejected `Role` table — `{ name, permissions }`. Add a role, or change what it grants, by writing rows; the `DatabaseAccessResolver` joins `user_roles` through it. No redeploy needed.
-
-## The model (overridable)
-
-The ejected `UserRole` is a thin cascade model — `{ user_id, user_type, role, tenant }`. `user_id` defaults to `uuid` — edit the ejected migration in `src/app/access/models/user-role/migrations/` if your user ids are integers.
-
-## Roles stored elsewhere?
-
-If roles live on the user (a `roles` column) or in a token claim, you don't use `UserRole` — you manage assignment your way and a resolver reads them. See [`implement-resolver`](@warlock.js/access/implement-resolver/SKILL.md).
-
-## See also
-
-- [`@warlock.js/access/configure-access/SKILL.md`](@warlock.js/access/configure-access/SKILL.md) — choosing the resolver.
-- [`@warlock.js/access/implement-resolver/SKILL.md`](@warlock.js/access/implement-resolver/SKILL.md) — non-table role storage.
-```
+---
+name: manage-roles
+description: '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 — `@warlock.js/access/check-permissions/SKILL.md`; resolver choice — `@warlock.js/access/configure-access/SKILL.md`.'
+---
+
+# Manage roles
+
+Role storage is **ejected into your app** (`npx warlock add access`): a `UserRole` table (who holds which role) and a `Role` catalog table (role → permissions). Both are dynamic — admins manage them at runtime. The package itself only reads them through the `DatabaseAccessResolver`.
+
+## Assign / revoke
+
+Assign and revoke with the ejected `UserRole` model. Both **flush the affected user's cached set for you** — no manual `access.flush` after a role change:
+
+```ts
+import { UserRole } from "app/access/models/user-role";
+
+await UserRole.assign(user, "editor", "tenant-1"); // editor in tenant-1 (auto-flushes that user)
+await UserRole.assign(user, "viewer", "tenant-2"); // viewer in tenant-2 — same user, different role
+
+await UserRole.revoke(user, "editor", "tenant-1"); // auto-flushes too
+```
+
+The `tenant` arg is optional — omit it for single-tenant apps (roles are stored globally). In a **multi-tenant** app, always pass the tenant: an omitted or unresolved tenant scopes to *global* roles only, never the union across tenants.
+
+### When you still need `access.flush`
+
+`assign` / `revoke` cover the common case. The cache keys off `(user, tenant)`, so flush manually only for **out-of-band** changes those two methods can't see:
+
+```ts
+import { access } from "@warlock.js/access";
+
+// A role's permission set changed in the `Role` catalog — every holder's cached
+// permissions are now stale, so flush each affected user:
+await access.flush(user, "tenant-1");
+
+// You changed a user's role membership WITHOUT UserRole (e.g. wrote the user's
+// `role` column directly, or a bulk SQL update):
+await access.flush(user, "tenant-1");
+```
+
+`access.flush(user, tenant)` is per-user — it has no "drop everything" form. For a sweeping catalog change with many holders, flush each affected user, or let the entries expire on their own (`cache.ttl`, default `10m`).
+
+## Read roles
+
+```ts
+import { hasAllRoles, hasAnyRole, hasRole } from "@warlock.js/access";
+
+await hasRole(user, "editor"); //              tenant is an optional 3rd arg
+await hasAnyRole(user, ["admin", "manager"]);
+await hasAllRoles(user, ["staff", "verified"]);
+```
+
+> **Prefer permission checks over role checks.** Role checks couple your code to the role taxonomy; `can(user, "orders.update")` survives a role rename. Reach for `hasRole` only for coarse UI gating.
+
+## The catalog (the `Role` table)
+
+A role's permissions live in the ejected `Role` table — `{ name, permissions }`. Add a role, or change what it grants, by writing rows; the `DatabaseAccessResolver` joins `user_roles` through it. No redeploy needed.
+
+## The model (overridable)
+
+The ejected `UserRole` is a thin cascade model — `{ user_id, user_type, role, tenant }`. `user_id` defaults to `uuid` — edit the ejected migration in `src/app/access/models/user-role/migrations/` if your user ids are integers.
+
+## Roles stored elsewhere?
+
+If roles live on the user (a `roles` column) or in a token claim, you don't use `UserRole` — you manage assignment your way and a resolver reads them. See [`implement-resolver`](@warlock.js/access/implement-resolver/SKILL.md).
+
+## See also
+
+- [`@warlock.js/access/configure-access/SKILL.md`](@warlock.js/access/configure-access/SKILL.md) — choosing the resolver.
+- [`@warlock.js/access/implement-resolver/SKILL.md`](@warlock.js/access/implement-resolver/SKILL.md) — non-table role storage.
+```