@warlock.js/access 5.52.0 → 5.53.1
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 +14 -0
- package/cjs/index.cjs +87 -7
- package/cjs/index.cjs.map +1 -1
- package/esm/services/access-config.d.mts.map +1 -1
- package/esm/services/access-config.mjs +3 -0
- package/esm/services/access-config.mjs.map +1 -1
- package/esm/services/engine.d.mts +5 -1
- package/esm/services/engine.d.mts.map +1 -1
- package/esm/services/engine.mjs +37 -7
- package/esm/services/engine.mjs.map +1 -1
- package/esm/services/resolution-memo.mjs +51 -0
- package/esm/services/resolution-memo.mjs.map +1 -0
- package/llms-full.txt +3 -0
- package/package.json +7 -7
- package/skills/check-permissions/SKILL.md +1 -0
- package/skills/manage-roles/SKILL.md +2 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,20 @@ All notable changes to `@warlock.js/access` are documented in this file.
|
|
|
4
4
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
|
|
6
6
|
|
|
7
|
+
## 5.53.0 - 2026-11-11
|
|
8
|
+
|
|
9
|
+
### Upgrading
|
|
10
|
+
|
|
11
|
+
- A role change made by another server (or written without `access.flush`) can take up to one second longer to show up on a user object that is already being checked; `access.flush` in the same process applies at once.
|
|
12
|
+
|
|
13
|
+
### Security
|
|
14
|
+
|
|
15
|
+
- `access.flush(user)` without a tenant also drops the set cached for the tenant your resolver's `resolveTenant(user)` returns (the one `can(user, …)` reads), as well as the no-tenant set. It used to drop only the no-tenant set, so in apps with an ambient tenant a revoked permission kept working until the cache expired (10 minutes by default).
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- Checks on the same user object share one resolved permission and role set for up to one second: stacked `gate()`s, `canAll` / `canAny` and repeated `can()` calls read the cache once per request instead of once per check. `access.flush` and a new configuration drop the shared sets at once.
|
|
20
|
+
|
|
7
21
|
## 5.40.0 - 2026-10-29
|
|
8
22
|
|
|
9
23
|
### Changed
|
package/cjs/index.cjs
CHANGED
|
@@ -29,6 +29,55 @@ var AccessConfigError = class extends Error {
|
|
|
29
29
|
}
|
|
30
30
|
};
|
|
31
31
|
|
|
32
|
+
//#endregion
|
|
33
|
+
//#region ../../packages/access/src/services/resolution-memo.ts
|
|
34
|
+
/**
|
|
35
|
+
* How long a resolved set is reused for the same user object. Long enough to
|
|
36
|
+
* cover one request's stacked gates and `can()` calls, short enough that a
|
|
37
|
+
* long-lived user object (a worker, a test fixture) never holds a set much
|
|
38
|
+
* longer than the shared cache would.
|
|
39
|
+
*/
|
|
40
|
+
const MEMO_MAX_AGE_MS = 1e3;
|
|
41
|
+
/** Resolved sets per user object; an entry dies with the object it belongs to. */
|
|
42
|
+
const memos = /* @__PURE__ */ new WeakMap();
|
|
43
|
+
/**
|
|
44
|
+
* Bumped by {@link invalidateResolutionMemo}: every entry from an older
|
|
45
|
+
* generation is ignored, so `flush()` and a new configuration take effect at
|
|
46
|
+
* once for every user object in this process.
|
|
47
|
+
*/
|
|
48
|
+
let generation = 0;
|
|
49
|
+
/** Drop every memoised set in this process. */
|
|
50
|
+
function invalidateResolutionMemo() {
|
|
51
|
+
generation++;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Resolve `key` for `user` once and share the promise with every check on the
|
|
55
|
+
* same user object for {@link MEMO_MAX_AGE_MS}. A rejected load is never
|
|
56
|
+
* reused, so a failed resolution is retried on the next check.
|
|
57
|
+
*/
|
|
58
|
+
function memoizeForUser(user, key, load) {
|
|
59
|
+
if (typeof user !== "object" || user === null) return load();
|
|
60
|
+
let entries = memos.get(user);
|
|
61
|
+
if (!entries) {
|
|
62
|
+
entries = /* @__PURE__ */ new Map();
|
|
63
|
+
memos.set(user, entries);
|
|
64
|
+
}
|
|
65
|
+
const now = Date.now();
|
|
66
|
+
const hit = entries.get(key);
|
|
67
|
+
if (hit && hit.generation === generation && now - hit.at < MEMO_MAX_AGE_MS) return hit.value;
|
|
68
|
+
const value = load();
|
|
69
|
+
const owner = entries;
|
|
70
|
+
owner.set(key, {
|
|
71
|
+
value,
|
|
72
|
+
at: now,
|
|
73
|
+
generation
|
|
74
|
+
});
|
|
75
|
+
value.catch(() => {
|
|
76
|
+
if (owner.get(key)?.value === value) owner.delete(key);
|
|
77
|
+
});
|
|
78
|
+
return value;
|
|
79
|
+
}
|
|
80
|
+
|
|
32
81
|
//#endregion
|
|
33
82
|
//#region ../../packages/access/src/services/access-config.ts
|
|
34
83
|
/**
|
|
@@ -50,10 +99,12 @@ let current;
|
|
|
50
99
|
function setAccessConfig(configuration) {
|
|
51
100
|
if (!configuration?.resolver) throw new AccessConfigError("No access resolver configured. Set `resolver` in src/config/access.ts to a class implementing AccessResolver — the ejected DatabaseAccessResolver, or `new DefaultAccessResolver(rolesMap)` for a fixed-role catalog.");
|
|
52
101
|
current = configuration;
|
|
102
|
+
invalidateResolutionMemo();
|
|
53
103
|
}
|
|
54
104
|
/** Clear the active config. Used by the connector on dev-restart and by tests. */
|
|
55
105
|
function resetAccessConfig() {
|
|
56
106
|
current = void 0;
|
|
107
|
+
invalidateResolutionMemo();
|
|
57
108
|
}
|
|
58
109
|
/** Accessors over the active access configuration. */
|
|
59
110
|
const accessConfig = {
|
|
@@ -161,21 +212,50 @@ async function cached(key, loader) {
|
|
|
161
212
|
}
|
|
162
213
|
return value;
|
|
163
214
|
}
|
|
164
|
-
/**
|
|
215
|
+
/**
|
|
216
|
+
* The user's effective permission set for a tenant (cached). Checks on the
|
|
217
|
+
* same user object share one resolution for a short while, so stacked gates
|
|
218
|
+
* and `canAll` / `canAny` read the shared cache once per request.
|
|
219
|
+
*/
|
|
165
220
|
function permissionsFor(user, tenant) {
|
|
166
|
-
|
|
221
|
+
const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);
|
|
222
|
+
return memoizeForUser(user, key, () => cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)));
|
|
167
223
|
}
|
|
168
|
-
/** The user's roles for a tenant (cached). */
|
|
224
|
+
/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */
|
|
169
225
|
function rolesFor(user, tenant) {
|
|
170
|
-
|
|
226
|
+
const key = cacheKey(ROLES_PREFIX, user, tenant);
|
|
227
|
+
return memoizeForUser(user, key, () => cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)));
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* The tenants whose cached sets `flush(user, tenant)` must drop: the one
|
|
231
|
+
* passed, else the ambient tenant the checks themselves use (the resolver's
|
|
232
|
+
* `resolveTenant`) together with the no-tenant entry.
|
|
233
|
+
*/
|
|
234
|
+
function tenantsToFlush(user, tenant) {
|
|
235
|
+
if (tenant !== void 0) return [tenant];
|
|
236
|
+
let ambient;
|
|
237
|
+
try {
|
|
238
|
+
ambient = accessConfig.tenant(user);
|
|
239
|
+
} catch {
|
|
240
|
+
ambient = void 0;
|
|
241
|
+
}
|
|
242
|
+
return ambient === void 0 ? [void 0] : [ambient, void 0];
|
|
171
243
|
}
|
|
172
|
-
/**
|
|
244
|
+
/**
|
|
245
|
+
* Drop the cached role/permission sets for a user (after any out-of-band role
|
|
246
|
+
* change). Without a `tenant` it drops the set for the user's ambient tenant
|
|
247
|
+
* (what `can(user, …)` reads) and the no-tenant set.
|
|
248
|
+
*/
|
|
173
249
|
async function flush(user, tenant) {
|
|
174
250
|
try {
|
|
175
|
-
|
|
176
|
-
|
|
251
|
+
for (const target of tenantsToFlush(user, tenant)) {
|
|
252
|
+
await _warlock_js_cache.cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));
|
|
253
|
+
await _warlock_js_cache.cache.remove(cacheKey(ROLES_PREFIX, user, target));
|
|
254
|
+
}
|
|
177
255
|
} catch (error) {
|
|
178
256
|
_warlock_js_logger.log.error("access", "cache", error);
|
|
257
|
+
} finally {
|
|
258
|
+
invalidateResolutionMemo();
|
|
179
259
|
}
|
|
180
260
|
}
|
|
181
261
|
/**
|
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/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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"}
|
|
1
|
+
{"version":3,"file":"index.cjs","names":["cache","ForbiddenError","t","flushUser","t"],"sources":["../../../../../../../packages/access/src/utils/access-error-codes.ts","../../../../../../../packages/access/src/utils/access-config-error.ts","../../../../../../../packages/access/src/services/resolution-memo.ts","../../../../../../../packages/access/src/services/access-config.ts","../../../../../../../packages/access/src/services/matcher.ts","../../../../../../../packages/access/src/services/policies.ts","../../../../../../../packages/access/src/services/engine.ts","../../../../../../../packages/access/src/services/access.ts","../../../../../../../packages/access/src/middleware/gate.middleware.ts","../../../../../../../packages/access/src/services/default-resolver.ts"],"sourcesContent":["/**\n * Wire-stable error codes emitted by `@warlock.js/access`. Map these in your\n * error transformer the way you map `AuthErrorCodes`. A value change here is a\n * breaking change for any client that reacts to the code.\n */\nexport enum AccessErrorCodes {\n /** EC100 — authenticated, but missing the required permission. */\n Forbidden = \"EC100\",\n}\n","/**\n * Thrown when `@warlock.js/access` is misconfigured (e.g. no resolver). Unlike a\n * runtime resolution failure — which fails CLOSED (denies) — a config error is a\n * developer mistake, so the engine re-throws it LOUD instead of silently denying.\n */\nexport class AccessConfigError extends Error {\n public constructor(message: string) {\n super(message);\n this.name = \"AccessConfigError\";\n }\n}\n","import type { Auth } from \"@warlock.js/auth\";\n\n/**\n * How long a resolved set is reused for the same user object. Long enough to\n * cover one request's stacked gates and `can()` calls, short enough that a\n * long-lived user object (a worker, a test fixture) never holds a set much\n * longer than the shared cache would.\n */\nconst MEMO_MAX_AGE_MS = 1000;\n\ntype MemoEntry = { value: Promise<string[]>; at: number; generation: number };\n\n/** Resolved sets per user object; an entry dies with the object it belongs to. */\nconst memos = new WeakMap<object, Map<string, MemoEntry>>();\n\n/**\n * Bumped by {@link invalidateResolutionMemo}: every entry from an older\n * generation is ignored, so `flush()` and a new configuration take effect at\n * once for every user object in this process.\n */\nlet generation = 0;\n\n/** Drop every memoised set in this process. */\nexport function invalidateResolutionMemo(): void {\n generation++;\n}\n\n/**\n * Resolve `key` for `user` once and share the promise with every check on the\n * same user object for {@link MEMO_MAX_AGE_MS}. A rejected load is never\n * reused, so a failed resolution is retried on the next check.\n */\nexport function memoizeForUser(\n user: Auth,\n key: string,\n load: () => Promise<string[]>,\n): Promise<string[]> {\n if (typeof user !== \"object\" || user === null) return load();\n\n let entries = memos.get(user);\n\n if (!entries) {\n entries = new Map();\n memos.set(user, entries);\n }\n\n const now = Date.now();\n const hit = entries.get(key);\n\n if (hit && hit.generation === generation && now - hit.at < MEMO_MAX_AGE_MS) {\n return hit.value;\n }\n\n const value = load();\n const owner = entries;\n\n owner.set(key, { value, at: now, generation });\n\n value.catch(() => {\n if (owner.get(key)?.value === value) owner.delete(key);\n });\n\n return value;\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { AccessConfigurations } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { invalidateResolutionMemo } from \"./resolution-memo\";\n\n/**\n * The active configuration, fed once at boot by the framework's access connector\n * via {@link setAccessConfig} (the connector reads `src/config/access.ts`).\n * Reading it before it's set throws {@link AccessConfigError} — a loud\n * misconfiguration, never a silent deny.\n */\nlet current: AccessConfigurations | undefined;\n\n/**\n * Register the access configuration. The framework's access connector calls this\n * at boot with the default export of `src/config/access.ts`. It validates that a\n * `resolver` is present, so a misconfigured authorization layer fails at STARTUP\n * rather than on the first protected request.\n *\n * @example\n * setAccessConfig({ resolver: new DefaultAccessResolver({ admin: [\"*\"] }) });\n */\nexport function setAccessConfig(configuration: AccessConfigurations): void {\n if (!configuration?.resolver) {\n throw new AccessConfigError(\n \"No access resolver configured. Set `resolver` in src/config/access.ts to a class \" +\n \"implementing AccessResolver — the ejected DatabaseAccessResolver, or \" +\n \"`new DefaultAccessResolver(rolesMap)` for a fixed-role catalog.\",\n );\n }\n\n current = configuration;\n invalidateResolutionMemo();\n}\n\n/** Clear the active config. Used by the connector on dev-restart and by tests. */\nexport function resetAccessConfig(): void {\n current = undefined;\n invalidateResolutionMemo();\n}\n\n/** Accessors over the active access configuration. */\nexport const accessConfig = {\n /**\n * The configured resolver. Throws {@link AccessConfigError} if access was never\n * configured (no `src/config/access.ts`, or the connector hasn't run).\n */\n resolver(): AccessResolver {\n if (!current) {\n throw new AccessConfigError(\n \"@warlock.js/access is not configured. Add src/config/access.ts (exporting a `resolver`) \" +\n \"— it is wired at boot by the access connector.\",\n );\n }\n\n return current.resolver;\n },\n\n /** Cache TTL for resolved permission sets. */\n cacheTtl(): string | number {\n return current?.cache?.ttl ?? \"10m\";\n },\n\n /** Whether an unpoliced instance-level check should deny instead of falling back to the RBAC grant. */\n strictPolicies(): boolean {\n return current?.strictPolicies ?? true;\n },\n\n /** Ambient tenant for this user, delegated to the resolver's optional hook. */\n tenant(user: Auth): string | undefined {\n return this.resolver().resolveTenant?.(user);\n },\n};\n","/**\n * Whether a set of granted permission patterns covers a requested permission.\n *\n * Supports three forms:\n * - exact — `\"orders.update\"` covers `\"orders.update\"`\n * - global — `\"*\"` covers everything (the super-grant)\n * - prefix wildcard — `\"orders.*\"` covers `\"orders.update\"` and `\"orders.update.status\"`\n *\n * `\"orders.*\"` does NOT cover the bare `\"orders\"` (no trailing segment).\n */\nexport function matchesPermission(granted: string[], permission: string): boolean {\n for (const pattern of granted) {\n if (pattern === \"*\" || pattern === permission) {\n return true;\n }\n\n // \"orders.*\" → prefix \"orders.\" — matches any nested permission.\n if (pattern.endsWith(\".*\") && permission.startsWith(pattern.slice(0, -1))) {\n return true;\n }\n }\n\n return false;\n}\n","import type { PolicyFn } from \"../contracts/types\";\n\nconst policies = new Map<string, PolicyFn>();\n\n/**\n * Register an ABAC condition for a permission. It runs ON TOP of the RBAC grant\n * whenever an authorization check carries a `resource` — letting you express\n * \"...but only their own / only in their tenant / only while pending\".\n *\n * @example\n * definePolicy(\"orders.update\", (user, order) => order.get(\"customer_id\") === user.id);\n */\nexport function definePolicy(permission: string, policy: PolicyFn): void {\n policies.set(permission, policy);\n}\n\n/** The policy registered for a permission, if any. */\nexport function getPolicy(permission: string): PolicyFn | undefined {\n return policies.get(permission);\n}\n\n/** Remove every registered policy. Primarily for tests. */\nexport function clearPolicies(): void {\n policies.clear();\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { accessConfig } from \"./access-config\";\nimport { matchesPermission } from \"./matcher\";\nimport { getPolicy } from \"./policies\";\nimport { invalidateResolutionMemo, memoizeForUser } from \"./resolution-memo\";\n\nconst PERMISSIONS_PREFIX = \"access.perms.\";\nconst ROLES_PREFIX = \"access.roles.\";\n\n/**\n * Permissions that have already triggered the \"unpoliced instance check\"\n * warning below — kept so a hot path doesn't log once per request.\n */\nconst warnedUnpolicedPermissions = new Set<string>();\n\n/** Reset the once-per-permission warning tracker. Primarily for tests. */\nexport function resetUnpolicedWarnings(): void {\n warnedUnpolicedPermissions.clear();\n}\n\n/** Resolve the effective tenant for a check (explicit → ambient → undefined). */\nfunction tenantFor(user: Auth, context: AccessContext): string | undefined {\n return context.tenant ?? accessConfig.tenant(user);\n}\n\nfunction cacheKey(prefix: string, user: Auth, tenant?: string): string {\n // Encode each segment so a `.` in an id or tenant can't collide two distinct\n // principals onto the same cache key (and serve one's grants to the other).\n const segment = (value: unknown) => encodeURIComponent(String(value));\n\n return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? \"_\")}`;\n}\n\n/**\n * Read a list through the cache, falling back to the loader.\n *\n * The cache is **best-effort**: a cache failure degrades to the loader (the\n * source of truth) and is logged, never denied. A loader failure propagates —\n * so the DECISION fails closed in {@link check}.\n */\nasync function cached(key: string, loader: () => Promise<string[]>): Promise<string[]> {\n try {\n const hit = await cache.get<string[]>(key);\n\n if (hit) return hit;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n await cache.set(key, value, { ttl: accessConfig.cacheTtl() });\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n return value;\n}\n\n/**\n * The user's effective permission set for a tenant (cached). Checks on the\n * same user object share one resolution for a short while, so stacked gates\n * and `canAll` / `canAny` read the shared cache once per request.\n */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)),\n );\n}\n\n/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(ROLES_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)),\n );\n}\n\n/**\n * The tenants whose cached sets `flush(user, tenant)` must drop: the one\n * passed, else the ambient tenant the checks themselves use (the resolver's\n * `resolveTenant`) together with the no-tenant entry.\n */\nfunction tenantsToFlush(user: Auth, tenant?: string): Array<string | undefined> {\n if (tenant !== undefined) return [tenant];\n\n let ambient: string | undefined;\n\n try {\n ambient = accessConfig.tenant(user);\n } catch {\n ambient = undefined;\n }\n\n return ambient === undefined ? [undefined] : [ambient, undefined];\n}\n\n/**\n * Drop the cached role/permission sets for a user (after any out-of-band role\n * change). Without a `tenant` it drops the set for the user's ambient tenant\n * (what `can(user, …)` reads) and the no-tenant set.\n */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n try {\n for (const target of tenantsToFlush(user, tenant)) {\n await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));\n await cache.remove(cacheKey(ROLES_PREFIX, user, target));\n }\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n } finally {\n // After the shared entries are gone, so a check cannot re-memoise them.\n invalidateResolutionMemo();\n }\n}\n\n/**\n * Surface a resource-scoped check that has no registered ABAC policy, and\n * report whether the check should now DENY.\n *\n * `strictPolicies` defaults to `true`: a forgotten `definePolicy` call (typo'd\n * permission name, or a missing `import \"./policies\"` side-effect — the\n * single most common mistake app teams make with this package, per the\n * `define-policies` skill) must never fail OPEN, so the check denies.\n *\n * `strictPolicies: false` explicitly restores the pre-5.13 behavior: fall\n * back to the RBAC grant alone (ALLOW), which is a plausible IDOR if the\n * permission was meant to be resource-scoped.\n *\n * Either way this warns once per permission (not once per call) so a hot\n * request path doesn't spam logs — mirrors cascade's\n * `warnUndeclaredSensitiveFields`.\n */\nfunction unpolicedShouldDeny(permission: string): boolean {\n const strict = accessConfig.strictPolicies();\n\n if (!warnedUnpolicedPermissions.has(permission)) {\n warnedUnpolicedPermissions.add(permission);\n\n log.warn(\n \"access\",\n \"unpoliced-check\",\n strict\n ? `Instance-level check for permission \"${permission}\" has no registered ABAC policy — ` +\n `DENYING (strictPolicies defaults to true as of 5.13). Register one with ` +\n `definePolicy(\"${permission}\", ...), or make sure the module that calls definePolicy is ` +\n `actually imported. Set strictPolicies: false in the access config to restore the pre-5.13 ` +\n `RBAC-only fallback (ALLOWS — not recommended).`\n : `Instance-level check for permission \"${permission}\" has no registered ABAC policy — falling ` +\n `back to the RBAC grant alone (strictPolicies: false), so any holder of \"${permission}\" can ` +\n `act on ANY resource. If this permission is meant to be resource-scoped, register a policy ` +\n `with definePolicy(\"${permission}\", ...) (and confirm the module that calls it is ` +\n `imported), or remove strictPolicies: false to deny by default.`,\n );\n }\n\n return strict;\n}\n\n/**\n * The core decision: does the user hold `permission`, and — when a `resource`\n * is supplied — does its policy pass too?\n *\n * Fails CLOSED: any error while resolving the decision denies (and logs). An\n * instance-level check for a permission with no registered policy also fails\n * CLOSED by default ({@link AccessConfigurations.strictPolicies}) rather than\n * falling back to the RBAC grant alone.\n */\nexport async function check(\n user: Auth,\n permission: string,\n context: AccessContext = {},\n): Promise<boolean> {\n try {\n const tenant = tenantFor(user, context);\n const permissions = await permissionsFor(user, tenant);\n\n if (!matchesPermission(permissions, permission)) return false;\n\n const policy = getPolicy(permission);\n\n // A policy only runs on an instance check (a resource was supplied);\n // class-level checks (`gate`) stop at the grant.\n if (context.resource !== undefined && policy === undefined) {\n if (unpolicedShouldDeny(permission)) return false;\n }\n\n if (policy === undefined || context.resource === undefined) return true;\n\n const roles = await rolesFor(user, tenant);\n\n return Boolean(\n await policy(user, context.resource, {\n ...context,\n tenant,\n hasRole: (role) => roles.includes(role),\n hasPermission: (perm) => matchesPermission(permissions, perm),\n }),\n );\n } catch (error) {\n if (error instanceof AccessConfigError) throw error; // misconfig is loud, not a silent deny\n\n log.error(\"access\", \"check\", error);\n\n return false;\n }\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport { ForbiddenError, t } from \"@warlock.js/core\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessErrorCodes } from \"../utils/access-error-codes\";\nimport { check, flush as flushUser, rolesFor } from \"./engine\";\n\n/** Whether the user holds `permission` (and passes its policy when a resource is given). */\nexport function can(user: Auth, permission: string, context?: AccessContext): Promise<boolean> {\n return check(user, permission, context);\n}\n\n/** Inverse of {@link can}. */\nexport async function cannot(\n user: Auth,\n permission: string,\n context?: AccessContext,\n): Promise<boolean> {\n return !(await can(user, permission, context));\n}\n\n/** Whether the user holds EVERY listed permission. Short-circuits on the first miss. */\nexport async function canAll(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<boolean> {\n for (const permission of permissions) {\n if (!(await can(user, permission, context))) return false;\n }\n\n return true;\n}\n\n/** Whether the user holds ANY listed permission. Short-circuits on the first hit. */\nexport async function canAny(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<boolean> {\n for (const permission of permissions) {\n if (await can(user, permission, context)) return true;\n }\n\n return false;\n}\n\nfunction forbidden(): never {\n throw new ForbiddenError(t(\"access.errors.forbidden\"), {\n errorCode: AccessErrorCodes.Forbidden,\n });\n}\n\n/** Assert the user holds `permission`; throw `ForbiddenError` (403) otherwise. */\nexport async function authorize(\n user: Auth,\n permission: string,\n context?: AccessContext,\n): Promise<void> {\n if (!(await can(user, permission, context))) forbidden();\n}\n\n/** Assert the user holds EVERY listed permission; throw otherwise. */\nexport async function authorizeAll(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<void> {\n if (!(await canAll(user, permissions, context))) forbidden();\n}\n\n/** Assert the user holds ANY listed permission; throw otherwise. */\nexport async function authorizeAny(\n user: Auth,\n permissions: string[],\n context?: AccessContext,\n): Promise<void> {\n if (!(await canAny(user, permissions, context))) forbidden();\n}\n\n/** Whether the user has the given role. */\nexport async function hasRole(user: Auth, role: string, tenant?: string): Promise<boolean> {\n return (await rolesFor(user, tenant)).includes(role);\n}\n\n/** Whether the user has ANY of the given roles. */\nexport async function hasAnyRole(user: Auth, roles: string[], tenant?: string): Promise<boolean> {\n const held = await rolesFor(user, tenant);\n\n return roles.some((role) => held.includes(role));\n}\n\n/** Whether the user has ALL of the given roles. */\nexport async function hasAllRoles(user: Auth, roles: string[], tenant?: string): Promise<boolean> {\n const held = await rolesFor(user, tenant);\n\n return roles.every((role) => held.includes(role));\n}\n\n/**\n * The access facade — every check plus `flush` to drop a user's cached set.\n * Role assignment lives on the ejected `UserRole` model in app-land; callers do\n * `UserRole.assign(...)` then `access.flush(user, tenant)`.\n *\n * @example\n * import { access } from \"@warlock.js/access\";\n * if (await access.can(user, \"orders.update\", { resource: order })) { ... }\n * await access.flush(user, \"tenant-1\");\n */\nexport const access = {\n can,\n cannot,\n canAll,\n canAny,\n authorize,\n authorizeAll,\n authorizeAny,\n hasRole,\n hasAnyRole,\n hasAllRoles,\n /** Drop the user's cached role/permission set (call after you mutate role rows). */\n flush: flushUser,\n};\n","import type { Auth } from \"@warlock.js/auth\";\nimport { t, type HttpContext, type Middleware, type Response } from \"@warlock.js/core\";\nimport type { ModelSchema } from \"@warlock.js/cascade\";\nimport { can, canAll, canAny } from \"../services/access\";\nimport { AccessErrorCodes } from \"../utils/access-error-codes\";\n\n/*\n * @warlock.js/access does NOT augment `RequestUser`, deliberately. An\n * interface can extend at most one class hierarchy, so a library-side\n * `interface RequestUser extends Auth<ModelSchema>` PRE-CLAIMS the one\n * extends slot every app needs for its own model — the app's\n * `interface RequestUser extends User {}` then fails with TS2320, and the\n * app can never see its own auth model on `request.locals.user`. (Core\n * documents the same hazard for member-level augmentation in\n * `http/middleware/utils/idempotency-key.ts`.)\n *\n * The contract instead: an app using gates augments `RequestUser` (declared\n * by `@warlock.js/auth`, which also augments core's `RequestLocals` with the\n * `user` key) to its OWN `Auth`-derived model; `authUserOf` below is the\n * single boundary where access asserts that contract to satisfy `can()`'s\n * parameter type.\n */\n\n/**\n * The one place access bridges `request.locals.user` (app-augmented via\n * `@warlock.js/auth`'s `RequestUser`, empty by default) to the\n * `Auth<ModelSchema>` that `can()`/`canAny()`/`canAll()` require. The\n * assertion is the contract boundary, not a shortcut: the app's `RequestUser`\n * augmentation promises an `Auth`-derived model, and the auth middleware\n * placed exactly that instance at `request.locals.user` at runtime. Kept to\n * this single accessor so the promise is asserted once, visibly, instead of\n * scattered.\n */\nfunction authUserOf(request: HttpContext[\"request\"]): Auth<ModelSchema> | undefined {\n return request.locals.user as unknown as Auth<ModelSchema> | undefined;\n}\n\nfunction deny(response: Response) {\n return response.forbidden({\n error: t(\"access.errors.forbidden\"),\n errorCode: AccessErrorCodes.Forbidden,\n });\n}\n\n/**\n * Gate a route on a single permission (class-level). Stack it AFTER\n * `authMiddleware`, which sets `request.locals.user`.\n *\n * @example\n * router.post(\"/orders\", createOrder, {\n * middleware: [authMiddleware([]), gate(\"orders.create\")],\n * });\n */\nexport function gate(permission: string): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await can(user, permission))) return deny(response);\n };\n}\n\n/** Gate a route on holding ANY of the listed permissions. */\nexport function gateAny(permissions: string[]): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await canAny(user, permissions))) return deny(response);\n };\n}\n\n/** Gate a route on holding ALL of the listed permissions. */\nexport function gateAll(permissions: string[]): Middleware {\n return async ({ request, response }: HttpContext) => {\n const user = authUserOf(request);\n\n if (!user) return deny(response);\n\n if (!(await canAll(user, permissions))) return deny(response);\n };\n}\n","import type { Auth } from \"@warlock.js/auth\";\nimport type { AccessResolver } from \"../contracts/access-resolver\";\nimport type { RolesMap } from \"../contracts/types\";\n\n/** Coerce a roles value (`undefined` / single string / array) into a string array. */\nfunction toRoleList(value: unknown): string[] {\n if (Array.isArray(value)) return value as string[];\n\n if (typeof value === \"string\" && value.length > 0) return [value];\n\n return [];\n}\n\n/**\n * The zero-config resolver: reads a user's roles from a model field and maps\n * them to permissions through your `roles` catalog. Works out of the box for\n * both a `roles` array column and a single `role` column.\n *\n * Swap `readRoles` to read from anywhere else (a relation, a token claim); for\n * a different storage shape entirely, implement {@link AccessResolver} directly.\n *\n * @example\n * new DefaultAccessResolver({ editor: [\"orders.*\"], viewer: [\"orders.view\"] });\n * new DefaultAccessResolver(rolesMap, (user) => user.get(\"memberRoles\"));\n */\nexport class DefaultAccessResolver implements AccessResolver {\n public constructor(\n private readonly roles: RolesMap,\n private readonly readRoles: (user: Auth) => unknown = (user) =>\n user.get(\"roles\") ?? user.get(\"role\"),\n ) {}\n\n public async resolveRoles(user: Auth): Promise<string[]> {\n return toRoleList(await this.readRoles(user));\n }\n\n public async resolvePermissions(user: Auth): Promise<string[]> {\n const roles = await this.resolveRoles(user);\n\n // Guard against a role named `__proto__` / `constructor` resolving to an\n // inherited (non-array) value.\n return roles.flatMap((role) => {\n if (!Object.prototype.hasOwnProperty.call(this.roles, role)) {\n return [];\n }\n\n // `hasOwnProperty` proves the KEY is present; it says nothing about the\n // value, which under `noUncheckedIndexedAccess` is `string[] |\n // undefined`. Falling back to NO permissions is the only safe direction\n // here: this function's result is what the caller checks before granting\n // access, so an unreadable role must grant nothing rather than be\n // asserted into something.\n return this.roles[role] ?? [];\n });\n }\n}\n"],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"access-config.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/access-config.ts"],"mappings":";;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"access-config.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/access-config.ts"],"mappings":";;;;;;;;;;;;;wBAuBgB,gBAAgB,eAAe;;wBAc/B"}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { AccessConfigError } from "../utils/access-config-error.mjs";
|
|
2
|
+
import { invalidateResolutionMemo } from "./resolution-memo.mjs";
|
|
2
3
|
|
|
3
4
|
//#region ../../packages/access/src/services/access-config.ts
|
|
4
5
|
/**
|
|
@@ -20,10 +21,12 @@ let current;
|
|
|
20
21
|
function setAccessConfig(configuration) {
|
|
21
22
|
if (!configuration?.resolver) throw new AccessConfigError("No access resolver configured. Set `resolver` in src/config/access.ts to a class implementing AccessResolver — the ejected DatabaseAccessResolver, or `new DefaultAccessResolver(rolesMap)` for a fixed-role catalog.");
|
|
22
23
|
current = configuration;
|
|
24
|
+
invalidateResolutionMemo();
|
|
23
25
|
}
|
|
24
26
|
/** Clear the active config. Used by the connector on dev-restart and by tests. */
|
|
25
27
|
function resetAccessConfig() {
|
|
26
28
|
current = void 0;
|
|
29
|
+
invalidateResolutionMemo();
|
|
27
30
|
}
|
|
28
31
|
/** Accessors over the active access configuration. */
|
|
29
32
|
const accessConfig = {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"access-config.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/access-config.ts"],"sourcesContent":["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"],"mappings":"
|
|
1
|
+
{"version":3,"file":"access-config.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/access-config.ts"],"sourcesContent":["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"],"mappings":";;;;;;;;;;AAYA,IAAI;;;;;;;;;;AAWJ,SAAgB,gBAAgB,eAA2C;CACzE,IAAI,CAAC,eAAe,UAClB,MAAM,IAAI,kBACR,uNAGF;CAGF,UAAU;CACV,yBAAyB;AAC3B;;AAGA,SAAgB,oBAA0B;CACxC,UAAU;CACV,yBAAyB;AAC3B;;AAGA,MAAa,eAAe;;;;;CAK1B,WAA2B;EACzB,IAAI,CAAC,SACH,MAAM,IAAI,kBACR,wIAEF;EAGF,OAAO,QAAQ;CACjB;;CAGA,WAA4B;EAC1B,OAAO,SAAS,OAAO,OAAO;CAChC;;CAGA,iBAA0B;EACxB,OAAO,SAAS,kBAAkB;CACpC;;CAGA,OAAO,MAAgC;EACrC,OAAO,KAAK,SAAS,CAAC,CAAC,gBAAgB,IAAI;CAC7C;AACF"}
|
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import "../contracts/types.mjs";
|
|
2
2
|
import { Auth } from "@warlock.js/auth";
|
|
3
3
|
//#region ../../packages/access/src/services/engine.d.ts
|
|
4
|
-
/**
|
|
4
|
+
/**
|
|
5
|
+
* Drop the cached role/permission sets for a user (after any out-of-band role
|
|
6
|
+
* change). Without a `tenant` it drops the set for the user's ambient tenant
|
|
7
|
+
* (what `can(user, …)` reads) and the no-tenant set.
|
|
8
|
+
*/
|
|
5
9
|
export declare function flush(user: Auth, tenant?: string): Promise<void>;
|
|
6
10
|
//#endregion
|
|
7
11
|
//# sourceMappingURL=engine.d.mts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":"
|
|
1
|
+
{"version":3,"file":"engine.d.mts","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"mappings":";;;;;;;;wBA8GsB,MAAM,MAAM,MAAM,kBAAkB"}
|
package/esm/services/engine.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { AccessConfigError } from "../utils/access-config-error.mjs";
|
|
2
|
+
import { invalidateResolutionMemo, memoizeForUser } from "./resolution-memo.mjs";
|
|
2
3
|
import { accessConfig } from "./access-config.mjs";
|
|
3
4
|
import { matchesPermission } from "./matcher.mjs";
|
|
4
5
|
import { getPolicy } from "./policies.mjs";
|
|
@@ -43,21 +44,50 @@ async function cached(key, loader) {
|
|
|
43
44
|
}
|
|
44
45
|
return value;
|
|
45
46
|
}
|
|
46
|
-
/**
|
|
47
|
+
/**
|
|
48
|
+
* The user's effective permission set for a tenant (cached). Checks on the
|
|
49
|
+
* same user object share one resolution for a short while, so stacked gates
|
|
50
|
+
* and `canAll` / `canAny` read the shared cache once per request.
|
|
51
|
+
*/
|
|
47
52
|
function permissionsFor(user, tenant) {
|
|
48
|
-
|
|
53
|
+
const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);
|
|
54
|
+
return memoizeForUser(user, key, () => cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)));
|
|
49
55
|
}
|
|
50
|
-
/** The user's roles for a tenant (cached). */
|
|
56
|
+
/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */
|
|
51
57
|
function rolesFor(user, tenant) {
|
|
52
|
-
|
|
58
|
+
const key = cacheKey(ROLES_PREFIX, user, tenant);
|
|
59
|
+
return memoizeForUser(user, key, () => cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)));
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* The tenants whose cached sets `flush(user, tenant)` must drop: the one
|
|
63
|
+
* passed, else the ambient tenant the checks themselves use (the resolver's
|
|
64
|
+
* `resolveTenant`) together with the no-tenant entry.
|
|
65
|
+
*/
|
|
66
|
+
function tenantsToFlush(user, tenant) {
|
|
67
|
+
if (tenant !== void 0) return [tenant];
|
|
68
|
+
let ambient;
|
|
69
|
+
try {
|
|
70
|
+
ambient = accessConfig.tenant(user);
|
|
71
|
+
} catch {
|
|
72
|
+
ambient = void 0;
|
|
73
|
+
}
|
|
74
|
+
return ambient === void 0 ? [void 0] : [ambient, void 0];
|
|
53
75
|
}
|
|
54
|
-
/**
|
|
76
|
+
/**
|
|
77
|
+
* Drop the cached role/permission sets for a user (after any out-of-band role
|
|
78
|
+
* change). Without a `tenant` it drops the set for the user's ambient tenant
|
|
79
|
+
* (what `can(user, …)` reads) and the no-tenant set.
|
|
80
|
+
*/
|
|
55
81
|
async function flush(user, tenant) {
|
|
56
82
|
try {
|
|
57
|
-
|
|
58
|
-
|
|
83
|
+
for (const target of tenantsToFlush(user, tenant)) {
|
|
84
|
+
await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));
|
|
85
|
+
await cache.remove(cacheKey(ROLES_PREFIX, user, target));
|
|
86
|
+
}
|
|
59
87
|
} catch (error) {
|
|
60
88
|
log.error("access", "cache", error);
|
|
89
|
+
} finally {
|
|
90
|
+
invalidateResolutionMemo();
|
|
61
91
|
}
|
|
62
92
|
}
|
|
63
93
|
/**
|
|
@@ -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\";\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"}
|
|
1
|
+
{"version":3,"file":"engine.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/engine.ts"],"sourcesContent":["import type { Auth } from \"@warlock.js/auth\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { AccessContext } from \"../contracts/types\";\nimport { AccessConfigError } from \"../utils/access-config-error\";\nimport { accessConfig } from \"./access-config\";\nimport { matchesPermission } from \"./matcher\";\nimport { getPolicy } from \"./policies\";\nimport { invalidateResolutionMemo, memoizeForUser } from \"./resolution-memo\";\n\nconst PERMISSIONS_PREFIX = \"access.perms.\";\nconst ROLES_PREFIX = \"access.roles.\";\n\n/**\n * Permissions that have already triggered the \"unpoliced instance check\"\n * warning below — kept so a hot path doesn't log once per request.\n */\nconst warnedUnpolicedPermissions = new Set<string>();\n\n/** Reset the once-per-permission warning tracker. Primarily for tests. */\nexport function resetUnpolicedWarnings(): void {\n warnedUnpolicedPermissions.clear();\n}\n\n/** Resolve the effective tenant for a check (explicit → ambient → undefined). */\nfunction tenantFor(user: Auth, context: AccessContext): string | undefined {\n return context.tenant ?? accessConfig.tenant(user);\n}\n\nfunction cacheKey(prefix: string, user: Auth, tenant?: string): string {\n // Encode each segment so a `.` in an id or tenant can't collide two distinct\n // principals onto the same cache key (and serve one's grants to the other).\n const segment = (value: unknown) => encodeURIComponent(String(value));\n\n return `${prefix}${segment(user.userType)}.${segment(user.id)}.${segment(tenant ?? \"_\")}`;\n}\n\n/**\n * Read a list through the cache, falling back to the loader.\n *\n * The cache is **best-effort**: a cache failure degrades to the loader (the\n * source of truth) and is logged, never denied. A loader failure propagates —\n * so the DECISION fails closed in {@link check}.\n */\nasync function cached(key: string, loader: () => Promise<string[]>): Promise<string[]> {\n try {\n const hit = await cache.get<string[]>(key);\n\n if (hit) return hit;\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n const value = await loader();\n\n try {\n await cache.set(key, value, { ttl: accessConfig.cacheTtl() });\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n }\n\n return value;\n}\n\n/**\n * The user's effective permission set for a tenant (cached). Checks on the\n * same user object share one resolution for a short while, so stacked gates\n * and `canAll` / `canAny` read the shared cache once per request.\n */\nexport function permissionsFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(PERMISSIONS_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolvePermissions(user, tenant)),\n );\n}\n\n/** The user's roles for a tenant (cached, shared per user object like {@link permissionsFor}). */\nexport function rolesFor(user: Auth, tenant?: string): Promise<string[]> {\n const key = cacheKey(ROLES_PREFIX, user, tenant);\n\n return memoizeForUser(user, key, () =>\n cached(key, () => accessConfig.resolver().resolveRoles(user, tenant)),\n );\n}\n\n/**\n * The tenants whose cached sets `flush(user, tenant)` must drop: the one\n * passed, else the ambient tenant the checks themselves use (the resolver's\n * `resolveTenant`) together with the no-tenant entry.\n */\nfunction tenantsToFlush(user: Auth, tenant?: string): Array<string | undefined> {\n if (tenant !== undefined) return [tenant];\n\n let ambient: string | undefined;\n\n try {\n ambient = accessConfig.tenant(user);\n } catch {\n ambient = undefined;\n }\n\n return ambient === undefined ? [undefined] : [ambient, undefined];\n}\n\n/**\n * Drop the cached role/permission sets for a user (after any out-of-band role\n * change). Without a `tenant` it drops the set for the user's ambient tenant\n * (what `can(user, …)` reads) and the no-tenant set.\n */\nexport async function flush(user: Auth, tenant?: string): Promise<void> {\n try {\n for (const target of tenantsToFlush(user, tenant)) {\n await cache.remove(cacheKey(PERMISSIONS_PREFIX, user, target));\n await cache.remove(cacheKey(ROLES_PREFIX, user, target));\n }\n } catch (error) {\n log.error(\"access\", \"cache\", error);\n } finally {\n // After the shared entries are gone, so a check cannot re-memoise them.\n invalidateResolutionMemo();\n }\n}\n\n/**\n * Surface a resource-scoped check that has no registered ABAC policy, and\n * report whether the check should now DENY.\n *\n * `strictPolicies` defaults to `true`: a forgotten `definePolicy` call (typo'd\n * permission name, or a missing `import \"./policies\"` side-effect — the\n * single most common mistake app teams make with this package, per the\n * `define-policies` skill) must never fail OPEN, so the check denies.\n *\n * `strictPolicies: false` explicitly restores the pre-5.13 behavior: fall\n * back to the RBAC grant alone (ALLOW), which is a plausible IDOR if the\n * permission was meant to be resource-scoped.\n *\n * Either way this warns once per permission (not once per call) so a hot\n * request path doesn't spam logs — mirrors cascade's\n * `warnUndeclaredSensitiveFields`.\n */\nfunction unpolicedShouldDeny(permission: string): boolean {\n const strict = accessConfig.strictPolicies();\n\n if (!warnedUnpolicedPermissions.has(permission)) {\n warnedUnpolicedPermissions.add(permission);\n\n log.warn(\n \"access\",\n \"unpoliced-check\",\n strict\n ? `Instance-level check for permission \"${permission}\" has no registered ABAC policy — ` +\n `DENYING (strictPolicies defaults to true as of 5.13). Register one with ` +\n `definePolicy(\"${permission}\", ...), or make sure the module that calls definePolicy is ` +\n `actually imported. Set strictPolicies: false in the access config to restore the pre-5.13 ` +\n `RBAC-only fallback (ALLOWS — not recommended).`\n : `Instance-level check for permission \"${permission}\" has no registered ABAC policy — falling ` +\n `back to the RBAC grant alone (strictPolicies: false), so any holder of \"${permission}\" can ` +\n `act on ANY resource. If this permission is meant to be resource-scoped, register a policy ` +\n `with definePolicy(\"${permission}\", ...) (and confirm the module that calls it is ` +\n `imported), or remove strictPolicies: false to deny by default.`,\n );\n }\n\n return strict;\n}\n\n/**\n * The core decision: does the user hold `permission`, and — when a `resource`\n * is supplied — does its policy pass too?\n *\n * Fails CLOSED: any error while resolving the decision denies (and logs). An\n * instance-level check for a permission with no registered policy also fails\n * CLOSED by default ({@link AccessConfigurations.strictPolicies}) rather than\n * falling back to the RBAC grant alone.\n */\nexport async function check(\n user: Auth,\n permission: string,\n context: AccessContext = {},\n): Promise<boolean> {\n try {\n const tenant = tenantFor(user, context);\n const permissions = await permissionsFor(user, tenant);\n\n if (!matchesPermission(permissions, permission)) return false;\n\n const policy = getPolicy(permission);\n\n // A policy only runs on an instance check (a resource was supplied);\n // class-level checks (`gate`) stop at the grant.\n if (context.resource !== undefined && policy === undefined) {\n if (unpolicedShouldDeny(permission)) return false;\n }\n\n if (policy === undefined || context.resource === undefined) return true;\n\n const roles = await rolesFor(user, tenant);\n\n return Boolean(\n await policy(user, context.resource, {\n ...context,\n tenant,\n hasRole: (role) => roles.includes(role),\n hasPermission: (perm) => matchesPermission(permissions, perm),\n }),\n );\n } catch (error) {\n if (error instanceof AccessConfigError) throw error; // misconfig is loud, not a silent deny\n\n log.error(\"access\", \"check\", error);\n\n return false;\n }\n}\n"],"mappings":";;;;;;;;;AAUA,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;;;;;;AAOA,SAAgB,eAAe,MAAY,QAAoC;CAC7E,MAAM,MAAM,SAAS,oBAAoB,MAAM,MAAM;CAErD,OAAO,eAAe,MAAM,WAC1B,OAAO,WAAW,aAAa,SAAS,CAAC,CAAC,mBAAmB,MAAM,MAAM,CAAC,CAC5E;AACF;;AAGA,SAAgB,SAAS,MAAY,QAAoC;CACvE,MAAM,MAAM,SAAS,cAAc,MAAM,MAAM;CAE/C,OAAO,eAAe,MAAM,WAC1B,OAAO,WAAW,aAAa,SAAS,CAAC,CAAC,aAAa,MAAM,MAAM,CAAC,CACtE;AACF;;;;;;AAOA,SAAS,eAAe,MAAY,QAA4C;CAC9E,IAAI,WAAW,QAAW,OAAO,CAAC,MAAM;CAExC,IAAI;CAEJ,IAAI;EACF,UAAU,aAAa,OAAO,IAAI;CACpC,QAAQ;EACN,UAAU;CACZ;CAEA,OAAO,YAAY,SAAY,CAAC,MAAS,IAAI,CAAC,SAAS,MAAS;AAClE;;;;;;AAOA,eAAsB,MAAM,MAAY,QAAgC;CACtE,IAAI;EACF,KAAK,MAAM,UAAU,eAAe,MAAM,MAAM,GAAG;GACjD,MAAM,MAAM,OAAO,SAAS,oBAAoB,MAAM,MAAM,CAAC;GAC7D,MAAM,MAAM,OAAO,SAAS,cAAc,MAAM,MAAM,CAAC;EACzD;CACF,SAAS,OAAO;EACd,IAAI,MAAM,UAAU,SAAS,KAAK;CACpC,UAAU;EAER,yBAAyB;CAC3B;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"}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
//#region ../../packages/access/src/services/resolution-memo.ts
|
|
2
|
+
/**
|
|
3
|
+
* How long a resolved set is reused for the same user object. Long enough to
|
|
4
|
+
* cover one request's stacked gates and `can()` calls, short enough that a
|
|
5
|
+
* long-lived user object (a worker, a test fixture) never holds a set much
|
|
6
|
+
* longer than the shared cache would.
|
|
7
|
+
*/
|
|
8
|
+
const MEMO_MAX_AGE_MS = 1e3;
|
|
9
|
+
/** Resolved sets per user object; an entry dies with the object it belongs to. */
|
|
10
|
+
const memos = /* @__PURE__ */ new WeakMap();
|
|
11
|
+
/**
|
|
12
|
+
* Bumped by {@link invalidateResolutionMemo}: every entry from an older
|
|
13
|
+
* generation is ignored, so `flush()` and a new configuration take effect at
|
|
14
|
+
* once for every user object in this process.
|
|
15
|
+
*/
|
|
16
|
+
let generation = 0;
|
|
17
|
+
/** Drop every memoised set in this process. */
|
|
18
|
+
function invalidateResolutionMemo() {
|
|
19
|
+
generation++;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Resolve `key` for `user` once and share the promise with every check on the
|
|
23
|
+
* same user object for {@link MEMO_MAX_AGE_MS}. A rejected load is never
|
|
24
|
+
* reused, so a failed resolution is retried on the next check.
|
|
25
|
+
*/
|
|
26
|
+
function memoizeForUser(user, key, load) {
|
|
27
|
+
if (typeof user !== "object" || user === null) return load();
|
|
28
|
+
let entries = memos.get(user);
|
|
29
|
+
if (!entries) {
|
|
30
|
+
entries = /* @__PURE__ */ new Map();
|
|
31
|
+
memos.set(user, entries);
|
|
32
|
+
}
|
|
33
|
+
const now = Date.now();
|
|
34
|
+
const hit = entries.get(key);
|
|
35
|
+
if (hit && hit.generation === generation && now - hit.at < MEMO_MAX_AGE_MS) return hit.value;
|
|
36
|
+
const value = load();
|
|
37
|
+
const owner = entries;
|
|
38
|
+
owner.set(key, {
|
|
39
|
+
value,
|
|
40
|
+
at: now,
|
|
41
|
+
generation
|
|
42
|
+
});
|
|
43
|
+
value.catch(() => {
|
|
44
|
+
if (owner.get(key)?.value === value) owner.delete(key);
|
|
45
|
+
});
|
|
46
|
+
return value;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
//#endregion
|
|
50
|
+
export { invalidateResolutionMemo, memoizeForUser };
|
|
51
|
+
//# sourceMappingURL=resolution-memo.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolution-memo.mjs","names":[],"sources":["../../../../../../../../packages/access/src/services/resolution-memo.ts"],"sourcesContent":["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"],"mappings":";;;;;;;AAQA,MAAM,kBAAkB;;AAKxB,MAAM,wBAAQ,IAAI,QAAwC;;;;;;AAO1D,IAAI,aAAa;;AAGjB,SAAgB,2BAAiC;CAC/C;AACF;;;;;;AAOA,SAAgB,eACd,MACA,KACA,MACmB;CACnB,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM,OAAO,KAAK;CAE3D,IAAI,UAAU,MAAM,IAAI,IAAI;CAE5B,IAAI,CAAC,SAAS;EACZ,0BAAU,IAAI,IAAI;EAClB,MAAM,IAAI,MAAM,OAAO;CACzB;CAEA,MAAM,MAAM,KAAK,IAAI;CACrB,MAAM,MAAM,QAAQ,IAAI,GAAG;CAE3B,IAAI,OAAO,IAAI,eAAe,cAAc,MAAM,IAAI,KAAK,iBACzD,OAAO,IAAI;CAGb,MAAM,QAAQ,KAAK;CACnB,MAAM,QAAQ;CAEd,MAAM,IAAI,KAAK;EAAE;EAAO,IAAI;EAAK;CAAW,CAAC;CAE7C,MAAM,YAAY;EAChB,IAAI,MAAM,IAAI,GAAG,CAAC,EAAE,UAAU,OAAO,MAAM,OAAO,GAAG;CACvD,CAAC;CAED,OAAO;AACT"}
|
package/llms-full.txt
CHANGED
|
@@ -127,6 +127,7 @@ await authorize(user, "orders.update", { resource: order, tenant }); // grant AN
|
|
|
127
127
|
|
|
128
128
|
## Gotchas
|
|
129
129
|
|
|
130
|
+
- **One resolution per user object per request.** Checks on the same user object share the resolved permission/role set for up to one second, so stacked `gate()`s and `canAll` / `canAny` read the cache once. `access.flush` drops the shared sets immediately.
|
|
130
131
|
- **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).
|
|
131
132
|
- Stack `gate` **after** `authMiddleware` — it reads `request.locals.user`; without an authenticated user it `403`s.
|
|
132
133
|
- The boolean `can*` family never throws; the `authorize*` family throws `ForbiddenError`. Pick per layer (controllers gate with middleware, services assert with `authorize`).
|
|
@@ -455,6 +456,8 @@ await access.flush(user, "tenant-1");
|
|
|
455
456
|
await access.flush(user, "tenant-1");
|
|
456
457
|
```
|
|
457
458
|
|
|
459
|
+
Without a `tenant`, `access.flush(user)` drops the set for the resolver's ambient tenant (`resolveTenant(user)`, what `can(user, …)` reads) plus the no-tenant set. On the memory cache driver a flush only reaches the process that runs it — use redis/pg with more than one instance.
|
|
460
|
+
|
|
458
461
|
`access.flush(user, tenant)` is per-user — it has no "drop everything" form. For a sweeping catalog change with many holders, flush each affected user, or let the entries expire on their own (`cache.ttl`, default `10m`).
|
|
459
462
|
|
|
460
463
|
## Read roles
|
package/package.json
CHANGED
|
@@ -5,12 +5,12 @@
|
|
|
5
5
|
"environment": "server"
|
|
6
6
|
},
|
|
7
7
|
"peerDependencies": {
|
|
8
|
-
"@warlock.js/auth": "5.
|
|
9
|
-
"@warlock.js/cache": "5.
|
|
10
|
-
"@warlock.js/cascade": "5.
|
|
11
|
-
"@warlock.js/core": "5.
|
|
12
|
-
"@warlock.js/logger": "5.
|
|
13
|
-
"@warlock.js/seal": "5.
|
|
8
|
+
"@warlock.js/auth": "5.53.1",
|
|
9
|
+
"@warlock.js/cache": "5.53.1",
|
|
10
|
+
"@warlock.js/cascade": "5.53.1",
|
|
11
|
+
"@warlock.js/core": "5.53.1",
|
|
12
|
+
"@warlock.js/logger": "5.53.1",
|
|
13
|
+
"@warlock.js/seal": "5.53.1"
|
|
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.
|
|
31
|
+
"version": "5.53.1",
|
|
32
32
|
"main": "./cjs/index.cjs",
|
|
33
33
|
"module": "./esm/index.mjs",
|
|
34
34
|
"types": "./esm/index.d.mts",
|
|
@@ -63,6 +63,7 @@ await authorize(user, "orders.update", { resource: order, tenant }); // grant AN
|
|
|
63
63
|
|
|
64
64
|
## Gotchas
|
|
65
65
|
|
|
66
|
+
- **One resolution per user object per request.** Checks on the same user object share the resolved permission/role set for up to one second, so stacked `gate()`s and `canAll` / `canAny` read the cache once. `access.flush` drops the shared sets immediately.
|
|
66
67
|
- **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).
|
|
67
68
|
- Stack `gate` **after** `authMiddleware` — it reads `request.locals.user`; without an authenticated user it `403`s.
|
|
68
69
|
- The boolean `can*` family never throws; the `authorize*` family throws `ForbiddenError`. Pick per layer (controllers gate with middleware, services assert with `authorize`).
|
|
@@ -38,6 +38,8 @@ await access.flush(user, "tenant-1");
|
|
|
38
38
|
await access.flush(user, "tenant-1");
|
|
39
39
|
```
|
|
40
40
|
|
|
41
|
+
Without a `tenant`, `access.flush(user)` drops the set for the resolver's ambient tenant (`resolveTenant(user)`, what `can(user, …)` reads) plus the no-tenant set. On the memory cache driver a flush only reaches the process that runs it — use redis/pg with more than one instance.
|
|
42
|
+
|
|
41
43
|
`access.flush(user, tenant)` is per-user — it has no "drop everything" form. For a sweeping catalog change with many holders, flush each affected user, or let the entries expire on their own (`cache.ttl`, default `10m`).
|
|
42
44
|
|
|
43
45
|
## Read roles
|