@warlock.js/access 5.30.0 → 5.31.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/access` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.31.0 - 2026-10-18
+
+### Fixed
+
+- Access skills no longer end in stray code fences, and the cache configuration recipe is an object expression rather than a labelled statement.
+
 ## 5.30.0 - 2026-10-16
 
 ### Changed
@@ -81,6 +87,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed

package/README.md

@@ -59,7 +59,9 @@ definePolicy("orders.update", (user, order) => order.get("customer_id") === user
 await authorize(user, "orders.update", { resource: order });
 
 // boolean, anywhere
-if (await can(user, "orders.viewCost")) { /* … */ }
+if (await can(user, "orders.viewCost")) {
+  /* … */
+}
 ```
 
 > Register `definePolicy` calls per module, in `src/app/<module>/policies/`, loaded by an `import "./policies";` side-effect in that module's `main.ts` — a policy defined in an unimported module silently never registers.

package/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["cache","ForbiddenError","flushUser"],"sources":["../../../../../../../packages/access/src/utils/access-error-codes.ts","../../../../../../../packages/access/src/utils/access-config-error.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\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { AccessConfigurations } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\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}\n\n/** Clear the active config. Used by the connector on dev-restart and by tests. */\nexport function resetAccessConfig(): void {\n  current = undefined;\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\";\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(\n  key: string,\n  loader: () => Promise<string[]>,\n): 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/** The user's effective permission set for a tenant (cached). */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(PERMISSIONS_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolvePermissions(user, tenant),\n  );\n}\n\n/** The user's roles for a tenant (cached). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(ROLES_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolveRoles(user, tenant),\n  );\n}\n\n/** Drop the cached role/permission sets for a user (after any out-of-band role change). */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n  try {\n    await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, tenant));\n    await cache.remove(cacheKey(ROLES_PREFIX, user, tenant));\n  } catch (error) {\n    log.error(\"access\", \"cache\", error);\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(\n  user: Auth,\n  permission: string,\n  context?: AccessContext,\n): 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(\n  user: Auth,\n  role: string,\n  tenant?: string,\n): 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(\n  user: Auth,\n  roles: string[],\n  tenant?: string,\n): 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(\n  user: Auth,\n  roles: string[],\n  tenant?: string,\n): 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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"}
+{"version":3,"file":"index.cjs","names":["cache","ForbiddenError","flushUser"],"sources":["../../../../../../../packages/access/src/utils/access-error-codes.ts","../../../../../../../packages/access/src/utils/access-config-error.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\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { AccessConfigurations } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\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}\n\n/** Clear the active config. Used by the connector on dev-restart and by tests. */\nexport function resetAccessConfig(): void {\n  current = undefined;\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\";\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/** The user's effective permission set for a tenant (cached). */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(PERMISSIONS_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolvePermissions(user, tenant),\n  );\n}\n\n/** The user's roles for a tenant (cached). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(ROLES_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolveRoles(user, tenant),\n  );\n}\n\n/** Drop the cached role/permission sets for a user (after any out-of-band role change). */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n  try {\n    await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, tenant));\n    await cache.remove(cacheKey(ROLES_PREFIX, user, tenant));\n  } catch (error) {\n    log.error(\"access\", \"cache\", error);\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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"}

package/esm/services/access.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/access.ts"],"mappings":";;;;;;iBAOgB,GAAA,CACd,IAAA,EAAM,IAAA,EACN,UAAA,UACA,OAAA,GAAU,aAAA,GACT,OAAA;AAJH;AAAA,iBASsB,MAAA,CACpB,IAAA,EAAM,IAAA,EACN,UAAA,UACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,MAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBASmB,MAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAemB,SAAA,CACpB,IAAA,EAAM,IAAA,EACN,UAAA,UACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,YAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,YAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,OAAA,CACpB,IAAA,EAAM,IAAA,EACN,IAAA,UACA,MAAA,YACC,OAAO;;iBAKY,UAAA,CACpB,IAAA,EAAM,IAAA,EACN,KAAA,YACA,MAAA,YACC,OAAO;AAjFV;AAAA,iBAwFsB,WAAA,CACpB,IAAA,EAAM,IAAA,EACN,KAAA,YACA,MAAA,YACC,OAAO;;;;;;;;;;;cAgBG,MAAA;;;;;;;;;;mCA/FH"}
+{"version":3,"file":"access.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/access.ts"],"mappings":";;;;;;iBAOgB,GAAA,CAAI,IAAA,EAAM,IAAA,EAAM,UAAA,UAAoB,OAAA,GAAU,aAAA,GAAgB,OAAA;AAA9E;AAAA,iBAKsB,MAAA,CACpB,IAAA,EAAM,IAAA,EACN,UAAA,UACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,MAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBASmB,MAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAemB,SAAA,CACpB,IAAA,EAAM,IAAA,EACN,UAAA,UACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,YAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,YAAA,CACpB,IAAA,EAAM,IAAA,EACN,WAAA,YACA,OAAA,GAAU,aAAA,GACT,OAAA;;iBAKmB,OAAA,CAAQ,IAAA,EAAM,IAAA,EAAM,IAAA,UAAc,MAAA,YAAkB,OAAO;;iBAK3D,UAAA,CAAW,IAAA,EAAM,IAAA,EAAM,KAAA,YAAiB,MAAA,YAAkB,OAAO;AAzEvF;AAAA,iBAgFsB,WAAA,CAAY,IAAA,EAAM,IAAA,EAAM,KAAA,YAAiB,MAAA,YAAkB,OAAO;;;;;;;;;;;cAgB3E,MAAA;;;;;;;;;;mCAnFH"}

