@plakboek/permissions 0.1.0

package/dist/index.js

@@ -0,0 +1,864 @@
+//#region src/catalogue.ts
+/**
+* The frozen v1 permission catalogue (D-07). Every catalogue entry uses
+* `resource:action` strings with no ownership split (D-05); publishing is
+* its own permission, separate from editing (D-06).
+*/
+const PERMISSIONS = {
+	"pages:read": {
+		group: "pages",
+		label: {
+			id: "permissions.pages.read.label",
+			message: "View pages"
+		},
+		description: {
+			id: "permissions.pages.read.description",
+			message: "See pages and their published content in the admin"
+		}
+	},
+	"pages:read-drafts": {
+		group: "pages",
+		label: {
+			id: "permissions.pages.readDrafts.label",
+			message: "View page drafts"
+		},
+		description: {
+			id: "permissions.pages.readDrafts.description",
+			message: "See unpublished drafts, previews and revision history of pages"
+		}
+	},
+	"pages:create": {
+		group: "pages",
+		label: {
+			id: "permissions.pages.create.label",
+			message: "Create pages"
+		},
+		description: {
+			id: "permissions.pages.create.description",
+			message: "Add new pages to the site"
+		}
+	},
+	"pages:edit": {
+		group: "pages",
+		label: {
+			id: "permissions.pages.edit.label",
+			message: "Edit pages"
+		},
+		description: {
+			id: "permissions.pages.edit.description",
+			message: "Change page content, blocks, layout, SEO fields and translations as drafts"
+		}
+	},
+	"pages:publish": {
+		group: "pages",
+		label: {
+			id: "permissions.pages.publish.label",
+			message: "Publish pages"
+		},
+		description: {
+			id: "permissions.pages.publish.description",
+			message: "Publish or schedule page drafts so visitors receive them"
+		}
+	},
+	"pages:delete": {
+		group: "pages",
+		label: {
+			id: "permissions.pages.delete.label",
+			message: "Delete pages"
+		},
+		description: {
+			id: "permissions.pages.delete.description",
+			message: "Move pages to the trash and restore them"
+		}
+	},
+	"pages:delete-permanent": {
+		group: "pages",
+		label: {
+			id: "permissions.pages.deletePermanent.label",
+			message: "Permanently delete pages"
+		},
+		description: {
+			id: "permissions.pages.deletePermanent.description",
+			message: "Permanently remove trashed pages"
+		}
+	},
+	"entries:read": {
+		group: "entries",
+		label: {
+			id: "permissions.entries.read.label",
+			message: "View entries"
+		},
+		description: {
+			id: "permissions.entries.read.description",
+			message: "See content entries and their published content in the admin"
+		}
+	},
+	"entries:read-drafts": {
+		group: "entries",
+		label: {
+			id: "permissions.entries.readDrafts.label",
+			message: "View entry drafts"
+		},
+		description: {
+			id: "permissions.entries.readDrafts.description",
+			message: "See unpublished drafts, previews and revision history of entries"
+		}
+	},
+	"entries:create": {
+		group: "entries",
+		label: {
+			id: "permissions.entries.create.label",
+			message: "Create entries"
+		},
+		description: {
+			id: "permissions.entries.create.description",
+			message: "Add new content entries"
+		}
+	},
+	"entries:edit": {
+		group: "entries",
+		label: {
+			id: "permissions.entries.edit.label",
+			message: "Edit entries"
+		},
+		description: {
+			id: "permissions.entries.edit.description",
+			message: "Change entry fields and translations as drafts"
+		}
+	},
+	"entries:publish": {
+		group: "entries",
+		label: {
+			id: "permissions.entries.publish.label",
+			message: "Publish entries"
+		},
+		description: {
+			id: "permissions.entries.publish.description",
+			message: "Publish or schedule entry drafts so visitors receive them"
+		}
+	},
+	"entries:delete": {
+		group: "entries",
+		label: {
+			id: "permissions.entries.delete.label",
+			message: "Delete entries"
+		},
+		description: {
+			id: "permissions.entries.delete.description",
+			message: "Move entries to the trash and restore them"
+		}
+	},
+	"entries:delete-permanent": {
+		group: "entries",
+		label: {
+			id: "permissions.entries.deletePermanent.label",
+			message: "Permanently delete entries"
+		},
+		description: {
+			id: "permissions.entries.deletePermanent.description",
+			message: "Permanently remove trashed entries"
+		}
+	},
+	"templates:edit": {
+		group: "templates",
+		label: {
+			id: "permissions.templates.edit.label",
+			message: "Edit detail templates"
+		},
+		description: {
+			id: "permissions.templates.edit.description",
+			message: "Change the shared block tree used to render a content type's detail pages"
+		}
+	},
+	"templates:publish": {
+		group: "templates",
+		label: {
+			id: "permissions.templates.publish.label",
+			message: "Publish detail templates"
+		},
+		description: {
+			id: "permissions.templates.publish.description",
+			message: "Publish changes to shared detail templates"
+		}
+	},
+	"content-types:read": {
+		group: "content-types",
+		label: {
+			id: "permissions.contentTypes.read.label",
+			message: "View content types"
+		},
+		description: {
+			id: "permissions.contentTypes.read.description",
+			message: "See content types and the fields attached to them"
+		}
+	},
+	"content-types:create": {
+		group: "content-types",
+		label: {
+			id: "permissions.contentTypes.create.label",
+			message: "Create content types"
+		},
+		description: {
+			id: "permissions.contentTypes.create.description",
+			message: "Add new content types"
+		}
+	},
+	"content-types:edit": {
+		group: "content-types",
+		label: {
+			id: "permissions.contentTypes.edit.label",
+			message: "Edit content types"
+		},
+		description: {
+			id: "permissions.contentTypes.edit.description",
+			message: "Change content type settings and add, change or remove fields"
+		}
+	},
+	"content-types:delete": {
+		group: "content-types",
+		label: {
+			id: "permissions.contentTypes.delete.label",
+			message: "Delete content types"
+		},
+		description: {
+			id: "permissions.contentTypes.delete.description",
+			message: "Remove content types"
+		}
+	},
+	"media:read": {
+		group: "media",
+		label: {
+			id: "permissions.media.read.label",
+			message: "View media"
+		},
+		description: {
+			id: "permissions.media.read.description",
+			message: "Browse and search the media library"
+		}
+	},
+	"media:upload": {
+		group: "media",
+		label: {
+			id: "permissions.media.upload.label",
+			message: "Upload media"
+		},
+		description: {
+			id: "permissions.media.upload.description",
+			message: "Upload images and files"
+		}
+	},
+	"media:edit": {
+		group: "media",
+		label: {
+			id: "permissions.media.edit.label",
+			message: "Edit media"
+		},
+		description: {
+			id: "permissions.media.edit.description",
+			message: "Change alt text, copyright labels and replace assets in place"
+		}
+	},
+	"media:delete": {
+		group: "media",
+		label: {
+			id: "permissions.media.delete.label",
+			message: "Delete media"
+		},
+		description: {
+			id: "permissions.media.delete.description",
+			message: "Delete assets, including ones still in use after a warning"
+		}
+	},
+	"menus:read": {
+		group: "menus",
+		label: {
+			id: "permissions.menus.read.label",
+			message: "View menus"
+		},
+		description: {
+			id: "permissions.menus.read.description",
+			message: "See menus declared by the site and their links"
+		}
+	},
+	"menus:edit": {
+		group: "menus",
+		label: {
+			id: "permissions.menus.edit.label",
+			message: "Edit menus"
+		},
+		description: {
+			id: "permissions.menus.edit.description",
+			message: "Add, remove and re-arrange menu links"
+		}
+	},
+	"redirects:read": {
+		group: "seo",
+		label: {
+			id: "permissions.redirects.read.label",
+			message: "View redirects"
+		},
+		description: {
+			id: "permissions.redirects.read.description",
+			message: "See redirects and how long each has been active"
+		}
+	},
+	"redirects:manage": {
+		group: "seo",
+		label: {
+			id: "permissions.redirects.manage.label",
+			message: "Manage redirects"
+		},
+		description: {
+			id: "permissions.redirects.manage.description",
+			message: "Create, change and remove redirects"
+		}
+	},
+	"users:read": {
+		group: "users",
+		label: {
+			id: "permissions.users.read.label",
+			message: "View users"
+		},
+		description: {
+			id: "permissions.users.read.description",
+			message: "See users and their roles"
+		}
+	},
+	"users:create": {
+		group: "users",
+		label: {
+			id: "permissions.users.create.label",
+			message: "Invite users"
+		},
+		description: {
+			id: "permissions.users.create.description",
+			message: "Add users and send or resend set-password emails"
+		}
+	},
+	"users:edit": {
+		group: "users",
+		label: {
+			id: "permissions.users.edit.label",
+			message: "Edit users"
+		},
+		description: {
+			id: "permissions.users.edit.description",
+			message: "Change other users' profile details"
+		}
+	},
+	"users:deactivate": {
+		group: "users",
+		label: {
+			id: "permissions.users.deactivate.label",
+			message: "Deactivate users"
+		},
+		description: {
+			id: "permissions.users.deactivate.description",
+			message: "Deactivate and reactivate users"
+		}
+	},
+	"users:assign-roles": {
+		group: "users",
+		label: {
+			id: "permissions.users.assignRoles.label",
+			message: "Assign roles"
+		},
+		description: {
+			id: "permissions.users.assignRoles.description",
+			message: "Assign a code-defined role to a user"
+		}
+	},
+	"users:reset-password": {
+		group: "users",
+		label: {
+			id: "permissions.users.resetPassword.label",
+			message: "Reset passwords"
+		},
+		description: {
+			id: "permissions.users.resetPassword.description",
+			message: "Set or reset another user's password"
+		}
+	},
+	"users:impersonate": {
+		group: "users",
+		label: {
+			id: "permissions.users.impersonate.label",
+			message: "Impersonate users"
+		},
+		description: {
+			id: "permissions.users.impersonate.description",
+			message: "Act as another user and return to your own session"
+		}
+	},
+	"audit-log:read": {
+		group: "audit",
+		label: {
+			id: "permissions.auditLog.read.label",
+			message: "View audit log"
+		},
+		description: {
+			id: "permissions.auditLog.read.description",
+			message: "See the audit log of data-changing actions"
+		}
+	},
+	"settings:read": {
+		group: "settings",
+		label: {
+			id: "permissions.settings.read.label",
+			message: "View settings"
+		},
+		description: {
+			id: "permissions.settings.read.description",
+			message: "See installation settings"
+		}
+	},
+	"settings:manage": {
+		group: "settings",
+		label: {
+			id: "permissions.settings.manage.label",
+			message: "Manage settings"
+		},
+		description: {
+			id: "permissions.settings.manage.description",
+			message: "Change core configuration, styles and rules"
+		}
+	},
+	"modules:manage": {
+		group: "settings",
+		label: {
+			id: "permissions.modules.manage.label",
+			message: "Manage modules"
+		},
+		description: {
+			id: "permissions.modules.manage.description",
+			message: "Turn installation modules on or off"
+		}
+	},
+	"blocks:manage": {
+		group: "settings",
+		label: {
+			id: "permissions.blocks.manage.label",
+			message: "Manage built-in blocks"
+		},
+		description: {
+			id: "permissions.blocks.manage.description",
+			message: "Turn individual built-in sections and blocks on or off"
+		}
+	},
+	"bootstrap:run": {
+		group: "settings",
+		label: {
+			id: "permissions.bootstrap.run.label",
+			message: "Run bootstrap"
+		},
+		description: {
+			id: "permissions.bootstrap.run.description",
+			message: "Run installation bootstrap steps"
+		}
+	},
+	"api-tokens:create": {
+		group: "api",
+		label: {
+			id: "permissions.apiTokens.create.label",
+			message: "Create API tokens"
+		},
+		description: {
+			id: "permissions.apiTokens.create.description",
+			message: "Create and revoke your own API tokens for MCP clients"
+		}
+	},
+	"api-tokens:manage": {
+		group: "api",
+		label: {
+			id: "permissions.apiTokens.manage.label",
+			message: "Manage API tokens"
+		},
+		description: {
+			id: "permissions.apiTokens.manage.description",
+			message: "See and revoke any user's API tokens"
+		}
+	},
+	"backups:manage": {
+		group: "backups",
+		label: {
+			id: "permissions.backups.manage.label",
+			message: "Manage backups"
+		},
+		description: {
+			id: "permissions.backups.manage.description",
+			message: "Configure backup targets and run backups"
+		}
+	},
+	"backups:restore": {
+		group: "backups",
+		label: {
+			id: "permissions.backups.restore.label",
+			message: "Restore backups"
+		},
+		description: {
+			id: "permissions.backups.restore.description",
+			message: "Restore the installation from a backup"
+		}
+	}
+};
+for (const meta of Object.values(PERMISSIONS)) {
+	Object.freeze(meta.label);
+	Object.freeze(meta.description);
+	Object.freeze(meta);
+}
+Object.freeze(PERMISSIONS);
+/** Runtime type guard for an arbitrary value being a known permission string.
+* Uses `Object.hasOwn` (not `in` or bracket access) so inherited
+* `Object.prototype` keys (`constructor`, `toString`, `__proto__`, ...) are
+* never classified as permissions (T-01-08). */
+function isPermission(value) {
+	return typeof value === "string" && Object.hasOwn(PERMISSIONS, value);
+}
+/** Every permission string, in catalogue declaration order, frozen. */
+const ALL_PERMISSIONS = Object.freeze(Object.keys(PERMISSIONS).filter(isPermission));
+/** The 12 v1 permission groups, in catalogue table order, frozen. */
+const PERMISSION_GROUPS = Object.freeze([
+	"pages",
+	"entries",
+	"templates",
+	"content-types",
+	"media",
+	"menus",
+	"seo",
+	"users",
+	"audit",
+	"settings",
+	"api",
+	"backups"
+]);
+//#endregion
+//#region src/deprecated.ts
+/**
+* D-09 breaking-change policy for permission strings:
+*
+* - Adding a permission is a minor version bump.
+* - Renaming or removing a permission is a major version bump (while
+*   pre-1.0, per D-17, it is a minor bump instead) -- and the old name
+*   stays in this table, pointing at its replacement, for one major
+*   version after the rename/removal ships. Host configs that still
+*   reference the old name keep booting, with a warning (D-10); they are
+*   never rejected outright during that window.
+* - An alias key must never equal a canonical key in `PERMISSIONS`
+*   (catalogue.ts) -- a key that renames back onto itself is not a
+*   deprecation, it is a bug in this table.
+*
+* No permission has been renamed or removed since the v1 catalogue shipped
+* at 0.1.0, so this table starts empty. `DeprecatedPermission` (`keyof
+* typeof DEPRECATED_PERMISSION_ALIASES`) is therefore `never` today -- that
+* is intentional and still a literal type, not `string`: the first entry
+* added here narrows it to a real literal union, it never widens.
+*/
+const DEPRECATED_PERMISSION_ALIASES = {};
+Object.freeze(DEPRECATED_PERMISSION_ALIASES);
+/**
+* Classify an arbitrary string as a canonical permission, a deprecated
+* alias (per `aliases`, defaulting to the shipped
+* `DEPRECATED_PERMISSION_ALIASES`), or unknown.
+*
+* Checks `isPermission` first so a canonical name is never misclassified
+* as deprecated even if it were accidentally also present as an alias key.
+* Alias lookup uses `Object.hasOwn` (not `in` or bracket access), so
+* inherited `Object.prototype` keys (`__proto__`, `constructor`, ...) are
+* always classified as unknown, never as a hit (T-01-08).
+*/
+function resolvePermissionName(value, aliases = DEPRECATED_PERMISSION_ALIASES) {
+	if (isPermission(value)) return {
+		kind: "canonical",
+		permission: value
+	};
+	if (Object.hasOwn(aliases, value)) {
+		const permission = aliases[value];
+		if (permission !== void 0) return {
+			kind: "deprecated",
+			alias: value,
+			permission
+		};
+	}
+	return {
+		kind: "unknown",
+		value
+	};
+}
+//#endregion
+//#region src/roles.ts
+/**
+* Code-defined roles on top of the fixed permission catalogue (USER-03,
+* USER-04, INST-06). `defineRoles` boot-fails a host's role config the
+* moment it references an unknown permission string, is missing the
+* reserved `superadmin` role, or narrows `superadmin` below
+* `ALL_PERMISSIONS` (D-10, D-11, D-12). Hosts compose roles by spreading
+* `defaultRoles` and overriding/adding keys (D-14) -- there is no
+* inheritance, `extends`, or wildcard: a role's permissions are exactly
+* what its list contains.
+*/
+/** Thrown by `defineRoles`/`validateRoleConfig` with every problem found in
+* the config, collected before throwing once (never one-issue-at-a-time). */
+var RoleConfigError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(["[@plakboek/permissions] invalid role config:", ...issues.map((issue) => issue.message)].join("\n"));
+		this.name = "RoleConfigError";
+		this.issues = issues;
+	}
+};
+/** A role key must be lowercase-kebab: starts with a letter, then letters,
+* digits or hyphens. Rejects case variants ("Editor"), whitespace
+* (" editor"), and inherited-property-name lookalikes ("__proto__",
+* "constructor", "toString") without any special-casing -- none of those
+* match the pattern. */
+const ROLE_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+function defaultOnDeprecatedPermission(event) {
+	console.warn(`[@plakboek/permissions] role "${event.roleKey}" uses deprecated permission "${event.alias}"; rename it to "${event.permission}"`);
+}
+/** Narrows `unknown` to a plain, non-array object without an `as` cast. */
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrows `unknown` to `string[]` without an `as` cast. */
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+* Module-level validator used directly by tests (not re-exported from
+* `index.ts`). `defineRoles` calls this with the shipped deprecated-alias
+* table; tests call it directly to inject a custom alias table.
+*
+* Collects every problem before throwing once. On success, every role's
+* permissions are deduped and reordered to catalogue declaration order
+* (`ALL_PERMISSIONS` filtered by membership), then frozen; the returned
+* container object is frozen too (T-01-20).
+*/
+function validateRoleConfig(input, options) {
+	const issues = [];
+	const aliases = options?.aliases ?? DEPRECATED_PERMISSION_ALIASES;
+	const onDeprecatedPermission = options?.onDeprecatedPermission ?? defaultOnDeprecatedPermission;
+	if (!isPlainObject(input)) {
+		issues.push({
+			code: "INVALID_ROLE_CONFIG",
+			message: "role config must be a plain object mapping role keys to permission lists"
+		});
+		throw new RoleConfigError(issues);
+	}
+	const roleKeys = Object.keys(input);
+	const normalized = /* @__PURE__ */ new Map();
+	for (const roleKey of roleKeys) {
+		if (!ROLE_KEY_PATTERN.test(roleKey)) {
+			issues.push({
+				code: "INVALID_ROLE_KEY",
+				roleKey,
+				message: `role key "${roleKey}" must match ${ROLE_KEY_PATTERN.source}`
+			});
+			continue;
+		}
+		const rawList = input[roleKey];
+		if (!isStringArray(rawList)) {
+			issues.push({
+				code: "INVALID_PERMISSION_LIST",
+				roleKey,
+				message: `role "${roleKey}" must be an array of permission strings`
+			});
+			continue;
+		}
+		const resolvedPermissions = [];
+		for (const value of rawList) {
+			const resolution = resolvePermissionName(value, aliases);
+			if (resolution.kind === "canonical") resolvedPermissions.push(resolution.permission);
+			else if (resolution.kind === "deprecated") {
+				resolvedPermissions.push(resolution.permission);
+				onDeprecatedPermission({
+					roleKey,
+					alias: resolution.alias,
+					permission: resolution.permission
+				});
+			} else issues.push({
+				code: "UNKNOWN_PERMISSION",
+				roleKey,
+				value,
+				message: `role "${roleKey}" references unknown permission "${value}"`
+			});
+		}
+		normalized.set(roleKey, resolvedPermissions);
+	}
+	if (!Object.hasOwn(input, "superadmin")) issues.push({
+		code: "MISSING_SUPERADMIN",
+		message: "role config must define a \"superadmin\" role holding ALL_PERMISSIONS"
+	});
+	else {
+		const superadminPermissions = normalized.get("superadmin");
+		if (superadminPermissions !== void 0) {
+			const superadminSet = new Set(superadminPermissions);
+			if (!(superadminSet.size === ALL_PERMISSIONS.length && ALL_PERMISSIONS.every((permission) => superadminSet.has(permission)))) issues.push({
+				code: "SUPERADMIN_NOT_ALL_PERMISSIONS",
+				roleKey: "superadmin",
+				message: "role \"superadmin\" must hold exactly ALL_PERMISSIONS -- use `superadmin: ALL_PERMISSIONS`"
+			});
+		}
+	}
+	if (issues.length > 0) throw new RoleConfigError(issues);
+	const result = {};
+	for (const roleKey of roleKeys) {
+		const resolved = normalized.get(roleKey);
+		if (resolved === void 0) continue;
+		const memberSet = new Set(resolved);
+		result[roleKey] = Object.freeze(ALL_PERMISSIONS.filter((permission) => memberSet.has(permission)));
+	}
+	return Object.freeze(result);
+}
+/**
+* Validate and normalize a host's role config. Throws a single
+* `RoleConfigError` listing every problem found; on success, returns a
+* frozen, deduped, catalogue-ordered permission map per role.
+*/
+function defineRoles(roles, options) {
+	return validateRoleConfig(roles, options);
+}
+/**
+* The shipped `superadmin`/`admin`/`editor` role set (D-13). Works with
+* zero customisation (USER-04); hosts compose via
+* `defineRoles({ ...defaultRoles, client: [...] })` (D-14).
+*/
+const defaultRoles = {
+	superadmin: ALL_PERMISSIONS,
+	admin: [
+		"pages:read",
+		"pages:read-drafts",
+		"pages:create",
+		"pages:edit",
+		"pages:publish",
+		"pages:delete",
+		"entries:read",
+		"entries:read-drafts",
+		"entries:create",
+		"entries:edit",
+		"entries:publish",
+		"entries:delete",
+		"templates:edit",
+		"templates:publish",
+		"content-types:read",
+		"content-types:create",
+		"content-types:edit",
+		"content-types:delete",
+		"media:read",
+		"media:upload",
+		"media:edit",
+		"media:delete",
+		"menus:read",
+		"menus:edit",
+		"redirects:read",
+		"redirects:manage",
+		"users:read",
+		"users:create",
+		"users:edit",
+		"users:deactivate",
+		"users:assign-roles",
+		"users:reset-password",
+		"audit-log:read",
+		"settings:read",
+		"settings:manage",
+		"api-tokens:create",
+		"api-tokens:manage"
+	],
+	editor: [
+		"pages:read",
+		"pages:read-drafts",
+		"pages:create",
+		"pages:edit",
+		"pages:publish",
+		"pages:delete",
+		"entries:read",
+		"entries:read-drafts",
+		"entries:create",
+		"entries:edit",
+		"entries:publish",
+		"entries:delete",
+		"templates:edit",
+		"templates:publish",
+		"content-types:read",
+		"media:read",
+		"media:upload",
+		"media:edit",
+		"menus:read",
+		"menus:edit",
+		"redirects:read",
+		"api-tokens:create"
+	]
+};
+Object.freeze(defaultRoles.admin);
+Object.freeze(defaultRoles.editor);
+Object.freeze(defaultRoles);
+//#endregion
+//#region src/resolve.ts
+const DEFAULT_RATE_LIMIT_MS = 6e4;
+/** Cap on distinct orphaned role keys tracked for rate limiting (T-01-22) --
+* without it, an attacker (or a persistently misconfigured client) sending
+* arbitrarily many distinct bogus role keys could grow this state without
+* bound. The oldest-inserted key is evicted to make room for a new one. */
+const MAX_TRACKED_KEYS = 1e3;
+function defaultOnOrphanedRole(event) {
+	const userPart = event.userId !== void 0 ? ` (user ${event.userId})` : "";
+	console.warn(`[@plakboek/permissions] orphaned role key "${event.roleKey}"${userPart} -- denying all permissions`);
+}
+/**
+* Build a resolver over a validated role map (the output of `defineRoles`).
+* `resolve` never throws: an unknown role key returns an empty set and
+* reports the orphan through `onOrphanedRole` (default `console.warn`),
+* rate-limited independently per key.
+*/
+function createPermissionResolver(roles, options) {
+	const roleMap = new Map(Object.entries(roles));
+	const rateLimitMs = options?.rateLimitMs ?? DEFAULT_RATE_LIMIT_MS;
+	const now = options?.now ?? Date.now;
+	const hook = options?.onOrphanedRole ?? defaultOnOrphanedRole;
+	const orphanState = /* @__PURE__ */ new Map();
+	function isKnownRole(roleKey) {
+		return roleMap.has(roleKey);
+	}
+	function emitOrphanedRoleEvent(roleKey, userId) {
+		const nowMs = now();
+		const state = orphanState.get(roleKey);
+		if (state !== void 0 && nowMs - state.lastEmittedAt < rateLimitMs) {
+			state.suppressed += 1;
+			return;
+		}
+		const suppressedCount = state?.suppressed ?? 0;
+		if (state === void 0 && orphanState.size >= MAX_TRACKED_KEYS) {
+			const oldestKey = orphanState.keys().next().value;
+			if (oldestKey !== void 0) orphanState.delete(oldestKey);
+		}
+		orphanState.set(roleKey, {
+			lastEmittedAt: nowMs,
+			suppressed: 0
+		});
+		const event = {
+			roleKey,
+			...userId !== void 0 ? { userId } : {},
+			occurredAt: new Date(nowMs),
+			suppressedCount
+		};
+		try {
+			hook(event);
+		} catch (error) {
+			try {
+				console.error(`[@plakboek/permissions] onOrphanedRole hook threw while handling role "${roleKey}"`, error);
+			} catch {}
+		}
+	}
+	function resolve(roleKeyInput, context) {
+		const roleKey = String(roleKeyInput);
+		const known = roleMap.get(roleKey);
+		if (known !== void 0) return new Set(known);
+		emitOrphanedRoleEvent(roleKey, context?.userId);
+		return /* @__PURE__ */ new Set();
+	}
+	return {
+		resolve,
+		isKnownRole
+	};
+}
+//#endregion
+export { ALL_PERMISSIONS, DEPRECATED_PERMISSION_ALIASES, PERMISSIONS, PERMISSION_GROUPS, RoleConfigError, createPermissionResolver, defaultRoles, defineRoles, isPermission, resolvePermissionName };