@warlock.js/access 5.59.0 → 5.61.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,12 @@ 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.60.0 - 2026-11-19
8
+
9
+ ### Fixed
10
+
11
+ - Cached roles and permissions expire a fixed `cache.ttl` after loading; reads no longer extend it on sliding cache drivers, so role changes show up within one ttl. Entries cached by older versions reload once.
12
+
7
13
  ## 5.54.0 - 2026-11-16
8
14
 
9
15
  ### Upgrading
package/cjs/index.cjs CHANGED
@@ -190,24 +190,37 @@ function cacheKey(prefix, user, tenant) {
190
190
  const segment = (value) => encodeURIComponent(String(value));
191
191
  return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? "_")}`;
192
192
  }
193
+ function isLiveSet(hit) {
194
+ return typeof hit === "object" && hit !== null && Array.isArray(hit.values) && typeof hit.expiresAt === "number" && hit.expiresAt > Date.now();
195
+ }
193
196
  /**
194
197
  * Read a list through the cache, falling back to the loader.
195
198
  *
196
199
  * The cache is **best-effort**: a cache failure degrades to the loader (the
197
200
  * source of truth) and is logged, never denied. A loader failure propagates —
198
201
  * so the DECISION fails closed in {@link check}.
202
+ *
203
+ * The expiry is FIXED from the moment the set was loaded (`cache.ttl`): reads
204
+ * never extend it. Entries written by an older version (a bare array) count as
205
+ * a miss and are reloaded once.
199
206
  */
200
207
  async function cached(key, loader) {
201
208
  if (accessConfig.resolver().cacheable === false) return loader();
202
209
  try {
203
210
  const hit = await _warlock_js_cache.cache.get(key);
204
- if (hit) return hit;
211
+ if (isLiveSet(hit)) return hit.values;
205
212
  } catch (error) {
206
213
  _warlock_js_logger.log.error("access", "cache", error);
207
214
  }
208
215
  const value = await loader();
209
216
  try {
210
- await _warlock_js_cache.cache.set(key, value, { ttl: accessConfig.cacheTtl() });
217
+ const ttl = accessConfig.cacheTtl();
218
+ const seconds = (0, _warlock_js_cache.parseTtl)(ttl);
219
+ const stored = {
220
+ values: value,
221
+ expiresAt: Number.isFinite(seconds) ? Date.now() + seconds * 1e3 : Number.MAX_SAFE_INTEGER
222
+ };
223
+ await _warlock_js_cache.cache.set(key, stored, { ttl });
211
224
  } catch (error) {
212
225
  _warlock_js_logger.log.error("access", "cache", error);
213
226
  }
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 // 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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"}
1
+ {"version":3,"file":"index.cjs","names":["cache","parseTtl","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, parseTtl } 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 * What the cache stores: the list plus an ABSOLUTE expiry the engine owns.\n *\n * Some cache drivers (the sliding `memoryExtended` one) push an entry's\n * expiration forward on every read, so a user who keeps making requests would\n * never see a role change made without `flush`. The engine therefore checks\n * its own `expiresAt` on read: past it, the entry is a miss and is reloaded,\n * whatever the driver does with its own TTL.\n */\ntype CachedSet = { values: string[]; expiresAt: number };\n\nfunction isLiveSet(hit: unknown): hit is CachedSet {\n return (\n typeof hit === \"object\" &&\n hit !== null &&\n Array.isArray((hit as CachedSet).values) &&\n typeof (hit as CachedSet).expiresAt === \"number\" &&\n (hit as CachedSet).expiresAt > Date.now()\n );\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 *\n * The expiry is FIXED from the moment the set was loaded (`cache.ttl`): reads\n * never extend it. Entries written by an older version (a bare array) count as\n * a miss and are reloaded once.\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<CachedSet>(key);\n\n if (isLiveSet(hit)) return hit.values;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n const ttl = accessConfig.cacheTtl();\n const seconds = parseTtl(ttl);\n const stored: CachedSet = {\n values: value,\n expiresAt: Number.isFinite(seconds) ? Date.now() + seconds * 1000 : Number.MAX_SAFE_INTEGER, // JSON-safe for Infinity\n };\n\n await cache.set(key, stored, { ttl });\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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"}
@@ -1 +1 @@
1
- {"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":";;;;;;;;wBAiHsB,MAAM,MAAM,MAAM,kBAAkB"}
1
+ {"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":";;;;;;;;wBAiJsB,MAAM,MAAM,MAAM,kBAAkB"}
@@ -3,7 +3,7 @@ import { invalidateResolutionMemo, memoizeForUser } from "./resolution-memo.mjs"
3
3
  import { accessConfig } from "./access-config.mjs";
4
4
  import { matchesPermission } from "./matcher.mjs";
5
5
  import { getPolicy } from "./policies.mjs";
6
- import { cache } from "@warlock.js/cache";
6
+ import { cache, parseTtl } from "@warlock.js/cache";
7
7
  import { log } from "@warlock.js/logger";
8
8
 
9
9
  //#region ../../packages/access/src/services/engine.ts
@@ -22,24 +22,37 @@ function cacheKey(prefix, user, tenant) {
22
22
  const segment = (value) => encodeURIComponent(String(value));
23
23
  return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? "_")}`;
24
24
  }
25
+ function isLiveSet(hit) {
26
+ return typeof hit === "object" && hit !== null && Array.isArray(hit.values) && typeof hit.expiresAt === "number" && hit.expiresAt > Date.now();
27
+ }
25
28
  /**
26
29
  * Read a list through the cache, falling back to the loader.
27
30
  *
28
31
  * The cache is **best-effort**: a cache failure degrades to the loader (the
29
32
  * source of truth) and is logged, never denied. A loader failure propagates —
30
33
  * so the DECISION fails closed in {@link check}.
34
+ *
35
+ * The expiry is FIXED from the moment the set was loaded (`cache.ttl`): reads
36
+ * never extend it. Entries written by an older version (a bare array) count as
37
+ * a miss and are reloaded once.
31
38
  */