package/esm/services/access.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"access.mjs","names":["flushUser"],"sources":["../../../../../../../../packages/access/src/services/access.ts"],"sourcesContent":["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(\n  user: Auth,\n  permission: string,\n  context?: AccessContext,\n): 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(\n  user: Auth,\n  role: string,\n  tenant?: string,\n): 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(\n  user: Auth,\n  roles: string[],\n  tenant?: string,\n): 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(\n  user: Auth,\n  roles: string[],\n  tenant?: string,\n): 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"],"mappings":";;;;;;AAOA,SAAgB,IACd,MACA,YACA,SACkB;CAClB,OAAO,MAAM,MAAM,YAAY,OAAO;AACxC;;AAGA,eAAsB,OACpB,MACA,YACA,SACkB;CAClB,OAAO,CAAE,MAAM,IAAI,MAAM,YAAY,OAAO;AAC9C;;AAGA,eAAsB,OACpB,MACA,aACA,SACkB;CAClB,KAAK,MAAM,cAAc,aACvB,IAAI,CAAE,MAAM,IAAI,MAAM,YAAY,OAAO,GAAI,OAAO;CAGtD,OAAO;AACT;;AAGA,eAAsB,OACpB,MACA,aACA,SACkB;CAClB,KAAK,MAAM,cAAc,aACvB,IAAI,MAAM,IAAI,MAAM,YAAY,OAAO,GAAG,OAAO;CAGnD,OAAO;AACT;AAEA,SAAS,YAAmB;CAC1B,MAAM,IAAI,eAAe,EAAE,yBAAyB,GAAG,EACrD,mBACF,CAAC;AACH;;AAGA,eAAsB,UACpB,MACA,YACA,SACe;CACf,IAAI,CAAE,MAAM,IAAI,MAAM,YAAY,OAAO,GAAI,UAAU;AACzD;;AAGA,eAAsB,aACpB,MACA,aACA,SACe;CACf,IAAI,CAAE,MAAM,OAAO,MAAM,aAAa,OAAO,GAAI,UAAU;AAC7D;;AAGA,eAAsB,aACpB,MACA,aACA,SACe;CACf,IAAI,CAAE,MAAM,OAAO,MAAM,aAAa,OAAO,GAAI,UAAU;AAC7D;;AAGA,eAAsB,QACpB,MACA,MACA,QACkB;CAClB,QAAQ,MAAM,SAAS,MAAM,MAAM,EAAC,CAAE,SAAS,IAAI;AACrD;;AAGA,eAAsB,WACpB,MACA,OACA,QACkB;CAClB,MAAM,OAAO,MAAM,SAAS,MAAM,MAAM;CAExC,OAAO,MAAM,MAAM,SAAS,KAAK,SAAS,IAAI,CAAC;AACjD;;AAGA,eAAsB,YACpB,MACA,OACA,QACkB;CAClB,MAAM,OAAO,MAAM,SAAS,MAAM,MAAM;CAExC,OAAO,MAAM,OAAO,SAAS,KAAK,SAAS,IAAI,CAAC;AAClD;;;;;;;;;;;AAYA,MAAa,SAAS;CACpB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;;CAEOA;AACT"}
+{"version":3,"file":"access.mjs","names":["flushUser"],"sources":["../../../../../../../../packages/access/src/services/access.ts"],"sourcesContent":["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"],"mappings":";;;;;;AAOA,SAAgB,IAAI,MAAY,YAAoB,SAA2C;CAC7F,OAAO,MAAM,MAAM,YAAY,OAAO;AACxC;;AAGA,eAAsB,OACpB,MACA,YACA,SACkB;CAClB,OAAO,CAAE,MAAM,IAAI,MAAM,YAAY,OAAO;AAC9C;;AAGA,eAAsB,OACpB,MACA,aACA,SACkB;CAClB,KAAK,MAAM,cAAc,aACvB,IAAI,CAAE,MAAM,IAAI,MAAM,YAAY,OAAO,GAAI,OAAO;CAGtD,OAAO;AACT;;AAGA,eAAsB,OACpB,MACA,aACA,SACkB;CAClB,KAAK,MAAM,cAAc,aACvB,IAAI,MAAM,IAAI,MAAM,YAAY,OAAO,GAAG,OAAO;CAGnD,OAAO;AACT;AAEA,SAAS,YAAmB;CAC1B,MAAM,IAAI,eAAe,EAAE,yBAAyB,GAAG,EACrD,mBACF,CAAC;AACH;;AAGA,eAAsB,UACpB,MACA,YACA,SACe;CACf,IAAI,CAAE,MAAM,IAAI,MAAM,YAAY,OAAO,GAAI,UAAU;AACzD;;AAGA,eAAsB,aACpB,MACA,aACA,SACe;CACf,IAAI,CAAE,MAAM,OAAO,MAAM,aAAa,OAAO,GAAI,UAAU;AAC7D;;AAGA,eAAsB,aACpB,MACA,aACA,SACe;CACf,IAAI,CAAE,MAAM,OAAO,MAAM,aAAa,OAAO,GAAI,UAAU;AAC7D;;AAGA,eAAsB,QAAQ,MAAY,MAAc,QAAmC;CACzF,QAAQ,MAAM,SAAS,MAAM,MAAM,EAAC,CAAE,SAAS,IAAI;AACrD;;AAGA,eAAsB,WAAW,MAAY,OAAiB,QAAmC;CAC/F,MAAM,OAAO,MAAM,SAAS,MAAM,MAAM;CAExC,OAAO,MAAM,MAAM,SAAS,KAAK,SAAS,IAAI,CAAC;AACjD;;AAGA,eAAsB,YAAY,MAAY,OAAiB,QAAmC;CAChG,MAAM,OAAO,MAAM,SAAS,MAAM,MAAM;CAExC,OAAO,MAAM,OAAO,SAAS,KAAK,SAAS,IAAI,CAAC;AAClD;;;;;;;;;;;AAYA,MAAa,SAAS;CACpB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;;CAEOA;AACT"}

