@warlock.js/access 5.53.1 → 5.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,20 @@ All notable changes to `@warlock.js/access` are documented in this file.
4
4
 
5
5
  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.
6
6
 
7
+ ## 5.54.0 - 2026-11-16
8
+
9
+ ### Upgrading
10
+
11
+ - `DefaultAccessResolver` no longer has its roles and permissions stored in the shared cache: they are read from the loaded user on every check, so a role change shows on the next request instead of after `access.cacheTtl`. A custom `readRoles` that is expensive should memoize itself. Other resolvers keep their cached behaviour.
12
+
13
+ ### Added
14
+
15
+ - `AccessResolver.cacheable` (optional, default `true`): a resolver that sets `readonly cacheable = false` is never cached by the engine. Checks on one user object within a request still share a single resolution.
16
+
17
+ ### Documentation
18
+
19
+ - The resolver page and the `implement-resolver` skill describe `cacheable`.
20
+
7
21
  ## 5.53.0 - 2026-11-11
8
22
 
9
23
  ### Upgrading
package/cjs/index.cjs CHANGED
@@ -198,6 +198,7 @@ function cacheKey(prefix, user, tenant) {
198
198
  * so the DECISION fails closed in {@link check}.
199
199
  */
200
200
  async function cached(key, loader) {
201
+ if (accessConfig.resolver().cacheable === false) return loader();
201
202
  try {
202
203
  const hit = await _warlock_js_cache.cache.get(key);
203
204
  if (hit) return hit;
@@ -467,6 +468,11 @@ function toRoleList(value) {
467
468
  var DefaultAccessResolver = class {
468
469
  roles;
469
470
  readRoles;
471
+ /**
472
+ * The sets are a pure function of the loaded user, so caching them would
473
+ * only delay a role change; the engine reads them straight from the user.
474
+ */
475
+ cacheable = false;
470
476
  constructor(roles, readRoles = (user) => user.get("roles") ?? user.get("role")) {
471
477
  this.roles = roles;
472
478
  this.readRoles = readRoles;
package/cjs/index.cjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.cjs","names":["cache","ForbiddenError","t","flushUser","t"],"sources":["../../../../../../../packages/access/src/utils/access-error-codes.ts","../../../../../../../packages/access/src/utils/access-config-error.ts","../../../../../../../packages/access/src/services/resolution-memo.ts","../../../../../../../packages/access/src/services/access-config.ts","../../../../../../../packages/access/src/services/matcher.ts","../../../../../../../packages/access/src/services/policies.ts","../../../../../../../packages/access/src/services/engine.ts","../../../../../../../packages/access/src/services/access.ts","../../../../../../../packages/access/src/middleware/gate.middleware.ts","../../../../../../../packages/access/src/services/default-resolver.ts"],"sourcesContent":["/**\n * Wire-stable error codes emitted by `@warlock.js/access`. Map these in your\n * error transformer the way you map `AuthErrorCodes`. A value change here is a\n * breaking change for any client that reacts to the code.\n */\nexport enum AccessErrorCodes {\n /** EC100 — authenticated, but missing the required permission. */\n Forbidden = \"EC100\",\n}\n","/**\n * Thrown when `@warlock.js/access` is misconfigured (e.g. no resolver). Unlike a\n * runtime resolution failure — which fails CLOSED (denies) — a config error is a\n * developer mistake, so the engine re-throws it LOUD instead of silently denying.\n */\nexport class AccessConfigError extends Error {\n public constructor(message: string) {\n super(message);\n this.name = \"AccessConfigError\";\n }\n}\n","import type { Auth } from \"@warlock.js/auth\";\n\n/**\n * How long a resolved set is reused for the same user object. Long enough to\n * cover one request's stacked gates and `can()` calls, short enough that a\n * long-lived user object (a worker, a test fixture) never holds a set much\n * longer than the shared cache would.\n */\nconst MEMO_MAX_AGE_MS = 1000;\n\ntype MemoEntry = { value: Promise<string[]>; at: number; generation: number };\n\n/** Resolved sets per user object; an entry dies with the object it belongs to. */\nconst memos = new WeakMap<object, Map<string, MemoEntry>>();\n\n/**\n * Bumped by {@link invalidateResolutionMemo}: every entry from an older\n * generation is ignored, so `flush()` and a new configuration take effect at\n * once for every user object in this process.\n */\nlet generation = 0;\n\n/** Drop every memoised set in this process. */\nexport function invalidateResolutionMemo(): void {\n generation++;\n}\n\n/**\n * Resolve `key` for `user` once and share the promise with every check on the\n * same user object for {@link MEMO_MAX_AGE_MS}. A rejected load is never\n * reused, so a failed resolution is retried on the next check.\n */\nexport function memoizeForUser(\n user: Auth,\n key: string,\n load: () => Promise<string[]>,\n): Promise<string[]> {\n if (typeof user !== \"object\" || user === null) return load();\n\n let entries = memos.get(user);\n\n if (!entries) {\n entries = new Map();\n memos.set(user, entries);\n }\n\n const now = Date.now();\n const hit = entries.get(key);\n\n if (hit && hit.generation === generation && now - hit.at < MEMO_MAX_AGE_MS) {\n return hit.value;\n }\n\n const value = load();\n const owner = entries;\n\n owner.set(key, { value, at: now, generation });\n\n value.catch(() => {\n if (owner.get(key)?.value === value) owner.delete(key);\n });\n\n return value;\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { AccessConfigurations } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { invalidateResolutionMemo } from \"./resolution-memo\";\n\n/**\n * The active configuration, fed once at boot by the framework's access connector\n * via {@link setAccessConfig} (the connector reads `src/config/access.ts`).\n * Reading it before it's set throws {@link AccessConfigError} — a loud\n * misconfiguration, never a silent deny.\n */\nlet current: AccessConfigurations | undefined;\n\n/**\n * Register the access configuration. The framework's access connector calls this\n * at boot with the default export of `src/config/access.ts`. It validates that a\n * `resolver` is present, so a misconfigured authorization layer fails at STARTUP\n * rather than on the first protected request.\n *\n * @example\n * setAccessConfig({ resolver: new DefaultAccessResolver({ admin: [\"*\"] }) });\n */\nexport function setAccessConfig(configuration: AccessConfigurations): void {\n if (!configuration?.resolver) {\n throw new AccessConfigError(\n \"No access resolver configured. Set `resolver` in src/config/access.ts to a class \" +\n \"implementing AccessResolver — the ejected DatabaseAccessResolver, or \" +\n \"`new DefaultAccessResolver(rolesMap)` for a fixed-role catalog.\",\n );\n }\n\n current = configuration;\n invalidateResolutionMemo();\n}\n\n/** Clear the active config. Used by the connector on dev-restart and by tests. */\nexport function resetAccessConfig(): void {\n current = undefined;\n invalidateResolutionMemo();\n}\n\n/** Accessors over the active access configuration. */\nexport const accessConfig = {\n /**\n * The configured resolver. Throws {@link AccessConfigError} if access was never\n * configured (no `src/config/access.ts`, or the connector hasn't run).\n */\n resolver(): AccessResolver {\n if (!current) {\n throw new AccessConfigError(\n \"@warlock.js/access is not configured. Add src/config/access.ts (exporting a `resolver`) \" +\n \"— it is wired at boot by the access connector.\",\n );\n }\n\n return current.resolver;\n },\n\n /** Cache TTL for resolved permission sets. */\n cacheTtl(): string | number {\n return current?.cache?.ttl ?? \"10m\";\n },\n\n /** Whether an unpoliced instance-level check should deny instead of falling back to the RBAC grant. */\n strictPolicies(): boolean {\n return current?.strictPolicies ?? true;\n },\n\n /** Ambient tenant for this user, delegated to the resolver's optional hook. */\n tenant(user: Auth): string | undefined {\n return this.resolver().resolveTenant?.(user);\n },\n};\n","/**\n * Whether a set of granted permission patterns covers a requested permission.\n *\n * Supports three forms:\n * - exact — `\"orders.update\"` covers `\"orders.update\"`\n * - global — `\"*\"` covers everything (the super-grant)\n * - prefix wildcard — `\"orders.*\"` covers `\"orders.update\"` and `\"orders.update.status\"`\n *\n * `\"orders.*\"` does NOT cover the bare `\"orders\"` (no trailing segment).\n */\nexport function matchesPermission(granted: string[], permission: string): boolean {\n for (const pattern of granted) {\n if (pattern === \"*\" || pattern === permission) {\n return true;\n }\n\n // \"orders.*\" → prefix \"orders.\" — matches any nested permission.\n if (pattern.endsWith(\".*\") && permission.startsWith(pattern.slice(0, -1))) {\n return true;\n }\n }\n\n return false;\n}\n","import type { PolicyFn } from \"../contracts/types\";\n\nconst policies = new Map<string, PolicyFn>();\n\n/**\n * Register an ABAC condition for a permission. It runs ON TOP of the RBAC grant\n * whenever an authorization check carries a `resource` — letting you express\n * \"...but only their own / only in their tenant / only while pending\".\n *\n * @example\n * definePolicy(\"orders.update\", (user, order) => order.get(\"customer_id\") === user.id);\n */\nexport function definePolicy(permission: string, policy: PolicyFn): void {\n policies.set(permission, policy);\n}\n\n/** The policy registered for a permission, if any. */\nexport function getPolicy(permission: string): PolicyFn | undefined {\n return policies.get(permission);\n}\n\n/** Remove every registered policy. Primarily for tests. */\nexport function clearPolicies(): void {\n policies.clear();\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { accessConfig } from \"./access-config\";\nimport { matchesPermission } from \"./matcher\";\nimport { getPolicy } from \"./policies\";\nimport { invalidateResolutionMemo, memoizeForUser } from \"./resolution-memo\";\n\nconst PERMISSIONS_PREFIX = \"access.perms.\";\nconst ROLES_PREFIX = \"access.roles.\";\n\n/**\n * Permissions that have already triggered the \"unpoliced instance check\"\n * warning below — kept so a hot path doesn't log once per request.\n */\nconst warnedUnpolicedPermissions = new Set<string>();\n\n/** Reset the once-per-permission warning tracker. Primarily for tests. */\nexport function resetUnpolicedWarnings(): void {\n warnedUnpolicedPermissions.clear();\n}\n\n/** Resolve the effective tenant for a check (explicit → ambient → undefined). */\nfunction tenantFor(user: Auth, context: AccessContext): string | undefined {\n return context.tenant ?? accessConfig.tenant(user);\n}\n\nfunction cacheKey(prefix: string, user: Auth, tenant?: string): string {\n // Encode each segment so a `.` in an id or tenant can't collide two distinct\n // principals onto the same cache key (and serve one's grants to the other).\n const segment = (value: unknown) => encodeURIComponent(String(value));\n\n return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? \"_\")}`;\n}\n\n/**\n * Read a list through the cache, falling back to the loader.\n *\n * The cache is **best-effort**: a cache failure degrades to the loader (the\n * source of truth) and is logged, never denied. A loader failure propagates —\n * so the DECISION fails closed in {@link check}.\n */\nasync function cached(key: string, loader: () => Promise<string[]>): Promise<string[]> {\n try {\n const hit = await cache.get<string[]>(key);\n\n if (hit) return hit;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n await cache.set(key, value, { ttl: accessConfig.cacheTtl() });\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n return value;\n}\n\n/**\n * The user's effective permission set for a tenant (cached). Checks on the\n * same user object share one resolution for a short while, so stacked gates\n * and `canAll` / `canAny` read the shared cache once per request.\n */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)),\n );\n}\n\n/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(ROLES_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)),\n );\n}\n\n/**\n * The tenants whose cached sets `flush(user, tenant)` must drop: the one\n * passed, else the ambient tenant the checks themselves use (the resolver's\n * `resolveTenant`) together with the no-tenant entry.\n */\nfunction tenantsToFlush(user: Auth, tenant?: string): Array<string | undefined> {\n if (tenant !== undefined) return [tenant];\n\n let ambient: string | undefined;\n\n try {\n ambient = accessConfig.tenant(user);\n } catch {\n ambient = undefined;\n }\n\n return ambient === undefined ? [undefined] : [ambient, undefined];\n}\n\n/**\n * Drop the cached role/permission sets for a user (after any out-of-band role\n * change). Without a `tenant` it drops the set for the user's ambient tenant\n * (what `can(user, …)` reads) and the no-tenant set.\n */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n try {\n for (const target of tenantsToFlush(user, tenant)) {\n await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));\n await cache.remove(cacheKey(ROLES_PREFIX, user, target));\n }\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n } finally {\n // After the shared entries are gone, so a check cannot re-memoise them.\n invalidateResolutionMemo();\n }\n}\n\n/**\n * Surface a resource-scoped check that has no registered ABAC policy, and\n * report whether the check should now DENY.\n *\n * `strictPolicies` defaults to `true`: a forgotten `definePolicy` call (typo'd\n * permission name, or a missing `import \"./policies\"` side-effect — the\n * single most common mistake app teams make with this package, per the\n * `define-policies` skill) must never fail OPEN, so the check denies.\n *\n * `strictPolicies: false` explicitly restores the pre-5.13 behavior: fall\n * back to the RBAC grant alone (ALLOW), which is a plausible IDOR if the\n * permission was meant to be resource-scoped.\n *\n * Either way this warns once per permission (not once per call) so a hot\n * request path doesn't spam logs — mirrors cascade's\n * `warnUndeclaredSensitiveFields`.\n */\nfunction unpolicedShouldDeny(permission: string): boolean {\n const strict = accessConfig.strictPolicies();\n\n if (!warnedUnpolicedPermissions.has(permission)) {\n warnedUnpolicedPermissions.add(permission);\n\n log.warn(\n \"access\",\n \"unpoliced-check\",\n strict\n ? `Instance-level check for permission \"${permission}\" has no registered ABAC policy — ` +\n `DENYING (strictPolicies defaults to true as of 5.13). Register one with ` +\n `definePolicy(\"${permission}\", ...), or make sure the module that calls definePolicy is ` +\n `actually imported. Set strictPolicies: false in the access config to restore the pre-5.13 ` +\n `RBAC-only fallback (ALLOWS — not recommended).`\n : `Instance-level check for permission \"${permission}\" has no registered ABAC policy — falling ` +\n `back to the RBAC grant alone (strictPolicies: false), so any holder of \"${permission}\" can ` +\n `act on ANY resource. If this permission is meant to be resource-scoped, register a policy ` +\n `with definePolicy(\"${permission}\", ...) (and confirm the module that calls it is ` +\n `imported), or remove strictPolicies: false to deny by default.`,\n );\n }\n\n return strict;\n}\n\n/**\n * The core decision: does the user hold `permission`, and — when a `resource`\n * is supplied — does its policy pass too?\n *\n * Fails CLOSED: any error while resolving the decision denies (and logs). An\n * instance-level check for a permission with no registered policy also fails\n * CLOSED by default ({@link AccessConfigurations.strictPolicies}) rather than\n * falling back to the RBAC grant alone.\n */\nexport async function check(\n user: Auth,\n permission: string,\n context: AccessContext = {},\n): Promise<boolean> {\n try {\n const tenant = tenantFor(user, context);\n const permissions = await permissionsFor(user, tenant);\n\n if (!matchesPermission(permissions, permission)) return false;\n\n const policy = getPolicy(permission);\n\n // A policy only runs on an instance check (a resource was supplied);\n // class-level checks (`gate`) stop at the grant.\n if (context.resource !== undefined && policy === undefined) {\n if (unpolicedShouldDeny(permission)) return false;\n }\n\n if (policy === undefined || context.resource === undefined) return true;\n\n const roles = await rolesFor(user, tenant);\n\n return Boolean(\n await policy(user, context.resource, {\n ...context,\n tenant,\n hasRole: (role) => roles.includes(role),\n hasPermission: (perm) => matchesPermission(permissions, perm),\n }),\n );\n } catch (error) {\n if (error instanceof AccessConfigError) throw error; // misconfig is loud, not a silent deny\n\n log.error(\"access\", \"check\", error);\n\n return false;\n }\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport { ForbiddenError, t } from \"@warlock.js/core\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessErrorCodes } from \"../utils/access-error-codes\";\nimport { check, flush as flushUser, rolesFor } from \"./engine\";\n\n/** Whether the user holds `permission` (and passes its policy when a resource is given). */\nexport function can(user: Auth, permission: string, context?: AccessContext): Promise<boolean> {\n return check(user, permission, context);\n}\n\n/** Inverse of {@link can}. */\nexport async function cannot(\n user: Auth,\n permission: string,\n context?: AccessContext,\n): Promise<boolean> {\n return !(await can(user, permission, context));\n}\n\n/** Whether the user holds EVERY listed permission. Short-circuits on the first miss. */\nexport async function canAll(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<boolean> {\n for (const permission of permissions) {\n if (!(await can(user, permission, context))) return false;\n }\n\n return true;\n}\n\n/** Whether the user holds ANY listed permission. Short-circuits on the first hit. */\nexport async function canAny(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<boolean> {\n for (const permission of permissions) {\n if (await can(user, permission, context)) return true;\n }\n\n return false;\n}\n\nfunction forbidden(): never {\n throw new ForbiddenError(t(\"access.errors.forbidden\"), {\n errorCode: AccessErrorCodes.Forbidden,\n });\n}\n\n/** Assert the user holds `permission`; throw `ForbiddenError` (403) otherwise. */\nexport async function authorize(\n user: Auth,\n permission: string,\n context?: AccessContext,\n): Promise<void> {\n if (!(await can(user, permission, context))) forbidden();\n}\n\n/** Assert the user holds EVERY listed permission; throw otherwise. */\nexport async function authorizeAll(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<void> {\n if (!(await canAll(user, permissions, context))) forbidden();\n}\n\n/** Assert the user holds ANY listed permission; throw otherwise. */\nexport async function authorizeAny(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<void> {\n if (!(await canAny(user, permissions, context))) forbidden();\n}\n\n/** Whether the user has the given role. */\nexport async function hasRole(user: Auth, role: string, tenant?: string): Promise<boolean> {\n return (await rolesFor(user, tenant)).includes(role);\n}\n\n/** Whether the user has ANY of the given roles. */\nexport async function hasAnyRole(user: Auth, roles: string[], tenant?: string): Promise<boolean> {\n const held = await rolesFor(user, tenant);\n\n return roles.some((role) => held.includes(role));\n}\n\n/** Whether the user has ALL of the given roles. */\nexport async function hasAllRoles(user: Auth, roles: string[], tenant?: string): Promise<boolean> {\n const held = await rolesFor(user, tenant);\n\n return roles.every((role) => held.includes(role));\n}\n\n/**\n * The access facade — every check plus `flush` to drop a user's cached set.\n * Role assignment lives on the ejected `UserRole` model in app-land; callers do\n * `UserRole.assign(...)` then `access.flush(user, tenant)`.\n *\n * @example\n * import { access } from \"@warlock.js/access\";\n * if (await access.can(user, \"orders.update\", { resource: order })) { ... }\n * await access.flush(user, \"tenant-1\");\n */\nexport const access = {\n can,\n cannot,\n canAll,\n canAny,\n authorize,\n authorizeAll,\n authorizeAny,\n hasRole,\n hasAnyRole,\n hasAllRoles,\n /** Drop the user's cached role/permission set (call after you mutate role rows). */\n flush: flushUser,\n};\n","import type { Auth } from \"@warlock.js/auth\";\nimport { t, type HttpContext, type Middleware, type Response } from \"@warlock.js/core\";\nimport type { ModelSchema } from \"@warlock.js/cascade\";\nimport { can, canAll, canAny } from \"../services/access\";\nimport { AccessErrorCodes } from \"../utils/access-error-codes\";\n\n/*\n * @warlock.js/access does NOT augment `RequestUser`, deliberately. An\n * interface can extend at most one class hierarchy, so a library-side\n * `interface RequestUser extends Auth<ModelSchema>` PRE-CLAIMS the one\n * extends slot every app needs for its own model — the app's\n * `interface RequestUser extends User {}` then fails with TS2320, and the\n * app can never see its own auth model on `request.locals.user`. (Core\n * documents the same hazard for member-level augmentation in\n * `http/middleware/utils/idempotency-key.ts`.)\n *\n * The contract instead: an app using gates augments `RequestUser` (declared\n * by `@warlock.js/auth`, which also augments core's `RequestLocals` with the\n * `user` key) to its OWN `Auth`-derived model; `authUserOf` below is the\n * single boundary where access asserts that contract to satisfy `can()`'s\n * parameter type.\n */\n\n/**\n * The one place access bridges `request.locals.user` (app-augmented via\n * `@warlock.js/auth`'s `RequestUser`, empty by default) to the\n * `Auth<ModelSchema>` that `can()`/`canAny()`/`canAll()` require. The\n * assertion is the contract boundary, not a shortcut: the app's `RequestUser`\n * augmentation promises an `Auth`-derived model, and the auth middleware\n * placed exactly that instance at `request.locals.user` at runtime. Kept to\n * this single accessor so the promise is asserted once, visibly, instead of\n * scattered.\n */\nfunction authUserOf(request: HttpContext[\"request\"]): Auth<ModelSchema> | undefined {\n return request.locals.user as unknown as Auth<ModelSchema> | undefined;\n}\n\nfunction deny(response: Response) {\n return response.forbidden({\n error: t(\"access.errors.forbidden\"),\n errorCode: AccessErrorCodes.Forbidden,\n });\n}\n\n/**\n * Gate a route on a single permission (class-level). Stack it AFTER\n * `authMiddleware`, which sets `request.locals.user`.\n *\n * @example\n * router.post(\"/orders\", createOrder, {\n * middleware: [authMiddleware([]), gate(\"orders.create\")],\n * });\n */\nexport function gate(permission: string): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await can(user, permission))) return deny(response);\n };\n}\n\n/** Gate a route on holding ANY of the listed permissions. */\nexport function gateAny(permissions: string[]): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await canAny(user, permissions))) return deny(response);\n };\n}\n\n/** Gate a route on holding ALL of the listed permissions. */\nexport function gateAll(permissions: string[]): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await canAll(user, permissions))) return deny(response);\n };\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { RolesMap } from \"../contracts/types\";\n\n/** Coerce a roles value (`undefined` / single string / array) into a string array. */\nfunction toRoleList(value: unknown): string[] {\n if (Array.isArray(value)) return value as string[];\n\n if (typeof value === \"string\" && value.length > 0) return [value];\n\n return [];\n}\n\n/**\n * The zero-config resolver: reads a user's roles from a model field and maps\n * them to permissions through your `roles` catalog. Works out of the box for\n * both a `roles` array column and a single `role` column.\n *\n * Swap `readRoles` to read from anywhere else (a relation, a token claim); for\n * a different storage shape entirely, implement {@link AccessResolver} directly.\n *\n * @example\n * new DefaultAccessResolver({ editor: [\"orders.*\"], viewer: [\"orders.view\"] });\n * new DefaultAccessResolver(rolesMap, (user) => user.get(\"memberRoles\"));\n */\nexport class DefaultAccessResolver implements AccessResolver {\n public constructor(\n private readonly roles: RolesMap,\n private readonly readRoles: (user: Auth) => unknown = (user) =>\n user.get(\"roles\") ?? user.get(\"role\"),\n ) {}\n\n public async resolveRoles(user: Auth): Promise<string[]> {\n return toRoleList(await this.readRoles(user));\n }\n\n public async resolvePermissions(user: Auth): Promise<string[]> {\n const roles = await this.resolveRoles(user);\n\n // Guard against a role named `__proto__` / `constructor` resolving to an\n // inherited (non-array) value.\n return roles.flatMap((role) => {\n if (!Object.prototype.hasOwnProperty.call(this.roles, role)) {\n return [];\n }\n\n // `hasOwnProperty` proves the KEY is present; it says nothing about the\n // value, which under `noUncheckedIndexedAccess` is `string[] |\n // undefined`. Falling back to NO permissions is the only safe direction\n // here: this function's result is what the caller checks before granting\n // access, so an unreadable role must grant nothing rather than be\n // asserted into something.\n return this.roles[role] ?? [];\n });\n }\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"index.cjs","names":["cache","ForbiddenError","t","flushUser","t"],"sources":["../../../../../../../packages/access/src/utils/access-error-codes.ts","../../../../../../../packages/access/src/utils/access-config-error.ts","../../../../../../../packages/access/src/services/resolution-memo.ts","../../../../../../../packages/access/src/services/access-config.ts","../../../../../../../packages/access/src/services/matcher.ts","../../../../../../../packages/access/src/services/policies.ts","../../../../../../../packages/access/src/services/engine.ts","../../../../../../../packages/access/src/services/access.ts","../../../../../../../packages/access/src/middleware/gate.middleware.ts","../../../../../../../packages/access/src/services/default-resolver.ts"],"sourcesContent":["/**\n * Wire-stable error codes emitted by `@warlock.js/access`. Map these in your\n * error transformer the way you map `AuthErrorCodes`. A value change here is a\n * breaking change for any client that reacts to the code.\n */\nexport enum AccessErrorCodes {\n /** EC100 — authenticated, but missing the required permission. */\n Forbidden = \"EC100\",\n}\n","/**\n * Thrown when `@warlock.js/access` is misconfigured (e.g. no resolver). Unlike a\n * runtime resolution failure — which fails CLOSED (denies) — a config error is a\n * developer mistake, so the engine re-throws it LOUD instead of silently denying.\n */\nexport class AccessConfigError extends Error {\n public constructor(message: string) {\n super(message);\n this.name = \"AccessConfigError\";\n }\n}\n","import type { Auth } from \"@warlock.js/auth\";\n\n/**\n * How long a resolved set is reused for the same user object. Long enough to\n * cover one request's stacked gates and `can()` calls, short enough that a\n * long-lived user object (a worker, a test fixture) never holds a set much\n * longer than the shared cache would.\n */\nconst MEMO_MAX_AGE_MS = 1000;\n\ntype MemoEntry = { value: Promise<string[]>; at: number; generation: number };\n\n/** Resolved sets per user object; an entry dies with the object it belongs to. */\nconst memos = new WeakMap<object, Map<string, MemoEntry>>();\n\n/**\n * Bumped by {@link invalidateResolutionMemo}: every entry from an older\n * generation is ignored, so `flush()` and a new configuration take effect at\n * once for every user object in this process.\n */\nlet generation = 0;\n\n/** Drop every memoised set in this process. */\nexport function invalidateResolutionMemo(): void {\n generation++;\n}\n\n/**\n * Resolve `key` for `user` once and share the promise with every check on the\n * same user object for {@link MEMO_MAX_AGE_MS}. A rejected load is never\n * reused, so a failed resolution is retried on the next check.\n */\nexport function memoizeForUser(\n user: Auth,\n key: string,\n load: () => Promise<string[]>,\n): Promise<string[]> {\n if (typeof user !== \"object\" || user === null) return load();\n\n let entries = memos.get(user);\n\n if (!entries) {\n entries = new Map();\n memos.set(user, entries);\n }\n\n const now = Date.now();\n const hit = entries.get(key);\n\n if (hit && hit.generation === generation && now - hit.at < MEMO_MAX_AGE_MS) {\n return hit.value;\n }\n\n const value = load();\n const owner = entries;\n\n owner.set(key, { value, at: now, generation });\n\n value.catch(() => {\n if (owner.get(key)?.value === value) owner.delete(key);\n });\n\n return value;\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { AccessConfigurations } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { invalidateResolutionMemo } from \"./resolution-memo\";\n\n/**\n * The active configuration, fed once at boot by the framework's access connector\n * via {@link setAccessConfig} (the connector reads `src/config/access.ts`).\n * Reading it before it's set throws {@link AccessConfigError} — a loud\n * misconfiguration, never a silent deny.\n */\nlet current: AccessConfigurations | undefined;\n\n/**\n * Register the access configuration. The framework's access connector calls this\n * at boot with the default export of `src/config/access.ts`. It validates that a\n * `resolver` is present, so a misconfigured authorization layer fails at STARTUP\n * rather than on the first protected request.\n *\n * @example\n * setAccessConfig({ resolver: new DefaultAccessResolver({ admin: [\"*\"] }) });\n */\nexport function setAccessConfig(configuration: AccessConfigurations): void {\n if (!configuration?.resolver) {\n throw new AccessConfigError(\n \"No access resolver configured. Set `resolver` in src/config/access.ts to a class \" +\n \"implementing AccessResolver — the ejected DatabaseAccessResolver, or \" +\n \"`new DefaultAccessResolver(rolesMap)` for a fixed-role catalog.\",\n );\n }\n\n current = configuration;\n invalidateResolutionMemo();\n}\n\n/** Clear the active config. Used by the connector on dev-restart and by tests. */\nexport function resetAccessConfig(): void {\n current = undefined;\n invalidateResolutionMemo();\n}\n\n/** Accessors over the active access configuration. */\nexport const accessConfig = {\n /**\n * The configured resolver. Throws {@link AccessConfigError} if access was never\n * configured (no `src/config/access.ts`, or the connector hasn't run).\n */\n resolver(): AccessResolver {\n if (!current) {\n throw new AccessConfigError(\n \"@warlock.js/access is not configured. Add src/config/access.ts (exporting a `resolver`) \" +\n \"— it is wired at boot by the access connector.\",\n );\n }\n\n return current.resolver;\n },\n\n /** Cache TTL for resolved permission sets. */\n cacheTtl(): string | number {\n return current?.cache?.ttl ?? \"10m\";\n },\n\n /** Whether an unpoliced instance-level check should deny instead of falling back to the RBAC grant. */\n strictPolicies(): boolean {\n return current?.strictPolicies ?? true;\n },\n\n /** Ambient tenant for this user, delegated to the resolver's optional hook. */\n tenant(user: Auth): string | undefined {\n return this.resolver().resolveTenant?.(user);\n },\n};\n","/**\n * Whether a set of granted permission patterns covers a requested permission.\n *\n * Supports three forms:\n * - exact — `\"orders.update\"` covers `\"orders.update\"`\n * - global — `\"*\"` covers everything (the super-grant)\n * - prefix wildcard — `\"orders.*\"` covers `\"orders.update\"` and `\"orders.update.status\"`\n *\n * `\"orders.*\"` does NOT cover the bare `\"orders\"` (no trailing segment).\n */\nexport function matchesPermission(granted: string[], permission: string): boolean {\n for (const pattern of granted) {\n if (pattern === \"*\" || pattern === permission) {\n return true;\n }\n\n // \"orders.*\" → prefix \"orders.\" — matches any nested permission.\n if (pattern.endsWith(\".*\") && permission.startsWith(pattern.slice(0, -1))) {\n return true;\n }\n }\n\n return false;\n}\n","import type { PolicyFn } from \"../contracts/types\";\n\nconst policies = new Map<string, PolicyFn>();\n\n/**\n * Register an ABAC condition for a permission. It runs ON TOP of the RBAC grant\n * whenever an authorization check carries a `resource` — letting you express\n * \"...but only their own / only in their tenant / only while pending\".\n *\n * @example\n * definePolicy(\"orders.update\", (user, order) => order.get(\"customer_id\") === user.id);\n */\nexport function definePolicy(permission: string, policy: PolicyFn): void {\n policies.set(permission, policy);\n}\n\n/** The policy registered for a permission, if any. */\nexport function getPolicy(permission: string): PolicyFn | undefined {\n return policies.get(permission);\n}\n\n/** Remove every registered policy. Primarily for tests. */\nexport function clearPolicies(): void {\n policies.clear();\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { accessConfig } from \"./access-config\";\nimport { matchesPermission } from \"./matcher\";\nimport { getPolicy } from \"./policies\";\nimport { invalidateResolutionMemo, memoizeForUser } from \"./resolution-memo\";\n\nconst PERMISSIONS_PREFIX = \"access.perms.\";\nconst ROLES_PREFIX = \"access.roles.\";\n\n/**\n * Permissions that have already triggered the \"unpoliced instance check\"\n * warning below — kept so a hot path doesn't log once per request.\n */\nconst warnedUnpolicedPermissions = new Set<string>();\n\n/** Reset the once-per-permission warning tracker. Primarily for tests. */\nexport function resetUnpolicedWarnings(): void {\n warnedUnpolicedPermissions.clear();\n}\n\n/** Resolve the effective tenant for a check (explicit → ambient → undefined). */\nfunction tenantFor(user: Auth, context: AccessContext): string | undefined {\n return context.tenant ?? accessConfig.tenant(user);\n}\n\nfunction cacheKey(prefix: string, user: Auth, tenant?: string): string {\n // Encode each segment so a `.` in an id or tenant can't collide two distinct\n // principals onto the same cache key (and serve one's grants to the other).\n const segment = (value: unknown) => encodeURIComponent(String(value));\n\n return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? \"_\")}`;\n}\n\n/**\n * Read a list through the cache, falling back to the loader.\n *\n * The cache is **best-effort**: a cache failure degrades to the loader (the\n * source of truth) and is logged, never denied. A loader failure propagates —\n * so the DECISION fails closed in {@link check}.\n */\nasync function cached(key: string, loader: () => Promise<string[]>): Promise<string[]> {\n // A resolver that opts out is the source of truth on every check.\n if (accessConfig.resolver().cacheable === false) return loader();\n\n try {\n const hit = await cache.get<string[]>(key);\n\n if (hit) return hit;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n await cache.set(key, value, { ttl: accessConfig.cacheTtl() });\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n return value;\n}\n\n/**\n * The user's effective permission set for a tenant (cached). Checks on the\n * same user object share one resolution for a short while, so stacked gates\n * and `canAll` / `canAny` read the shared cache once per request.\n */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)),\n );\n}\n\n/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(ROLES_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)),\n );\n}\n\n/**\n * The tenants whose cached sets `flush(user, tenant)` must drop: the one\n * passed, else the ambient tenant the checks themselves use (the resolver's\n * `resolveTenant`) together with the no-tenant entry.\n */\nfunction tenantsToFlush(user: Auth, tenant?: string): Array<string | undefined> {\n if (tenant !== undefined) return [tenant];\n\n let ambient: string | undefined;\n\n try {\n ambient = accessConfig.tenant(user);\n } catch {\n ambient = undefined;\n }\n\n return ambient === undefined ? [undefined] : [ambient, undefined];\n}\n\n/**\n * Drop the cached role/permission sets for a user (after any out-of-band role\n * change). Without a `tenant` it drops the set for the user's ambient tenant\n * (what `can(user, …)` reads) and the no-tenant set.\n */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n try {\n for (const target of tenantsToFlush(user, tenant)) {\n await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));\n await cache.remove(cacheKey(ROLES_PREFIX, user, target));\n }\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n } finally {\n // After the shared entries are gone, so a check cannot re-memoise them.\n invalidateResolutionMemo();\n }\n}\n\n/**\n * Surface a resource-scoped check that has no registered ABAC policy, and\n * report whether the check should now DENY.\n *\n * `strictPolicies` defaults to `true`: a forgotten `definePolicy` call (typo'd\n * permission name, or a missing `import \"./policies\"` side-effect — the\n * single most common mistake app teams make with this package, per the\n * `define-policies` skill) must never fail OPEN, so the check denies.\n *\n * `strictPolicies: false` explicitly restores the pre-5.13 behavior: fall\n * back to the RBAC grant alone (ALLOW), which is a plausible IDOR if the\n * permission was meant to be resource-scoped.\n *\n * Either way this warns once per permission (not once per call) so a hot\n * request path doesn't spam logs — mirrors cascade's\n * `warnUndeclaredSensitiveFields`.\n */\nfunction unpolicedShouldDeny(permission: string): boolean {\n const strict = accessConfig.strictPolicies();\n\n if (!warnedUnpolicedPermissions.has(permission)) {\n warnedUnpolicedPermissions.add(permission);\n\n log.warn(\n \"access\",\n \"unpoliced-check\",\n strict\n ? `Instance-level check for permission \"${permission}\" has no registered ABAC policy — ` +\n `DENYING (strictPolicies defaults to true as of 5.13). Register one with ` +\n `definePolicy(\"${permission}\", ...), or make sure the module that calls definePolicy is ` +\n `actually imported. Set strictPolicies: false in the access config to restore the pre-5.13 ` +\n `RBAC-only fallback (ALLOWS — not recommended).`\n : `Instance-level check for permission \"${permission}\" has no registered ABAC policy — falling ` +\n `back to the RBAC grant alone (strictPolicies: false), so any holder of \"${permission}\" can ` +\n `act on ANY resource. If this permission is meant to be resource-scoped, register a policy ` +\n `with definePolicy(\"${permission}\", ...) (and confirm the module that calls it is ` +\n `imported), or remove strictPolicies: false to deny by default.`,\n );\n }\n\n return strict;\n}\n\n/**\n * The core decision: does the user hold `permission`, and — when a `resource`\n * is supplied — does its policy pass too?\n *\n * Fails CLOSED: any error while resolving the decision denies (and logs). An\n * instance-level check for a permission with no registered policy also fails\n * CLOSED by default ({@link AccessConfigurations.strictPolicies}) rather than\n * falling back to the RBAC grant alone.\n */\nexport async function check(\n user: Auth,\n permission: string,\n context: AccessContext = {},\n): Promise<boolean> {\n try {\n const tenant = tenantFor(user, context);\n const permissions = await permissionsFor(user, tenant);\n\n if (!matchesPermission(permissions, permission)) return false;\n\n const policy = getPolicy(permission);\n\n // A policy only runs on an instance check (a resource was supplied);\n // class-level checks (`gate`) stop at the grant.\n if (context.resource !== undefined && policy === undefined) {\n if (unpolicedShouldDeny(permission)) return false;\n }\n\n if (policy === undefined || context.resource === undefined) return true;\n\n const roles = await rolesFor(user, tenant);\n\n return Boolean(\n await policy(user, context.resource, {\n ...context,\n tenant,\n hasRole: (role) => roles.includes(role),\n hasPermission: (perm) => matchesPermission(permissions, perm),\n }),\n );\n } catch (error) {\n if (error instanceof AccessConfigError) throw error; // misconfig is loud, not a silent deny\n\n log.error(\"access\", \"check\", error);\n\n return false;\n }\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport { ForbiddenError, t } from \"@warlock.js/core\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessErrorCodes } from \"../utils/access-error-codes\";\nimport { check, flush as flushUser, rolesFor } from \"./engine\";\n\n/** Whether the user holds `permission` (and passes its policy when a resource is given). */\nexport function can(user: Auth, permission: string, context?: AccessContext): Promise<boolean> {\n return check(user, permission, context);\n}\n\n/** Inverse of {@link can}. */\nexport async function cannot(\n user: Auth,\n permission: string,\n context?: AccessContext,\n): Promise<boolean> {\n return !(await can(user, permission, context));\n}\n\n/** Whether the user holds EVERY listed permission. Short-circuits on the first miss. */\nexport async function canAll(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<boolean> {\n for (const permission of permissions) {\n if (!(await can(user, permission, context))) return false;\n }\n\n return true;\n}\n\n/** Whether the user holds ANY listed permission. Short-circuits on the first hit. */\nexport async function canAny(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<boolean> {\n for (const permission of permissions) {\n if (await can(user, permission, context)) return true;\n }\n\n return false;\n}\n\nfunction forbidden(): never {\n throw new ForbiddenError(t(\"access.errors.forbidden\"), {\n errorCode: AccessErrorCodes.Forbidden,\n });\n}\n\n/** Assert the user holds `permission`; throw `ForbiddenError` (403) otherwise. */\nexport async function authorize(\n user: Auth,\n permission: string,\n context?: AccessContext,\n): Promise<void> {\n if (!(await can(user, permission, context))) forbidden();\n}\n\n/** Assert the user holds EVERY listed permission; throw otherwise. */\nexport async function authorizeAll(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<void> {\n if (!(await canAll(user, permissions, context))) forbidden();\n}\n\n/** Assert the user holds ANY listed permission; throw otherwise. */\nexport async function authorizeAny(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<void> {\n if (!(await canAny(user, permissions, context))) forbidden();\n}\n\n/** Whether the user has the given role. */\nexport async function hasRole(user: Auth, role: string, tenant?: string): Promise<boolean> {\n return (await rolesFor(user, tenant)).includes(role);\n}\n\n/** Whether the user has ANY of the given roles. */\nexport async function hasAnyRole(user: Auth, roles: string[], tenant?: string): Promise<boolean> {\n const held = await rolesFor(user, tenant);\n\n return roles.some((role) => held.includes(role));\n}\n\n/** Whether the user has ALL of the given roles. */\nexport async function hasAllRoles(user: Auth, roles: string[], tenant?: string): Promise<boolean> {\n const held = await rolesFor(user, tenant);\n\n return roles.every((role) => held.includes(role));\n}\n\n/**\n * The access facade — every check plus `flush` to drop a user's cached set.\n * Role assignment lives on the ejected `UserRole` model in app-land; callers do\n * `UserRole.assign(...)` then `access.flush(user, tenant)`.\n *\n * @example\n * import { access } from \"@warlock.js/access\";\n * if (await access.can(user, \"orders.update\", { resource: order })) { ... }\n * await access.flush(user, \"tenant-1\");\n */\nexport const access = {\n can,\n cannot,\n canAll,\n canAny,\n authorize,\n authorizeAll,\n authorizeAny,\n hasRole,\n hasAnyRole,\n hasAllRoles,\n /** Drop the user's cached role/permission set (call after you mutate role rows). */\n flush: flushUser,\n};\n","import type { Auth } from \"@warlock.js/auth\";\nimport { t, type HttpContext, type Middleware, type Response } from \"@warlock.js/core\";\nimport type { ModelSchema } from \"@warlock.js/cascade\";\nimport { can, canAll, canAny } from \"../services/access\";\nimport { AccessErrorCodes } from \"../utils/access-error-codes\";\n\n/*\n * @warlock.js/access does NOT augment `RequestUser`, deliberately. An\n * interface can extend at most one class hierarchy, so a library-side\n * `interface RequestUser extends Auth<ModelSchema>` PRE-CLAIMS the one\n * extends slot every app needs for its own model — the app's\n * `interface RequestUser extends User {}` then fails with TS2320, and the\n * app can never see its own auth model on `request.locals.user`. (Core\n * documents the same hazard for member-level augmentation in\n * `http/middleware/utils/idempotency-key.ts`.)\n *\n * The contract instead: an app using gates augments `RequestUser` (declared\n * by `@warlock.js/auth`, which also augments core's `RequestLocals` with the\n * `user` key) to its OWN `Auth`-derived model; `authUserOf` below is the\n * single boundary where access asserts that contract to satisfy `can()`'s\n * parameter type.\n */\n\n/**\n * The one place access bridges `request.locals.user` (app-augmented via\n * `@warlock.js/auth`'s `RequestUser`, empty by default) to the\n * `Auth<ModelSchema>` that `can()`/`canAny()`/`canAll()` require. The\n * assertion is the contract boundary, not a shortcut: the app's `RequestUser`\n * augmentation promises an `Auth`-derived model, and the auth middleware\n * placed exactly that instance at `request.locals.user` at runtime. Kept to\n * this single accessor so the promise is asserted once, visibly, instead of\n * scattered.\n */\nfunction authUserOf(request: HttpContext[\"request\"]): Auth<ModelSchema> | undefined {\n return request.locals.user as unknown as Auth<ModelSchema> | undefined;\n}\n\nfunction deny(response: Response) {\n return response.forbidden({\n error: t(\"access.errors.forbidden\"),\n errorCode: AccessErrorCodes.Forbidden,\n });\n}\n\n/**\n * Gate a route on a single permission (class-level). Stack it AFTER\n * `authMiddleware`, which sets `request.locals.user`.\n *\n * @example\n * router.post(\"/orders\", createOrder, {\n * middleware: [authMiddleware([]), gate(\"orders.create\")],\n * });\n */\nexport function gate(permission: string): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await can(user, permission))) return deny(response);\n };\n}\n\n/** Gate a route on holding ANY of the listed permissions. */\nexport function gateAny(permissions: string[]): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await canAny(user, permissions))) return deny(response);\n };\n}\n\n/** Gate a route on holding ALL of the listed permissions. */\nexport function gateAll(permissions: string[]): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await canAll(user, permissions))) return deny(response);\n };\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { RolesMap } from \"../contracts/types\";\n\n/** Coerce a roles value (`undefined` / single string / array) into a string array. */\nfunction toRoleList(value: unknown): string[] {\n if (Array.isArray(value)) return value as string[];\n\n if (typeof value === \"string\" && value.length > 0) return [value];\n\n return [];\n}\n\n/**\n * The zero-config resolver: reads a user's roles from a model field and maps\n * them to permissions through your `roles` catalog. Works out of the box for\n * both a `roles` array column and a single `role` column.\n *\n * Swap `readRoles` to read from anywhere else (a relation, a token claim); for\n * a different storage shape entirely, implement {@link AccessResolver} directly.\n *\n * @example\n * new DefaultAccessResolver({ editor: [\"orders.*\"], viewer: [\"orders.view\"] });\n * new DefaultAccessResolver(rolesMap, (user) => user.get(\"memberRoles\"));\n */\nexport class DefaultAccessResolver implements AccessResolver {\n /**\n * The sets are a pure function of the loaded user, so caching them would\n * only delay a role change; the engine reads them straight from the user.\n */\n public readonly cacheable = false;\n\n public constructor(\n private readonly roles: RolesMap,\n private readonly readRoles: (user: Auth) => unknown = (user) =>\n user.get(\"roles\") ?? user.get(\"role\"),\n ) {}\n\n public async resolveRoles(user: Auth): Promise<string[]> {\n return toRoleList(await this.readRoles(user));\n }\n\n public async resolvePermissions(user: Auth): Promise<string[]> {\n const roles = await this.resolveRoles(user);\n\n // Guard against a role named `__proto__` / `constructor` resolving to an\n // inherited (non-array) value.\n return roles.flatMap((role) => {\n if (!Object.prototype.hasOwnProperty.call(this.roles, role)) {\n return [];\n }\n\n // `hasOwnProperty` proves the KEY is present; it says nothing about the\n // value, which under `noUncheckedIndexedAccess` is `string[] |\n // undefined`. Falling back to NO permissions is the only safe direction\n // here: this function's result is what the caller checks before granting\n // access, so an unreadable role must grant nothing rather than be\n // asserted into something.\n return this.roles[role] ?? [];\n });\n }\n}\n"],"mappings":"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"}
@@ -33,6 +33,16 @@ export interface AccessResolver {
33
33
  * for single-tenant apps.
34
34
  */
35
35
  resolveTenant?(user: Auth): string | undefined;
36
+ /**
37
+ * Optional. Set to `false` to keep the engine from storing this resolver's
38
+ * roles and permissions in the shared cache: every check then reads them
39
+ * from the resolver (checks on one user object within a request still share
40
+ * one resolution). Use it when the sets are a cheap function of the loaded
41
+ * user, so a role change shows up at once instead of after the cache entry
42
+ * expires. Omitted or `true`, results are cached.
43
+ * @default true
44
+ */
45
+ readonly cacheable?: boolean;
36
46
  }
37
47
  //#endregion
38
48
  //# sourceMappingURL=access-resolver.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"access-resolver.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/contracts/access-resolver.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;iBAuBiB;;EAEf,aAAa,MAAM,MAAM,kBAAkB;;EAG3C,mBAAmB,MAAM,MAAM,kBAAkB;;;;;;;EAQjD,eAAe,MAAM"}
1
+ {"version":3,"file":"access-resolver.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/contracts/access-resolver.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;iBAuBiB;;EAEf,aAAa,MAAM,MAAM,kBAAkB;;EAG3C,mBAAmB,MAAM,MAAM,kBAAkB;;;;;;;EAQjD,eAAe,MAAM;;;;;;;;;;WAWZ"}
@@ -17,6 +17,11 @@ import { Auth } from "@warlock.js/auth";
17
17
  export declare class DefaultAccessResolver implements AccessResolver {
18
18
  private readonly roles;
19
19
  private readonly readRoles;
20
+ /**
21
+ * The sets are a pure function of the loaded user, so caching them would
22
+ * only delay a role change; the engine reads them straight from the user.
23
+ */
24
+ readonly cacheable = false;
20
25
  constructor(roles: RolesMap, readRoles?: (user: Auth) => unknown);
21
26
  resolveRoles(user: Auth): Promise<string[]>;
22
27
  resolvePermissions(user: Auth): Promise<string[]>;
@@ -1 +1 @@
1
- {"version":3,"file":"default-resolver.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/default-resolver.ts"],"mappings":";;;;;;;;;;;;;;;;qBAyBa,iCAAiC;mBAEzB;mBACA;EAFnB,YACmB,OAAO,UACP,aAAY,MAAM;EAIxB,aAAa,MAAM,OAAO;EAI1B,mBAAmB,MAAM,OAAO"}
1
+ {"version":3,"file":"default-resolver.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/default-resolver.ts"],"mappings":";;;;;;;;;;;;;;;;qBAyBa,iCAAiC;mBAQzB;mBACA;;;;;WAJH;EAEhB,YACmB,OAAO,UACP,aAAY,MAAM;EAIxB,aAAa,MAAM,OAAO;EAI1B,mBAAmB,MAAM,OAAO"}
@@ -20,6 +20,11 @@ function toRoleList(value) {
20
20
  var DefaultAccessResolver = class {
21
21
  roles;
22
22
  readRoles;
23
+ /**
24
+ * The sets are a pure function of the loaded user, so caching them would
25
+ * only delay a role change; the engine reads them straight from the user.
26
+ */
27
+ cacheable = false;
23
28
  constructor(roles, readRoles = (user) => user.get("roles") ?? user.get("role")) {
24
29
  this.roles = roles;
25
30
  this.readRoles = readRoles;
@@ -1 +1 @@
1
- {"version":3,"file":"default-resolver.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/default-resolver.ts"],"sourcesContent":["import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { RolesMap } from \"../contracts/types\";\n\n/** Coerce a roles value (`undefined` / single string / array) into a string array. */\nfunction toRoleList(value: unknown): string[] {\n if (Array.isArray(value)) return value as string[];\n\n if (typeof value === \"string\" && value.length > 0) return [value];\n\n return [];\n}\n\n/**\n * The zero-config resolver: reads a user's roles from a model field and maps\n * them to permissions through your `roles` catalog. Works out of the box for\n * both a `roles` array column and a single `role` column.\n *\n * Swap `readRoles` to read from anywhere else (a relation, a token claim); for\n * a different storage shape entirely, implement {@link AccessResolver} directly.\n *\n * @example\n * new DefaultAccessResolver({ editor: [\"orders.*\"], viewer: [\"orders.view\"] });\n * new DefaultAccessResolver(rolesMap, (user) => user.get(\"memberRoles\"));\n */\nexport class DefaultAccessResolver implements AccessResolver {\n public constructor(\n private readonly roles: RolesMap,\n private readonly readRoles: (user: Auth) => unknown = (user) =>\n user.get(\"roles\") ?? user.get(\"role\"),\n ) {}\n\n public async resolveRoles(user: Auth): Promise<string[]> {\n return toRoleList(await this.readRoles(user));\n }\n\n public async resolvePermissions(user: Auth): Promise<string[]> {\n const roles = await this.resolveRoles(user);\n\n // Guard against a role named `__proto__` / `constructor` resolving to an\n // inherited (non-array) value.\n return roles.flatMap((role) => {\n if (!Object.prototype.hasOwnProperty.call(this.roles, role)) {\n return [];\n }\n\n // `hasOwnProperty` proves the KEY is present; it says nothing about the\n // value, which under `noUncheckedIndexedAccess` is `string[] |\n // undefined`. Falling back to NO permissions is the only safe direction\n // here: this function's result is what the caller checks before granting\n // access, so an unreadable role must grant nothing rather than be\n // asserted into something.\n return this.roles[role] ?? [];\n });\n }\n}\n"],"mappings":";;AAKA,SAAS,WAAW,OAA0B;CAC5C,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO;CAEjC,IAAI,OAAO,UAAU,YAAY,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK;CAEhE,OAAO,CAAC;AACV;;;;;;;;;;;;;AAcA,IAAa,wBAAb,MAA6D;CAExC;CACA;CAFnB,AAAO,YACL,AAAiB,OACjB,AAAiB,aAAsC,SACrD,KAAK,IAAI,OAAO,KAAK,KAAK,IAAI,MAAM,GACtC;EAHiB;EACA;CAEhB;CAEH,MAAa,aAAa,MAA+B;EACvD,OAAO,WAAW,MAAM,KAAK,UAAU,IAAI,CAAC;CAC9C;CAEA,MAAa,mBAAmB,MAA+B;EAK7D,QAAO,MAJa,KAAK,aAAa,IAAI,EAI9B,CAAC,SAAS,SAAS;GAC7B,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,KAAK,OAAO,IAAI,GACxD,OAAO,CAAC;GASV,OAAO,KAAK,MAAM,SAAS,CAAC;EAC9B,CAAC;CACH;AACF"}
1
+ {"version":3,"file":"default-resolver.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/default-resolver.ts"],"sourcesContent":["import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { RolesMap } from \"../contracts/types\";\n\n/** Coerce a roles value (`undefined` / single string / array) into a string array. */\nfunction toRoleList(value: unknown): string[] {\n if (Array.isArray(value)) return value as string[];\n\n if (typeof value === \"string\" && value.length > 0) return [value];\n\n return [];\n}\n\n/**\n * The zero-config resolver: reads a user's roles from a model field and maps\n * them to permissions through your `roles` catalog. Works out of the box for\n * both a `roles` array column and a single `role` column.\n *\n * Swap `readRoles` to read from anywhere else (a relation, a token claim); for\n * a different storage shape entirely, implement {@link AccessResolver} directly.\n *\n * @example\n * new DefaultAccessResolver({ editor: [\"orders.*\"], viewer: [\"orders.view\"] });\n * new DefaultAccessResolver(rolesMap, (user) => user.get(\"memberRoles\"));\n */\nexport class DefaultAccessResolver implements AccessResolver {\n /**\n * The sets are a pure function of the loaded user, so caching them would\n * only delay a role change; the engine reads them straight from the user.\n */\n public readonly cacheable = false;\n\n public constructor(\n private readonly roles: RolesMap,\n private readonly readRoles: (user: Auth) => unknown = (user) =>\n user.get(\"roles\") ?? user.get(\"role\"),\n ) {}\n\n public async resolveRoles(user: Auth): Promise<string[]> {\n return toRoleList(await this.readRoles(user));\n }\n\n public async resolvePermissions(user: Auth): Promise<string[]> {\n const roles = await this.resolveRoles(user);\n\n // Guard against a role named `__proto__` / `constructor` resolving to an\n // inherited (non-array) value.\n return roles.flatMap((role) => {\n if (!Object.prototype.hasOwnProperty.call(this.roles, role)) {\n return [];\n }\n\n // `hasOwnProperty` proves the KEY is present; it says nothing about the\n // value, which under `noUncheckedIndexedAccess` is `string[] |\n // undefined`. Falling back to NO permissions is the only safe direction\n // here: this function's result is what the caller checks before granting\n // access, so an unreadable role must grant nothing rather than be\n // asserted into something.\n return this.roles[role] ?? [];\n });\n }\n}\n"],"mappings":";;AAKA,SAAS,WAAW,OAA0B;CAC5C,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO;CAEjC,IAAI,OAAO,UAAU,YAAY,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK;CAEhE,OAAO,CAAC;AACV;;;;;;;;;;;;;AAcA,IAAa,wBAAb,MAA6D;CAQxC;CACA;;;;;CAJnB,AAAgB,YAAY;CAE5B,AAAO,YACL,AAAiB,OACjB,AAAiB,aAAsC,SACrD,KAAK,IAAI,OAAO,KAAK,KAAK,IAAI,MAAM,GACtC;EAHiB;EACA;CAEhB;CAEH,MAAa,aAAa,MAA+B;EACvD,OAAO,WAAW,MAAM,KAAK,UAAU,IAAI,CAAC;CAC9C;CAEA,MAAa,mBAAmB,MAA+B;EAK7D,QAAO,MAJa,KAAK,aAAa,IAAI,EAI9B,CAAC,SAAS,SAAS;GAC7B,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,KAAK,OAAO,IAAI,GACxD,OAAO,CAAC;GASV,OAAO,KAAK,MAAM,SAAS,CAAC;EAC9B,CAAC;CACH;AACF"}
@@ -1 +1 @@
1
- {"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":";;;;;;;;wBA8GsB,MAAM,MAAM,MAAM,kBAAkB"}
1
+ {"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":";;;;;;;;wBAiHsB,MAAM,MAAM,MAAM,kBAAkB"}
@@ -30,6 +30,7 @@ function cacheKey(prefix, user, tenant) {
30
30
  * so the DECISION fails closed in {@link check}.
31
31
  */
32
32
  async function cached(key, loader) {
33
+ if (accessConfig.resolver().cacheable === false) return loader();
33
34
  try {
34
35
  const hit = await cache.get(key);
35
36
  if (hit) return hit;
@@ -1 +1 @@
1
- {"version":3,"file":"engine.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"sourcesContent":["import type { Auth } from \"@warlock.js/auth\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { accessConfig } from \"./access-config\";\nimport { matchesPermission } from \"./matcher\";\nimport { getPolicy } from \"./policies\";\nimport { invalidateResolutionMemo, memoizeForUser } from \"./resolution-memo\";\n\nconst PERMISSIONS_PREFIX = \"access.perms.\";\nconst ROLES_PREFIX = \"access.roles.\";\n\n/**\n * Permissions that have already triggered the \"unpoliced instance check\"\n * warning below — kept so a hot path doesn't log once per request.\n */\nconst warnedUnpolicedPermissions = new Set<string>();\n\n/** Reset the once-per-permission warning tracker. Primarily for tests. */\nexport function resetUnpolicedWarnings(): void {\n warnedUnpolicedPermissions.clear();\n}\n\n/** Resolve the effective tenant for a check (explicit → ambient → undefined). */\nfunction tenantFor(user: Auth, context: AccessContext): string | undefined {\n return context.tenant ?? accessConfig.tenant(user);\n}\n\nfunction cacheKey(prefix: string, user: Auth, tenant?: string): string {\n // Encode each segment so a `.` in an id or tenant can't collide two distinct\n // principals onto the same cache key (and serve one's grants to the other).\n const segment = (value: unknown) => encodeURIComponent(String(value));\n\n return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? \"_\")}`;\n}\n\n/**\n * Read a list through the cache, falling back to the loader.\n *\n * The cache is **best-effort**: a cache failure degrades to the loader (the\n * source of truth) and is logged, never denied. A loader failure propagates —\n * so the DECISION fails closed in {@link check}.\n */\nasync function cached(key: string, loader: () => Promise<string[]>): Promise<string[]> {\n try {\n const hit = await cache.get<string[]>(key);\n\n if (hit) return hit;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n await cache.set(key, value, { ttl: accessConfig.cacheTtl() });\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n return value;\n}\n\n/**\n * The user's effective permission set for a tenant (cached). Checks on the\n * same user object share one resolution for a short while, so stacked gates\n * and `canAll` / `canAny` read the shared cache once per request.\n */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)),\n );\n}\n\n/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(ROLES_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)),\n );\n}\n\n/**\n * The tenants whose cached sets `flush(user, tenant)` must drop: the one\n * passed, else the ambient tenant the checks themselves use (the resolver's\n * `resolveTenant`) together with the no-tenant entry.\n */\nfunction tenantsToFlush(user: Auth, tenant?: string): Array<string | undefined> {\n if (tenant !== undefined) return [tenant];\n\n let ambient: string | undefined;\n\n try {\n ambient = accessConfig.tenant(user);\n } catch {\n ambient = undefined;\n }\n\n return ambient === undefined ? [undefined] : [ambient, undefined];\n}\n\n/**\n * Drop the cached role/permission sets for a user (after any out-of-band role\n * change). Without a `tenant` it drops the set for the user's ambient tenant\n * (what `can(user, …)` reads) and the no-tenant set.\n */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n try {\n for (const target of tenantsToFlush(user, tenant)) {\n await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));\n await cache.remove(cacheKey(ROLES_PREFIX, user, target));\n }\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n } finally {\n // After the shared entries are gone, so a check cannot re-memoise them.\n invalidateResolutionMemo();\n }\n}\n\n/**\n * Surface a resource-scoped check that has no registered ABAC policy, and\n * report whether the check should now DENY.\n *\n * `strictPolicies` defaults to `true`: a forgotten `definePolicy` call (typo'd\n * permission name, or a missing `import \"./policies\"` side-effect — the\n * single most common mistake app teams make with this package, per the\n * `define-policies` skill) must never fail OPEN, so the check denies.\n *\n * `strictPolicies: false` explicitly restores the pre-5.13 behavior: fall\n * back to the RBAC grant alone (ALLOW), which is a plausible IDOR if the\n * permission was meant to be resource-scoped.\n *\n * Either way this warns once per permission (not once per call) so a hot\n * request path doesn't spam logs — mirrors cascade's\n * `warnUndeclaredSensitiveFields`.\n */\nfunction unpolicedShouldDeny(permission: string): boolean {\n const strict = accessConfig.strictPolicies();\n\n if (!warnedUnpolicedPermissions.has(permission)) {\n warnedUnpolicedPermissions.add(permission);\n\n log.warn(\n \"access\",\n \"unpoliced-check\",\n strict\n ? `Instance-level check for permission \"${permission}\" has no registered ABAC policy — ` +\n `DENYING (strictPolicies defaults to true as of 5.13). Register one with ` +\n `definePolicy(\"${permission}\", ...), or make sure the module that calls definePolicy is ` +\n `actually imported. Set strictPolicies: false in the access config to restore the pre-5.13 ` +\n `RBAC-only fallback (ALLOWS — not recommended).`\n : `Instance-level check for permission \"${permission}\" has no registered ABAC policy — falling ` +\n `back to the RBAC grant alone (strictPolicies: false), so any holder of \"${permission}\" can ` +\n `act on ANY resource. If this permission is meant to be resource-scoped, register a policy ` +\n `with definePolicy(\"${permission}\", ...) (and confirm the module that calls it is ` +\n `imported), or remove strictPolicies: false to deny by default.`,\n );\n }\n\n return strict;\n}\n\n/**\n * The core decision: does the user hold `permission`, and — when a `resource`\n * is supplied — does its policy pass too?\n *\n * Fails CLOSED: any error while resolving the decision denies (and logs). An\n * instance-level check for a permission with no registered policy also fails\n * CLOSED by default ({@link AccessConfigurations.strictPolicies}) rather than\n * falling back to the RBAC grant alone.\n */\nexport async function check(\n user: Auth,\n permission: string,\n context: AccessContext = {},\n): Promise<boolean> {\n try {\n const tenant = tenantFor(user, context);\n const permissions = await permissionsFor(user, tenant);\n\n if (!matchesPermission(permissions, permission)) return false;\n\n const policy = getPolicy(permission);\n\n // A policy only runs on an instance check (a resource was supplied);\n // class-level checks (`gate`) stop at the grant.\n if (context.resource !== undefined && policy === undefined) {\n if (unpolicedShouldDeny(permission)) return false;\n }\n\n if (policy === undefined || context.resource === undefined) return true;\n\n const roles = await rolesFor(user, tenant);\n\n return Boolean(\n await policy(user, context.resource, {\n ...context,\n tenant,\n hasRole: (role) => roles.includes(role),\n hasPermission: (perm) => matchesPermission(permissions, perm),\n }),\n );\n } catch (error) {\n if (error instanceof AccessConfigError) throw error; // misconfig is loud, not a silent deny\n\n log.error(\"access\", \"check\", error);\n\n return false;\n }\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"engine.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"sourcesContent":["import type { Auth } from \"@warlock.js/auth\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { accessConfig } from \"./access-config\";\nimport { matchesPermission } from \"./matcher\";\nimport { getPolicy } from \"./policies\";\nimport { invalidateResolutionMemo, memoizeForUser } from \"./resolution-memo\";\n\nconst PERMISSIONS_PREFIX = \"access.perms.\";\nconst ROLES_PREFIX = \"access.roles.\";\n\n/**\n * Permissions that have already triggered the \"unpoliced instance check\"\n * warning below — kept so a hot path doesn't log once per request.\n */\nconst warnedUnpolicedPermissions = new Set<string>();\n\n/** Reset the once-per-permission warning tracker. Primarily for tests. */\nexport function resetUnpolicedWarnings(): void {\n warnedUnpolicedPermissions.clear();\n}\n\n/** Resolve the effective tenant for a check (explicit → ambient → undefined). */\nfunction tenantFor(user: Auth, context: AccessContext): string | undefined {\n return context.tenant ?? accessConfig.tenant(user);\n}\n\nfunction cacheKey(prefix: string, user: Auth, tenant?: string): string {\n // Encode each segment so a `.` in an id or tenant can't collide two distinct\n // principals onto the same cache key (and serve one's grants to the other).\n const segment = (value: unknown) => encodeURIComponent(String(value));\n\n return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? \"_\")}`;\n}\n\n/**\n * Read a list through the cache, falling back to the loader.\n *\n * The cache is **best-effort**: a cache failure degrades to the loader (the\n * source of truth) and is logged, never denied. A loader failure propagates —\n * so the DECISION fails closed in {@link check}.\n */\nasync function cached(key: string, loader: () => Promise<string[]>): Promise<string[]> {\n // A resolver that opts out is the source of truth on every check.\n if (accessConfig.resolver().cacheable === false) return loader();\n\n try {\n const hit = await cache.get<string[]>(key);\n\n if (hit) return hit;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n await cache.set(key, value, { ttl: accessConfig.cacheTtl() });\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n return value;\n}\n\n/**\n * The user's effective permission set for a tenant (cached). Checks on the\n * same user object share one resolution for a short while, so stacked gates\n * and `canAll` / `canAny` read the shared cache once per request.\n */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)),\n );\n}\n\n/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(ROLES_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)),\n );\n}\n\n/**\n * The tenants whose cached sets `flush(user, tenant)` must drop: the one\n * passed, else the ambient tenant the checks themselves use (the resolver's\n * `resolveTenant`) together with the no-tenant entry.\n */\nfunction tenantsToFlush(user: Auth, tenant?: string): Array<string | undefined> {\n if (tenant !== undefined) return [tenant];\n\n let ambient: string | undefined;\n\n try {\n ambient = accessConfig.tenant(user);\n } catch {\n ambient = undefined;\n }\n\n return ambient === undefined ? [undefined] : [ambient, undefined];\n}\n\n/**\n * Drop the cached role/permission sets for a user (after any out-of-band role\n * change). Without a `tenant` it drops the set for the user's ambient tenant\n * (what `can(user, …)` reads) and the no-tenant set.\n */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n try {\n for (const target of tenantsToFlush(user, tenant)) {\n await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));\n await cache.remove(cacheKey(ROLES_PREFIX, user, target));\n }\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n } finally {\n // After the shared entries are gone, so a check cannot re-memoise them.\n invalidateResolutionMemo();\n }\n}\n\n/**\n * Surface a resource-scoped check that has no registered ABAC policy, and\n * report whether the check should now DENY.\n *\n * `strictPolicies` defaults to `true`: a forgotten `definePolicy` call (typo'd\n * permission name, or a missing `import \"./policies\"` side-effect — the\n * single most common mistake app teams make with this package, per the\n * `define-policies` skill) must never fail OPEN, so the check denies.\n *\n * `strictPolicies: false` explicitly restores the pre-5.13 behavior: fall\n * back to the RBAC grant alone (ALLOW), which is a plausible IDOR if the\n * permission was meant to be resource-scoped.\n *\n * Either way this warns once per permission (not once per call) so a hot\n * request path doesn't spam logs — mirrors cascade's\n * `warnUndeclaredSensitiveFields`.\n */\nfunction unpolicedShouldDeny(permission: string): boolean {\n const strict = accessConfig.strictPolicies();\n\n if (!warnedUnpolicedPermissions.has(permission)) {\n warnedUnpolicedPermissions.add(permission);\n\n log.warn(\n \"access\",\n \"unpoliced-check\",\n strict\n ? `Instance-level check for permission \"${permission}\" has no registered ABAC policy — ` +\n `DENYING (strictPolicies defaults to true as of 5.13). Register one with ` +\n `definePolicy(\"${permission}\", ...), or make sure the module that calls definePolicy is ` +\n `actually imported. Set strictPolicies: false in the access config to restore the pre-5.13 ` +\n `RBAC-only fallback (ALLOWS — not recommended).`\n : `Instance-level check for permission \"${permission}\" has no registered ABAC policy — falling ` +\n `back to the RBAC grant alone (strictPolicies: false), so any holder of \"${permission}\" can ` +\n `act on ANY resource. If this permission is meant to be resource-scoped, register a policy ` +\n `with definePolicy(\"${permission}\", ...) (and confirm the module that calls it is ` +\n `imported), or remove strictPolicies: false to deny by default.`,\n );\n }\n\n return strict;\n}\n\n/**\n * The core decision: does the user hold `permission`, and — when a `resource`\n * is supplied — does its policy pass too?\n *\n * Fails CLOSED: any error while resolving the decision denies (and logs). An\n * instance-level check for a permission with no registered policy also fails\n * CLOSED by default ({@link AccessConfigurations.strictPolicies}) rather than\n * falling back to the RBAC grant alone.\n */\nexport async function check(\n user: Auth,\n permission: string,\n context: AccessContext = {},\n): Promise<boolean> {\n try {\n const tenant = tenantFor(user, context);\n const permissions = await permissionsFor(user, tenant);\n\n if (!matchesPermission(permissions, permission)) return false;\n\n const policy = getPolicy(permission);\n\n // A policy only runs on an instance check (a resource was supplied);\n // class-level checks (`gate`) stop at the grant.\n if (context.resource !== undefined && policy === undefined) {\n if (unpolicedShouldDeny(permission)) return false;\n }\n\n if (policy === undefined || context.resource === undefined) return true;\n\n const roles = await rolesFor(user, tenant);\n\n return Boolean(\n await policy(user, context.resource, {\n ...context,\n tenant,\n hasRole: (role) => roles.includes(role),\n hasPermission: (perm) => matchesPermission(permissions, perm),\n }),\n );\n } catch (error) {\n if (error instanceof AccessConfigError) throw error; // misconfig is loud, not a silent deny\n\n log.error(\"access\", \"check\", error);\n\n return false;\n }\n}\n"],"mappings":"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"}
package/llms-full.txt CHANGED
@@ -404,6 +404,7 @@ class DirectResolver implements AccessResolver {
404
404
 
405
405
  ## Rules
406
406
 
407
+ - **Opt out of the engine cache with `readonly cacheable = false`** when the sets are a cheap function of the loaded user (`DefaultAccessResolver` does): every check then reads the resolver, so a role change shows at once. Omitted, results are cached.
407
408
  - **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.
408
409
  - Return plain `string[]`. Wildcards (`orders.*`, `*`) in the returned permissions are honored by the engine.
409
410
  - `resolveRoles` and `resolvePermissions` may read **different** sources — roles and permissions are independent axes (a role can be a pure label with permissions granted directly).
package/package.json CHANGED
@@ -5,12 +5,12 @@
5
5
  "environment": "server"
6
6
  },
7
7
  "peerDependencies": {
8
- "@warlock.js/auth": "5.53.1",
9
- "@warlock.js/cache": "5.53.1",
10
- "@warlock.js/cascade": "5.53.1",
11
- "@warlock.js/core": "5.53.1",
12
- "@warlock.js/logger": "5.53.1",
13
- "@warlock.js/seal": "5.53.1"
8
+ "@warlock.js/auth": "5.54.0",
9
+ "@warlock.js/cache": "5.54.0",
10
+ "@warlock.js/cascade": "5.54.0",
11
+ "@warlock.js/core": "5.54.0",
12
+ "@warlock.js/logger": "5.54.0",
13
+ "@warlock.js/seal": "5.54.0"
14
14
  },
15
15
  "repository": {
16
16
  "type": "git",
@@ -28,7 +28,7 @@
28
28
  ],
29
29
  "author": "hassanzohdy",
30
30
  "license": "MIT",
31
- "version": "5.53.1",
31
+ "version": "5.54.0",
32
32
  "main": "./cjs/index.cjs",
33
33
  "module": "./esm/index.mjs",
34
34
  "types": "./esm/index.d.mts",
@@ -95,6 +95,7 @@ class DirectResolver implements AccessResolver {
95
95
 
96
96
  ## Rules
97
97
 
98
+ - **Opt out of the engine cache with `readonly cacheable = false`** when the sets are a cheap function of the loaded user (`DefaultAccessResolver` does): every check then reads the resolver, so a role change shows at once. Omitted, results are cached.
98
99
  - **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.
99
100
  - Return plain `string[]`. Wildcards (`orders.*`, `*`) in the returned permissions are honored by the engine.
100
101
  - `resolveRoles` and `resolvePermissions` may read **different** sources — roles and permissions are independent axes (a role can be a pure label with permissions granted directly).