32
39
  async function cached(key, loader) {
33
40
  if (accessConfig.resolver().cacheable === false) return loader();
34
41
  try {
35
42
  const hit = await cache.get(key);
36
- if (hit) return hit;
43
+ if (isLiveSet(hit)) return hit.values;
37
44
  } catch (error) {
38
45
  log.error("access", "cache", error);
39
46
  }
40
47
  const value = await loader();
41
48
  try {
42
- await cache.set(key, value, { ttl: accessConfig.cacheTtl() });
49
+ const ttl = accessConfig.cacheTtl();
50
+ const seconds = parseTtl(ttl);
51
+ const stored = {
52
+ values: value,
53
+ expiresAt: Number.isFinite(seconds) ? Date.now() + seconds * 1e3 : Number.MAX_SAFE_INTEGER
54
+ };
55
+ await cache.set(key, stored, { ttl });
43
56
  } catch (error) {
44
57
  log.error("access", "cache", error);
45
58
  }
@@ -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 // 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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"}
1
+ {"version":3,"file":"engine.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"sourcesContent":["import type { Auth } from \"@warlock.js/auth\";\nimport { cache, parseTtl } 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 * What the cache stores: the list plus an ABSOLUTE expiry the engine owns.\n *\n * Some cache drivers (the sliding `memoryExtended` one) push an entry's\n * expiration forward on every read, so a user who keeps making requests would\n * never see a role change made without `flush`. The engine therefore checks\n * its own `expiresAt` on read: past it, the entry is a miss and is reloaded,\n * whatever the driver does with its own TTL.\n */\ntype CachedSet = { values: string[]; expiresAt: number };\n\nfunction isLiveSet(hit: unknown): hit is CachedSet {\n return (\n typeof hit === \"object\" &&\n hit !== null &&\n Array.isArray((hit as CachedSet).values) &&\n typeof (hit as CachedSet).expiresAt === \"number\" &&\n (hit as CachedSet).expiresAt > Date.now()\n );\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 *\n * The expiry is FIXED from the moment the set was loaded (`cache.ttl`): reads\n * never extend it. Entries written by an older version (a bare array) count as\n * a miss and are reloaded once.\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<CachedSet>(key);\n\n if (isLiveSet(hit)) return hit.values;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n const ttl = accessConfig.cacheTtl();\n const seconds = parseTtl(ttl);\n const stored: CachedSet = {\n values: value,\n expiresAt: Number.isFinite(seconds) ? Date.now() + seconds * 1000 : Number.MAX_SAFE_INTEGER, // JSON-safe for Infinity\n };\n\n await cache.set(key, stored, { ttl });\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
@@ -222,7 +222,7 @@ public resolveTenant(user: Auth): string | undefined {
222
222
 
223
223
  ## Caching
224
224
 
225
- The engine caches each user's resolved set (`cache.ttl`, default `10m`). Roles changed out of band? Call `access.flush(user, tenant)`. The cache is **best-effort**: an outage degrades to the resolver, it never denies.
225
+ The engine caches each user's resolved set (`cache.ttl`, default `10m`). Roles changed out of band? Call `access.flush(user, tenant)`. The expiry is fixed from load time (reads never extend it, even on a sliding cache driver), so a bulk change such as a migration shows up within one `ttl`; to apply it at once, clear the `access.perms.*` / `access.roles.*` cache keys (`cache.removeNamespace("access")`), in every process for a per-process memory driver. The cache is **best-effort**: an outage degrades to the resolver, it never denies.
226
226
 
227
227
  ## See also
228
228
 
package/package.json CHANGED
@@ -5,12 +5,12 @@
5
5
  "environment": "server"
6
6
  },
7
7
  "peerDependencies": {
8
- "@warlock.js/auth": "5.59.0",
9
- "@warlock.js/cache": "5.59.0",
10
- "@warlock.js/cascade": "5.59.0",
11
- "@warlock.js/core": "5.59.0",
12
- "@warlock.js/logger": "5.59.0",
13
- "@warlock.js/seal": "5.59.0"
8
+ "@warlock.js/auth": "5.61.0",
9
+ "@warlock.js/cache": "5.61.0",
10
+ "@warlock.js/cascade": "5.61.0",
11
+ "@warlock.js/core": "5.61.0",
12
+ "@warlock.js/logger": "5.61.0",
13
+ "@warlock.js/seal": "5.61.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.59.0",
31
+ "version": "5.61.0",
32
32
  "main": "./cjs/index.cjs",
33
33
  "module": "./esm/index.mjs",
34
34
  "types": "./esm/index.d.mts",
@@ -80,7 +80,7 @@ public resolveTenant(user: Auth): string | undefined {
80
80
 
81
81
  ## Caching
82
82
 
83
- The engine caches each user's resolved set (`cache.ttl`, default `10m`). Roles changed out of band? Call `access.flush(user, tenant)`. The cache is **best-effort**: an outage degrades to the resolver, it never denies.
83
+ The engine caches each user's resolved set (`cache.ttl`, default `10m`). Roles changed out of band? Call `access.flush(user, tenant)`. The expiry is fixed from load time (reads never extend it, even on a sliding cache driver), so a bulk change such as a migration shows up within one `ttl`; to apply it at once, clear the `access.perms.*` / `access.roles.*` cache keys (`cache.removeNamespace("access")`), in every process for a per-process memory driver. The cache is **best-effort**: an outage degrades to the resolver, it never denies.
84
84
 
85
85
  ## See also
86
86