package/esm/services/engine.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":";;;;iBAiFsB,KAAA,CAAM,IAAA,EAAM,IAAA,EAAM,MAAA,YAAkB,OAAO"}
+{"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":";;;;iBA8EsB,KAAA,CAAM,IAAA,EAAM,IAAA,EAAM,MAAA,YAAkB,OAAO"}

package/esm/services/engine.mjs.map

@@ -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\";\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(\n  key: string,\n  loader: () => Promise<string[]>,\n): 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/** The user's effective permission set for a tenant (cached). */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(PERMISSIONS_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolvePermissions(user, tenant),\n  );\n}\n\n/** The user's roles for a tenant (cached). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(ROLES_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolveRoles(user, tenant),\n  );\n}\n\n/** Drop the cached role/permission sets for a user (after any out-of-band role change). */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n  try {\n    await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, tenant));\n    await cache.remove(cacheKey(ROLES_PREFIX, user, tenant));\n  } catch (error) {\n    log.error(\"access\", \"cache\", error);\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":";;;;;;;;AASA,MAAM,qBAAqB;AAC3B,MAAM,eAAe;;;;;AAMrB,MAAM,6CAA6B,IAAI,IAAY;;AAQnD,SAAS,UAAU,MAAY,SAA4C;CACzE,OAAO,QAAQ,UAAU,aAAa,OAAO,IAAI;AACnD;AAEA,SAAS,SAAS,QAAgB,MAAY,QAAyB;CAGrE,MAAM,WAAW,UAAmB,mBAAmB,OAAO,KAAK,CAAC;CAEpE,OAAO,GAAG,SAAS,QAAQ,KAAK,QAAQ,EAAE,GAAG,QAAQ,KAAK,EAAE,EAAE,GAAG,QAAQ,UAAU,GAAG;AACxF;;;;;;;;AASA,eAAe,OACb,KACA,QACmB;CACnB,IAAI;EACF,MAAM,MAAM,MAAM,MAAM,IAAc,GAAG;EAEzC,IAAI,KAAK,OAAO;CAClB,SAAS,OAAO;EACd,IAAI,MAAM,UAAU,SAAS,KAAK;CACpC;CAEA,MAAM,QAAQ,MAAM,OAAO;CAE3B,IAAI;EACF,MAAM,MAAM,IAAI,KAAK,OAAO,EAAE,KAAK,aAAa,SAAS,EAAE,CAAC;CAC9D,SAAS,OAAO;EACd,IAAI,MAAM,UAAU,SAAS,KAAK;CACpC;CAEA,OAAO;AACT;;AAGA,SAAgB,eAAe,MAAY,QAAoC;CAC7E,OAAO,OAAO,SAAS,oBAAoB,MAAM,MAAM,SACrD,aAAa,SAAS,CAAC,CAAC,mBAAmB,MAAM,MAAM,CACzD;AACF;;AAGA,SAAgB,SAAS,MAAY,QAAoC;CACvE,OAAO,OAAO,SAAS,cAAc,MAAM,MAAM,SAC/C,aAAa,SAAS,CAAC,CAAC,aAAa,MAAM,MAAM,CACnD;AACF;;AAGA,eAAsB,MAAM,MAAY,QAAgC;CACtE,IAAI;EACF,MAAM,MAAM,OAAO,SAAS,oBAAoB,MAAM,MAAM,CAAC;EAC7D,MAAM,MAAM,OAAO,SAAS,cAAc,MAAM,MAAM,CAAC;CACzD,SAAS,OAAO;EACd,IAAI,MAAM,UAAU,SAAS,KAAK;CACpC;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAS,oBAAoB,YAA6B;CACxD,MAAM,SAAS,aAAa,eAAe;CAE3C,IAAI,CAAC,2BAA2B,IAAI,UAAU,GAAG;EAC/C,2BAA2B,IAAI,UAAU;EAEzC,IAAI,KACF,UACA,mBACA,SACI,wCAAwC,WAAW,0HAEhC,WAAW,wMAG9B,wCAAwC,WAAW,oHAC0B,WAAW,qHAEhE,WAAW,gHAEzC;CACF;CAEA,OAAO;AACT;;;;;;;;;;AAWA,eAAsB,MACpB,MACA,YACA,UAAyB,CAAC,GACR;CAClB,IAAI;EACF,MAAM,SAAS,UAAU,MAAM,OAAO;EACtC,MAAM,cAAc,MAAM,eAAe,MAAM,MAAM;EAErD,IAAI,CAAC,kBAAkB,aAAa,UAAU,GAAG,OAAO;EAExD,MAAM,SAAS,UAAU,UAAU;EAInC,IAAI,QAAQ,aAAa,UAAa,WAAW,QAC/C;OAAI,oBAAoB,UAAU,GAAG,OAAO;EAAK;EAGnD,IAAI,WAAW,UAAa,QAAQ,aAAa,QAAW,OAAO;EAEnE,MAAM,QAAQ,MAAM,SAAS,MAAM,MAAM;EAEzC,OAAO,QACL,MAAM,OAAO,MAAM,QAAQ,UAAU;GACnC,GAAG;GACH;GACA,UAAU,SAAS,MAAM,SAAS,IAAI;GACtC,gBAAgB,SAAS,kBAAkB,aAAa,IAAI;EAC9D,CAAC,CACH;CACF,SAAS,OAAO;EACd,IAAI,iBAAiB,mBAAmB,MAAM;EAE9C,IAAI,MAAM,UAAU,SAAS,KAAK;EAElC,OAAO;CACT;AACF"}
+{"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\";\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/** The user's effective permission set for a tenant (cached). */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(PERMISSIONS_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolvePermissions(user, tenant),\n  );\n}\n\n/** The user's roles for a tenant (cached). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n  return cached(cacheKey(ROLES_PREFIX, user, tenant), () =>\n    accessConfig.resolver().resolveRoles(user, tenant),\n  );\n}\n\n/** Drop the cached role/permission sets for a user (after any out-of-band role change). */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n  try {\n    await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, tenant));\n    await cache.remove(cacheKey(ROLES_PREFIX, user, tenant));\n  } catch (error) {\n    log.error(\"access\", \"cache\", error);\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":";;;;;;;;AASA,MAAM,qBAAqB;AAC3B,MAAM,eAAe;;;;;AAMrB,MAAM,6CAA6B,IAAI,IAAY;;AAQnD,SAAS,UAAU,MAAY,SAA4C;CACzE,OAAO,QAAQ,UAAU,aAAa,OAAO,IAAI;AACnD;AAEA,SAAS,SAAS,QAAgB,MAAY,QAAyB;CAGrE,MAAM,WAAW,UAAmB,mBAAmB,OAAO,KAAK,CAAC;CAEpE,OAAO,GAAG,SAAS,QAAQ,KAAK,QAAQ,EAAE,GAAG,QAAQ,KAAK,EAAE,EAAE,GAAG,QAAQ,UAAU,GAAG;AACxF;;;;;;;;AASA,eAAe,OAAO,KAAa,QAAoD;CACrF,IAAI;EACF,MAAM,MAAM,MAAM,MAAM,IAAc,GAAG;EAEzC,IAAI,KAAK,OAAO;CAClB,SAAS,OAAO;EACd,IAAI,MAAM,UAAU,SAAS,KAAK;CACpC;CAEA,MAAM,QAAQ,MAAM,OAAO;CAE3B,IAAI;EACF,MAAM,MAAM,IAAI,KAAK,OAAO,EAAE,KAAK,aAAa,SAAS,EAAE,CAAC;CAC9D,SAAS,OAAO;EACd,IAAI,MAAM,UAAU,SAAS,KAAK;CACpC;CAEA,OAAO;AACT;;AAGA,SAAgB,eAAe,MAAY,QAAoC;CAC7E,OAAO,OAAO,SAAS,oBAAoB,MAAM,MAAM,SACrD,aAAa,SAAS,CAAC,CAAC,mBAAmB,MAAM,MAAM,CACzD;AACF;;AAGA,SAAgB,SAAS,MAAY,QAAoC;CACvE,OAAO,OAAO,SAAS,cAAc,MAAM,MAAM,SAC/C,aAAa,SAAS,CAAC,CAAC,aAAa,MAAM,MAAM,CACnD;AACF;;AAGA,eAAsB,MAAM,MAAY,QAAgC;CACtE,IAAI;EACF,MAAM,MAAM,OAAO,SAAS,oBAAoB,MAAM,MAAM,CAAC;EAC7D,MAAM,MAAM,OAAO,SAAS,cAAc,MAAM,MAAM,CAAC;CACzD,SAAS,OAAO;EACd,IAAI,MAAM,UAAU,SAAS,KAAK;CACpC;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAS,oBAAoB,YAA6B;CACxD,MAAM,SAAS,aAAa,eAAe;CAE3C,IAAI,CAAC,2BAA2B,IAAI,UAAU,GAAG;EAC/C,2BAA2B,IAAI,UAAU;EAEzC,IAAI,KACF,UACA,mBACA,SACI,wCAAwC,WAAW,0HAEhC,WAAW,wMAG9B,wCAAwC,WAAW,oHAC0B,WAAW,qHAEhE,WAAW,gHAEzC;CACF;CAEA,OAAO;AACT;;;;;;;;;;AAWA,eAAsB,MACpB,MACA,YACA,UAAyB,CAAC,GACR;CAClB,IAAI;EACF,MAAM,SAAS,UAAU,MAAM,OAAO;EACtC,MAAM,cAAc,MAAM,eAAe,MAAM,MAAM;EAErD,IAAI,CAAC,kBAAkB,aAAa,UAAU,GAAG,OAAO;EAExD,MAAM,SAAS,UAAU,UAAU;EAInC,IAAI,QAAQ,aAAa,UAAa,WAAW,QAC/C;OAAI,oBAAoB,UAAU,GAAG,OAAO;EAAK;EAGnD,IAAI,WAAW,UAAa,QAAQ,aAAa,QAAW,OAAO;EAEnE,MAAM,QAAQ,MAAM,SAAS,MAAM,MAAM;EAEzC,OAAO,QACL,MAAM,OAAO,MAAM,QAAQ,UAAU;GACnC,GAAG;GACH;GACA,UAAU,SAAS,MAAM,SAAS,IAAI;GACtC,gBAAgB,SAAS,kBAAkB,aAAa,IAAI;EAC9D,CAAC,CACH;CACF,SAAS,OAAO;EACd,IAAI,iBAAiB,mBAAmB,MAAM;EAE9C,IAAI,MAAM,UAAU,SAAS,KAAK;EAElC,OAAO;CACT;AACF"}

package/llms-full.txt

@@ -33,7 +33,9 @@ A missing permission → `403` before your controller runs. Use `gateAny([...])`
 ```ts
 import { can, cannot, canAll, canAny } from "@warlock.js/access";
 
-if (await can(user, "orders.update")) { /* … */ }
+if (await can(user, "orders.update")) {
+  /* … */
+}
 
 await canAll(user, ["orders.update", "orders.viewCost"]); // needs BOTH
 await canAny(user, ["orders.update", "orders.updateStatus"]); // needs EITHER
@@ -69,7 +71,7 @@ await authorize(user, "orders.update", { resource: order, tenant }); // grant AN
 
 ## Gotchas
 
-- **Fails closed, but config errors are loud.** A resolver or policy that throws → denied and logged (a user with no roles is denied, never allowed by accident). The one exception: `AccessConfigError` (e.g. no resolver configured) is **re-thrown**, not denied — a misconfig must surface, not hide. A cache outage is different again: it degrades to the resolver (the cache fails *open*; the decision still fails closed).
+- **Fails closed, but config errors are loud.** A resolver or policy that throws → denied and logged (a user with no roles is denied, never allowed by accident). The one exception: `AccessConfigError` (e.g. no resolver configured) is **re-thrown**, not denied — a misconfig must surface, not hide. A cache outage is different again: it degrades to the resolver (the cache fails _open_; the decision still fails closed).
 - Stack `gate` **after** `authMiddleware` — it reads `request.locals.user`; without an authenticated user it `403`s.
 - The boolean `can*` family never throws; the `authorize*` family throws `ForbiddenError`. Pick per layer (controllers gate with middleware, services assert with `authorize`).
 
@@ -169,7 +171,6 @@ The engine caches each user's resolved set (`cache.ttl`, default `10m`). Roles c
 
 - The `implement-resolver` topic — write a resolver for your own storage.
 - The `manage-roles` topic — assign / revoke with the ejected table.
-```
 
 
 ## define-policies  `@warlock.js/access/define-policies/SKILL.md`
@@ -190,9 +191,11 @@ Policies live **per module**, in `src/app/<module>/policies/`, and are loaded by
 ```ts title="src/app/orders/policies/index.ts"
 import { definePolicy } from "@warlock.js/access";
 
-definePolicy("orders.update", (user, order, ctx) =>
-  order.get("organization_id") === ctx.tenant &&
-  (order.get("customer_id") === user.id || ctx.hasRole("manager")),
+definePolicy(
+  "orders.update",
+  (user, order, ctx) =>
+    order.get("organization_id") === ctx.tenant &&
+    (order.get("customer_id") === user.id || ctx.hasRole("manager")),
 );
 ```
 
@@ -228,8 +231,9 @@ Policies **deny**, they don't grant — a policy can't let a user past a permiss
 ```ts
 await authorize(user, "orders.refund", { resource: order, amount: 5000 });
 
-definePolicy("orders.refund", (user, order, ctx) =>
-  ctx.hasRole("manager") || (ctx.amount as number) <= 1000,
+definePolicy(
+  "orders.refund",
+  (user, order, ctx) => ctx.hasRole("manager") || (ctx.amount as number) <= 1000,
 );
 ```
 
@@ -351,7 +355,6 @@ class DirectResolver implements AccessResolver {
 ## See also
 
 - The `configure-access` topic — the quickstart `DefaultAccessResolver`.
-```
 
 
 ## manage-roles  `@warlock.js/access/manage-roles/SKILL.md`
@@ -378,7 +381,7 @@ await UserRole.assign(user, "viewer", "tenant-2"); // viewer in tenant-2 — sam
 await UserRole.revoke(user, "editor", "tenant-1"); // auto-flushes too
 ```
 
-The `tenant` arg is optional — omit it for single-tenant apps (roles are stored globally). In a **multi-tenant** app, always pass the tenant: an omitted or unresolved tenant scopes to *global* roles only, never the union across tenants.
+The `tenant` arg is optional — omit it for single-tenant apps (roles are stored globally). In a **multi-tenant** app, always pass the tenant: an omitted or unresolved tenant scopes to _global_ roles only, never the union across tenants.
 
 ### When you still need `access.flush`
 
@@ -426,7 +429,6 @@ If roles live on the user (a `roles` column) or in a token claim, you don't use
 
 - The `configure-access` topic — choosing the resolver.
 - The `implement-resolver` topic — non-table role storage.
-```
 
 
 ## overview  `@warlock.js/access/overview/SKILL.md`

package/package.json

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

package/skills/check-permissions/SKILL.md

@@ -25,7 +25,9 @@ A missing permission → `403` before your controller runs. Use `gateAny([...])`
 ```ts
 import { can, cannot, canAll, canAny } from "@warlock.js/access";
 
-if (await can(user, "orders.update")) { /* … */ }
+if (await can(user, "orders.update")) {
+  /* … */
+}
 
 await canAll(user, ["orders.update", "orders.viewCost"]); // needs BOTH
 await canAny(user, ["orders.update", "orders.updateStatus"]); // needs EITHER
@@ -61,7 +63,7 @@ await authorize(user, "orders.update", { resource: order, tenant }); // grant AN
 
 ## Gotchas
 
-- **Fails closed, but config errors are loud.** A resolver or policy that throws → denied and logged (a user with no roles is denied, never allowed by accident). The one exception: `AccessConfigError` (e.g. no resolver configured) is **re-thrown**, not denied — a misconfig must surface, not hide. A cache outage is different again: it degrades to the resolver (the cache fails *open*; the decision still fails closed).
+- **Fails closed, but config errors are loud.** A resolver or policy that throws → denied and logged (a user with no roles is denied, never allowed by accident). The one exception: `AccessConfigError` (e.g. no resolver configured) is **re-thrown**, not denied — a misconfig must surface, not hide. A cache outage is different again: it degrades to the resolver (the cache fails _open_; the decision still fails closed).
 - Stack `gate` **after** `authMiddleware` — it reads `request.locals.user`; without an authenticated user it `403`s.
 - The boolean `can*` family never throws; the `authorize*` family throws `ForbiddenError`. Pick per layer (controllers gate with middleware, services assert with `authorize`).
 

package/skills/configure-access/SKILL.md

@@ -86,4 +86,3 @@ The engine caches each user's resolved set (`cache.ttl`, default `10m`). Roles c
 
 - The `implement-resolver` topic — write a resolver for your own storage.
 - The `manage-roles` topic — assign / revoke with the ejected table.
-```

package/skills/define-policies/SKILL.md

@@ -14,9 +14,11 @@ Policies live **per module**, in `src/app/<module>/policies/`, and are loaded by
 ```ts title="src/app/orders/policies/index.ts"
 import { definePolicy } from "@warlock.js/access";
 
-definePolicy("orders.update", (user, order, ctx) =>
-  order.get("organization_id") === ctx.tenant &&
-  (order.get("customer_id") === user.id || ctx.hasRole("manager")),
+definePolicy(
+  "orders.update",
+  (user, order, ctx) =>
+    order.get("organization_id") === ctx.tenant &&
+    (order.get("customer_id") === user.id || ctx.hasRole("manager")),
 );
 ```
 
@@ -52,8 +54,9 @@ Policies **deny**, they don't grant — a policy can't let a user past a permiss
 ```ts
 await authorize(user, "orders.refund", { resource: order, amount: 5000 });
 
-definePolicy("orders.refund", (user, order, ctx) =>
-  ctx.hasRole("manager") || (ctx.amount as number) <= 1000,
+definePolicy(
+  "orders.refund",
+  (user, order, ctx) => ctx.hasRole("manager") || (ctx.amount as number) <= 1000,
 );
 ```
 

package/skills/implement-resolver/SKILL.md

@@ -103,4 +103,3 @@ class DirectResolver implements AccessResolver {
 ## See also
 
 - The `configure-access` topic — the quickstart `DefaultAccessResolver`.
-```

package/skills/index.md

@@ -1,11 +1,13 @@
 ---
-description: "Authorization (RBAC + ABAC) for Warlock apps: what a signed-in user is allowed to do. Exports `can`, `authorize`, `gate`, `gateAny`, `definePolicy`, `hasRole`, `access`, `DefaultAccessResolver`, `AccessResolver`, `AccessErrorCodes`. Use for: \"check a permission\", \"restrict this route to users who can update orders\", \"only the owner can edit\", \"roles and permissions\", \"per-tenant roles\", \"custom role storage\". Not this package: login, tokens, user-type gating → @warlock.js/auth; request validation → @warlock.js/seal."
+description: 'Authorization (RBAC + ABAC) for Warlock apps: what a signed-in user is allowed to do. Exports `can`, `authorize`, `gate`, `gateAny`, `definePolicy`, `hasRole`, `access`, `DefaultAccessResolver`, `AccessResolver`, `AccessErrorCodes`. Use for: "check a permission", "restrict this route to users who can update orders", "only the owner can edit", "roles and permissions", "per-tenant roles", "custom role storage". Not this package: login, tokens, user-type gating → @warlock.js/auth; request validation → @warlock.js/seal.'
 ---
+
 # @warlock.js/access
 
 Access is the authorization engine. You supply one adapter, an `AccessResolver`, that reads a user's roles and permissions from your storage; then `can(user, "orders.update")` and `gate("orders.update")` work. Two halves: permissions (RBAC grants) and policies (ABAC conditions). Server-only; reads `request.user`, so it sits beside `@warlock.js/auth`.
 
 ## The 80% path
+
 1. Orient with `overview.md`.
 2. Configure the required resolver: `configure-access.md` (`DefaultAccessResolver` for a code-defined catalog, or the ejected DB one); custom storage in `implement-resolver.md`.
 3. Gate routes and check in code: `check-permissions.md`.
@@ -13,6 +15,7 @@ Access is the authorization engine. You supply one adapter, an `AccessResolver`,
 5. Assign and revoke roles: `manage-roles.md`.
 
 ## Conventions and pitfalls
+
 - Two stages: class-level (`gate`, `can`) asks "can they at all?"; instance-level (`authorize` with a `resource`) runs the policy on the loaded row.
 - Decisions fail closed; a missing resolver is a config error, not a default allow.
 - Stack `gate` after `authMiddleware`; access does not authenticate.

package/skills/manage-roles/SKILL.md

@@ -20,7 +20,7 @@ await UserRole.assign(user, "viewer", "tenant-2"); // viewer in tenant-2 — sam
 await UserRole.revoke(user, "editor", "tenant-1"); // auto-flushes too
 ```
 
-The `tenant` arg is optional — omit it for single-tenant apps (roles are stored globally). In a **multi-tenant** app, always pass the tenant: an omitted or unresolved tenant scopes to *global* roles only, never the union across tenants.
+The `tenant` arg is optional — omit it for single-tenant apps (roles are stored globally). In a **multi-tenant** app, always pass the tenant: an omitted or unresolved tenant scopes to _global_ roles only, never the union across tenants.
 
 ### When you still need `access.flush`
 
@@ -68,4 +68,3 @@ If roles live on the user (a `roles` column) or in a token claim, you don't use
 
 - The `configure-access` topic — choosing the resolver.
 - The `implement-resolver` topic — non-table role storage.
-```