@murumets-ee/admin-route 0.37.0

package/dist/index.d.mts

@@ -0,0 +1,998 @@
+//#region src/admin-route.d.ts
+/**
+ * Types for the admin API plugin route system.
+ *
+ * Defined in `@murumets-ee/admin-route` — a dependency-free leaf (F020,
+ * F024) — so that every package, including ones that structurally cannot
+ * depend on `@murumets-ee/core` (e.g. `@murumets-ee/logging`; `core`
+ * imports `logging`, so the reverse edge would close a cycle), can import
+ * these types without circular dependencies.
+ *
+ * `@murumets-ee/core` re-exports these from its own barrel, binding the
+ * `TApp` generic below to the real `ToolkitApp` (see `packages/core/src/
+ * admin-route.ts`) so existing consumers see the exact same shape they
+ * always have — this file itself must stay dependency-free and cannot
+ * name `ToolkitApp`.
+ */
+/**
+ * The nominal gating brand carried by every legitimately-minted
+ * {@link AdminRoute} (`plan/admin-api-hardening/` PR 3, SD002).
+ *
+ * ## Why this exists
+ *
+ * An `AdminRoute` used to be a plain structural shape — `{ prefix,
+ * handlers }` — so ANY object literal satisfied it, including one whose
+ * handlers perform no permission check at all. That is the exact defect
+ * class this plan exists to close: PR 2 proved every route is *currently*
+ * gated; this brand makes an ungated one impossible to construct.
+ *
+ * `combineAdminRoutes` is the SOLE minter, and it accepts ONLY
+ * `defineAdminRoute` outputs — `AdminRouteEntry` carries its own brand
+ * (`ENTRY_GATED`, `define-admin-route.ts`) which the combiner requires at
+ * both the type level and, fail-closed, at runtime. Since
+ * `defineAdminRoute` requires a `permission`, "carries the brand"
+ * transitively means "went through a permission gate".
+ *
+ * That transitivity used to be an unchecked assumption, and it was FALSE:
+ * `AdminRouteEntry` was a purely structural, publicly exported shape, so
+ * a hand-written literal (with any `guardedHandler` at all, or none) fed
+ * to `combineAdminRoutes` produced a genuinely branded `AdminRoute` that
+ * passed {@link isGatedRoute} and served every request under its prefix
+ * ungated. Finding H1 of PR 3 closed that by branding the entry too; see
+ * `ENTRY_GATED`'s doc comment for the full account.
+ *
+ * ## Threat model — be precise about what this does and does not stop
+ *
+ * These layers defend against **author error and `as` casts**: a route
+ * declared without a gate, by someone who did not realise one was needed.
+ * That is the failure mode this plan actually observed, four times over.
+ *
+ * They do NOT defend against hostile code already running in the server
+ * process. Symbols are not capabilities: anything holding a legitimately
+ * minted route can read the key off it via `Object.getOwnPropertySymbols`
+ * and stamp a forgery. That is not a weakness worth closing — a malicious
+ * plugin has arbitrary in-process execution and does not need a forged
+ * route to do harm — but do not mistake {@link isGatedRoute} for a
+ * sandbox, and do not let it become the justification for loading
+ * untrusted plugin code.
+ *
+ * ## Why a real `Symbol()`, not a `declare const` phantom
+ *
+ * `@murumets-ee/blocks` brands `BlockRenderer` with a `declare const`
+ * (`BLOCK_RENDER_BRAND`, `packages/blocks/src/core/define-theme.ts`) — a
+ * pure type-level phantom that is erased at compile time. That is not
+ * enough here. Types are erased and a plain-JS plugin never runs `tsc` at
+ * all, so the brand alone is *author ergonomics*; the runtime guarantee is
+ * {@link isGatedRoute}, checked fail-closed where routes are collected
+ * (`getRouteMap` in `@murumets-ee/admin-ui`). A phantom brand would leave
+ * that check nothing to read. SD002 locked "defense in depth, not
+ * either/or" for exactly this reason (OWASP: no single control should be
+ * the sole enforcement).
+ *
+ * ## Why `unique symbol`, and why it is not exported from the barrel
+ *
+ * `GATED` is exported from THIS MODULE (so `define-admin-route.ts`'s
+ * minter can name the key with no cast) but deliberately NOT re-exported
+ * from `src/index.ts`, and the package's `exports` map has no deep paths.
+ * No code outside this package can name the key, so an ungated object
+ * literal is a compile error at the boundary. A `unique symbol` is what
+ * makes that airtight: a same-named `Symbol('lumi.admin-route.gated')`
+ * declared elsewhere is a DIFFERENT `unique symbol` type and does not
+ * satisfy the property — where a string-literal brand would be trivially
+ * forgeable.
+ *
+ * ## Why it is set as a plain, enumerable own property
+ *
+ * The minter assigns it in the object literal rather than via
+ * `Object.defineProperty(..., { enumerable: false })`. It MUST survive
+ * object spread (`{ ...route }`), or a route the compiler blessed would
+ * lose its brand at runtime and {@link isGatedRoute} would reject it —
+ * layer 3 refusing something layer 2 approved. Symbol keys are already
+ * excluded from `Object.keys`, `for…in` and `JSON.stringify`, so leaving
+ * it enumerable costs nothing in serialization noise.
+ *
+ * ## Module-instance caveat
+ *
+ * Symbol identity is per module instance. Every package that mints routes
+ * and the one package that checks them (`admin-ui`) all resolve the same
+ * `@murumets-ee/admin-route` (single workspace symlink; a single hoisted
+ * version once published, since `@murumets-ee/*` is one fixed changeset
+ * group), so there is exactly one `GATED`. `Symbol.for()` would survive
+ * module duplication but lives in the cross-realm global registry, where
+ * any code could re-derive the key — trading the forgery guarantee for a
+ * hazard that does not exist here. If duplication ever did occur the
+ * failure is loud and fail-safe: every route logs an error and 404s,
+ * rather than silently registering ungated.
+ */
+declare const GATED: unique symbol;
+/** Authenticated user returned by the handler's authenticate callback. */
+interface AuthUser {
+  id: string;
+  role?: string;
+  name?: string;
+  email?: string;
+}
+/** Fire-and-forget audit log function passed to plugin route handlers. */
+type AuditLogFn = (entry: {
+  action: string;
+  entityType?: string;
+  entityId?: string;
+  userId?: string;
+  userName?: string;
+  changes?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}) => void;
+/**
+ * Synchronous permission checker — `(role, resource, action) => boolean`.
+ *
+ * Built by `buildPermissionChecker()` from saved role definitions.
+ * - `admin` role: always returns `true` (hardcoded safety net)
+ * - All other roles: exact match from settings (deny-by-default)
+ */
+type PermissionChecker = (role: string, resource: string, action: string) => boolean;
+/**
+ * Handler function for a plugin-provided admin API route.
+ *
+ * Handlers run inside `runWithContextAsync` — `getCurrentApp()`,
+ * `getCurrentLocale()`, `getCurrentDefaultLocale()` are available.
+ * `ctx.app` carries the SAME running app instance as an explicit,
+ * non-optional field rather than requiring the handler to reach for
+ * `getCurrentApp()` (which returns `ToolkitApp | undefined` on the
+ * `@murumets-ee/core` side). This is dependency injection, not a
+ * duplicate mechanism: a "leaf" package (per CLAUDE.md's package-
+ * boundary rule — `logging`, `settings`, etc.) that needs the running
+ * app inside a route handler can read `ctx.app` without importing
+ * `@murumets-ee/core` at all. Some of those packages genuinely CANNOT
+ * import core — `core` itself imports `logging` (`app.ts`), so
+ * `logging` importing `core` back would close a real cycle.
+ * `getCurrentApp()` remains available and unchanged for callers
+ * already inside core's dependency cone.
+ *
+ * `TApp` is generic (defaulting to `unknown`) because this leaf package
+ * cannot name `ToolkitApp` without depending on `@murumets-ee/core` —
+ * see the module-level doc comment (F024). `@murumets-ee/core` binds
+ * `TApp` to the real `ToolkitApp` in its own re-exported `AdminRouteHandler`
+ * alias, so every existing consumer that imports from `@murumets-ee/core`
+ * sees `ctx.app: ToolkitApp` exactly as before.
+ *
+ * @param req - The incoming request
+ * @param ctx.segments - Path segments after the route prefix has been consumed.
+ *   e.g. for `/api/admin/media/abc-123`, the media route handler gets `['abc-123']`.
+ * @param ctx.user - The authenticated user
+ * @param ctx.locale - Content locale from the request (query param)
+ * @param ctx.defaultLocale - Default locale from handler config
+ * @param ctx.audit - Fire-and-forget audit logger (undefined if no auditLogger configured)
+ * @param ctx.checkPermission - Bound permission checker for the current user's role.
+ *   Used by multi-entity routes (e.g. taxonomy) for per-entity permission checks.
+ * @param ctx.app - The running app instance — the SAME reference the
+ *   dispatcher resolved via `getApp()` for this request, not a fresh construction.
+ *   Required (not optional): there is exactly one production construction site
+ *   and it always has the value, so every handler can rely on it being present.
+ */
+type AdminRouteHandler<TApp = unknown> = (req: Request, ctx: {
+  segments: string[];
+  user: AuthUser;
+  locale?: string;
+  defaultLocale?: string;
+  audit?: AuditLogFn;
+  checkPermission: (resource: string, action: string) => boolean;
+  app: TApp;
+}) => Promise<Response>;
+/**
+ * A plugin-provided route group for the admin API handler.
+ *
+ * This is the lower-level shape `createAdminApiHandler` consumes. It is
+ * **not constructible by hand**: the {@link GATED} brand below can only be
+ * named inside this package, so `combineAdminRoutes` is the only way to
+ * produce one — and the combiner in turn accepts only `defineAdminRoute`
+ * outputs. Two independent things enforce that on the combiner's input
+ * (finding H1 and its residual):
+ *
+ *   - `AdminRouteEntry` carries its own non-exported brand (`ENTRY_GATED`),
+ *     required at compile time and re-checked at runtime, so a hand-built
+ *     entry literal is refused.
+ *   - The combiner additionally requires the entry's `guardedHandler` to
+ *     be a function `defineAdminRoute` actually minted (tracked in a
+ *     module-private `WeakSet`). The brand alone was NOT enough: it is an
+ *     enumerable property, so `{ ...realEntry, guardedHandler: mine }`
+ *     carried it faithfully while discarding the gate, with zero casts.
+ *
+ * `defineAdminRoute` requires a `permission` and builds the gate itself,
+ * so neither end of that chain admits an ungated handler. There is no
+ * "declare a prefix and gate it yourself" shape any more; the legacy
+ * top-level `resource` / `actions` gate was retired in
+ * `plan/admin-api-hardening/` PR 3 (F006).
+ *
+ * The guarantee is scoped to author error and `as` casts. Code already
+ * executing in the process can read either brand off a legitimately
+ * minted value — it just cannot get a forged `guardedHandler` past
+ * `combineAdminRoutes`, because function identity is not copyable.
+ *
+ * The centralized handler dispatches to plugin routes by matching the
+ * first path segment against the prefix.
+ *
+ * @example
+ * ```typescript
+ * // The ONLY shape. Each entry registers its permission in the catalog
+ * // and is wrapper-gated automatically (`guardedHandler`), so a route
+ * // that reaches dispatch has provably passed a permission check.
+ * import { type AdminRoute, combineAdminRoutes, defineAdminRoute } from '@murumets-ee/core'
+ *
+ * export function pluginRoutes(): AdminRoute[] {
+ *   return combineAdminRoutes([
+ *     defineAdminRoute({
+ *       prefix: 'plugin', path: '', method: 'GET',
+ *       permission: 'plugin:view',
+ *       defaultRoles: ['admin', 'editor', 'agent', 'viewer'],
+ *       handler: async (req, ctx) => { ... },
+ *     }),
+ *     defineAdminRoute({
+ *       prefix: 'plugin', path: '', method: 'POST',
+ *       permission: 'plugin:create',
+ *       defaultRoles: ['admin'],
+ *       handler: async (req, ctx) => { ... },
+ *     }),
+ *   ])
+ * }
+ *
+ * // ✗ Does NOT compile — TS2741, property '[GATED]' is missing. An
+ * //   ungated admin route is unwritable, not merely discouraged.
+ * const rogue: AdminRoute = { prefix: 'plugin', handlers: { GET: h } }
+ * ```
+ */
+interface AdminRoute<TApp = unknown> {
+  /**
+   * Nominal brand — present ONLY on routes minted by
+   * `combineAdminRoutes`. See {@link GATED} for the full rationale; the
+   * short version is that this property is what makes an ungated admin
+   * route a compile error rather than a code-review question.
+   */
+  readonly [GATED]: true;
+  /** URL prefix, e.g. 'media' matches `/api/admin/media/*` */
+  prefix: string;
+  /** HTTP method handlers */
+  handlers: {
+    GET?: AdminRouteHandler<TApp>;
+    POST?: AdminRouteHandler<TApp>;
+    PATCH?: AdminRouteHandler<TApp>;
+    DELETE?: AdminRouteHandler<TApp>;
+  };
+}
+/**
+ * Layer 3 of three — the RUNTIME half of the gating guarantee.
+ *
+ * Reports whether `value` carries the {@link GATED} brand, i.e. whether it
+ * was actually produced by `combineAdminRoutes` rather than merely
+ * *typed* as an {@link AdminRoute}. Safe to export: it reads the brand, it
+ * cannot mint it.
+ *
+ * The type layer (layer 2) is erased at runtime and never runs at all for
+ * a plain-JavaScript plugin or for TypeScript that reached the shape via
+ * `as`. Route collection therefore re-checks structurally and refuses
+ * anything unbranded — see `getRouteMap` in `@murumets-ee/admin-ui`.
+ *
+ * The predicate is deliberately `TApp`-agnostic (`AdminRoute<unknown>`):
+ * the brand says nothing about which app shape the handlers expect.
+ *
+ * **Narrowing caveat.** That genericity is not free. `AdminRoute<unknown>`
+ * IS assignable to `AdminRoute<SomeApp>` — the handlers are functions
+ * taking `ctx.app`, so `TApp` is contravariant and the `unknown`
+ * instantiation is the more permissive one. TypeScript therefore treats
+ * the predicate type as the narrower candidate and a caller that already
+ * held an `AdminRoute<SomeApp>` comes out of the guard holding
+ * `AdminRoute<unknown>`, losing the app instantiation. Callers that need
+ * to keep it should use a `boolean`-returning assertion instead of
+ * narrowing on this predicate — which is what `@murumets-ee/admin-ui`'s
+ * `assertGated` does, so nothing in-tree is affected today.
+ */
+declare function isGatedRoute(value: unknown): value is AdminRoute;
+//#endregion
+//#region src/permissions/resolved.d.ts
+/**
+ * The public permission-string type.
+ *
+ * ## History — issue #357 typed-union approach (reversed 2026-07-02)
+ *
+ * PRs 1–4 of #357 shipped a compile-time typed union: every app augmented
+ * `PermissionStringRegistry` with `ResolvedPermissions<typeof config>`, materializing a
+ * flat `` `${resource}:${action}` `` union of *every* permission so `tsc` caught typos
+ * at `permission:` callsites (plus autocomplete).
+ *
+ * Measured at real-app scale, that augmentation forced the entire `typeof config` type
+ * (~27k type-instantiations across ~9 plugin factories) into the resolution of
+ * `PermissionString` — which is referenced at every `permission:` / `requires:` callsite.
+ * The resulting union sat right at TypeScript's union-complexity ceiling. Under a full
+ * `next build` (the extra `.next/types` program load) it tipped over **non-
+ * deterministically**: the union silently widened to the loose fallback, typo-detection
+ * degraded, and the `typed-permissions-demo` canary's `@ts-expect-error` guards became
+ * "unused" → `scaffold-e2e` failed on PRs while local `tsc` passed. The approach was
+ * fundamentally too fragile at scale (it degraded by *build environment*, not by code).
+ *
+ * The typo-detection GOAL is retained by a cheaper, robust mechanism:
+ * {@link import('@murumets-ee/auth').assertPermissionsResolvable} runs at boot, validates
+ * every declared route / page / sidebar permission against the runtime permission catalog,
+ * and throws loudly on an unknown `resource:action` — "fail loud at boot", O(n), no type
+ * ceiling, and it also validates the dynamic `` `${entity.name}:view` `` strings the typed
+ * union never could.
+ *
+ * So `PermissionString` is simply the shape `` `${string}:${string}` ``: callsites still
+ * type-accept a `resource:action` string; the boot check enforces that it actually exists.
+ */
+type PermissionString = `${string}:${string}`;
+//#endregion
+//#region src/define-admin-route.d.ts
+/** HTTP methods the admin API handler dispatches. */
+type AdminRouteMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+/**
+ * Template-literal type that REJECTS multi-segment paths at compile
+ * time. A path containing `/` resolves to `never`, so the assignment
+ * fails with a TS error pointing at the literal that contains the
+ * slash.
+ *
+ * PR 5 of `PLAN-DECLARATIVE-PLUGINS.md` — addresses foot-gun F3
+ * (`defineAdminRoute({ path: 'accounts/:id/poll-now' })` throwing at
+ * registration with a runtime error). The runtime check survives as
+ * defense-in-depth (a malformed dist that slipped past TS, or a
+ * dynamic-string callsite with `as` cast), but typical plugin
+ * authors get the error on save, in their editor, before they even
+ * try to boot.
+ *
+ * @example
+ * ```ts
+ * // ✓ Compiles
+ * defineAdminRoute({ path: 'reply', ... })
+ *
+ * // ✗ TS error — 'reply/:ticketId' is not assignable to 'never'
+ * defineAdminRoute({ path: 'reply/:ticketId', ... })
+ * ```
+ *
+ * For URL shapes where `segments[0]` is itself a runtime value
+ * (e.g. `/media/<uuid>`), use `{ path: '', matchAnyPath: true }` —
+ * `''` (empty) is not multi-segment, so it satisfies the constraint.
+ *
+ * Same template-literal technique as `PermissionString` (PR #357).
+ */
+type SegmentPath<P extends string> = P extends `${string}/${string}` ? never : P;
+/**
+ * Spec passed to {@link defineAdminRoute}. `permission` is REQUIRED — a route
+ * without an explicit permission can't compile. There is no "publicly callable
+ * admin route" — see CLAUDE.md security section.
+ *
+ * Generic over `TApp` (the `ctx.app` type — see the `TApp` threading note
+ * above) and `P` (the literal `path` string, constrained by
+ * {@link SegmentPath}). Both default so a bare `DefineAdminRouteSpec`
+ * type reference (docs, non-instantiating usage) still resolves to the
+ * pre-extraction shape (`ctx.app: unknown`, `path: string`).
+ */
+interface DefineAdminRouteSpec<TApp = unknown, P extends string = string> {
+  /**
+   * URL prefix segment, e.g. `'ticketing'` for `/api/admin/ticketing/*`.
+   * Routes sharing a prefix MUST be passed together to `combineAdminRoutes`
+   * — the resulting `AdminRoute` is keyed on this prefix.
+   */
+  prefix: string;
+  /**
+   * Sub-path within the prefix, e.g. `'reply'` for
+   * `/api/admin/ticketing/reply`. Pass `''` for the root path
+   * (`/api/admin/<prefix>`).
+   *
+   * **Single segment only.** `path` must not contain `/`. Dynamic
+   * sub-segments (`'reply/:ticketId'`-style paths) are NOT supported by
+   * the combiner — it dispatches strictly on `ctx.segments[0]`. Routes
+   * accepting dynamic IDs read them from `ctx.segments[1..]` inside the
+   * handler; the registered `path` should still be the static prefix
+   * (e.g. `'reply'`). The factory throws at registration time on input
+   * containing `/` — loud-at-boot is the design.
+   *
+   * For URL shapes where `segments[0]` itself is a runtime value
+   * (e.g. `/media/<uuid>`), set {@link matchAnyPath} = `true` with
+   * `path: ''` — the combiner then dispatches every unmatched sub-path
+   * through this entry's handler instead of returning dispatch-miss.
+   */
+  path: SegmentPath<P>;
+  /** HTTP method this route serves. */
+  method: AdminRouteMethod;
+  /**
+   * Permission required, in `'<resource>:<action>'` form. The api-handler
+   * verifies the caller's role has this grant before invoking `handler`;
+   * a missing grant returns 403 with no handler invocation. The string is
+   * also added to the catalog so role-default seeding and the audit UI
+   * pick it up automatically.
+   *
+   * Resolves to the literal union from
+   * `@murumets-ee/core`'s {@link PermissionStringRegistry} when the
+   * consuming app augments it (see `PermissionString` docs); otherwise
+   * falls back to the loose `${string}:${string}` template literal so
+   * dynamic per-resource callsites in toolkit packages keep compiling.
+   */
+  permission: PermissionString;
+  /**
+   * Built-in roles that should be granted this permission on first
+   * deploy / on `upsertBuiltInRoles`. Defaults to `[]` (admin always
+   * passes via the hardcoded safety net in `buildPermissionChecker`).
+   */
+  defaultRoles?: readonly string[];
+  /**
+   * Optional description for the Permission Matrix UI (PR-D) and audit
+   * logs. Plain-text, no markdown.
+   */
+  description?: string;
+  /** The actual handler — runs only after the permission check passes. */
+  handler: AdminRouteHandler<TApp>;
+  /**
+   * Opt-in catch-all flag for plugins whose top-level URL surface embeds a
+   * runtime-value segment directly after the prefix (e.g. `/media/<uuid>`,
+   * `/media/<uuid>/usage`). When `true`, the combiner's dispatcher
+   * delegates to this entry's `guardedHandler` for any `(prefix, method)`
+   * sub-path that no other registered `path` claims — instead of
+   * returning the default dispatch-miss 404/403.
+   *
+   * Constraints (enforced at registration / combine time):
+   *
+   *   - `path` MUST be `''`. Static paths take precedence over the
+   *     catch-all, so the path slot is reserved for the prefix-root.
+   *   - At most ONE matchAnyPath entry per `(prefix, method)`. Two
+   *     conflicting catch-alls would silently shadow each other.
+   *   - The handler is still wrapper-gated on `permission`. The wrapper
+   *     emits the same `permission.denied` audit on deny as every other
+   *     `defineAdminRoute`. The TRADE-OFF: when the wrapper passes but
+   *     the handler internally returns 404 for an unknown sub-path,
+   *     there's no `kind: 'dispatch-miss'` forensic enrichment on the
+   *     audit row (the wrapper-gated audit fires on permission deny,
+   *     not on handler-level 404). For surfaces where the URL space is
+   *     enumerable by callers with the permission anyway (media's
+   *     `/media/<uuid>` — any holder of `media:view` can already list
+   *     IDs via `GET /media`), the missing enrichment carries no
+   *     forensic loss. Plugins whose sub-path namespace IS sensitive
+   *     should use static paths instead.
+   *
+   * **Default `false`.** Use sparingly — static paths + the
+   * `kind: 'dispatch-miss'` audit are the preferred shape. The known
+   * use case is plugins whose URL surface predates the framework's
+   * static-path convention and where breaking clients to retrofit a
+   * sub-resource segment isn't worth the audit-enrichment win.
+   */
+  matchAnyPath?: boolean;
+}
+/**
+ * The nominal gating brand carried by every {@link AdminRouteEntry} that
+ * {@link defineAdminRoute} actually produced (`plan/admin-api-hardening/`
+ * PR 3, finding H1).
+ *
+ * ## Why a SECOND brand
+ *
+ * `GATED` (see `admin-route.ts`) brands the {@link AdminRoute} that
+ * `combineAdminRoutes` mints, on the reasoning "the combiner is fed only
+ * by `defineAdminRoute` outputs, so the brand transitively means 'went
+ * through a permission gate'". That premise was false: `AdminRouteEntry`
+ * was fully structural and publicly exported (from this package's barrel
+ * and re-exported by `@murumets-ee/core`), so a hand-written literal —
+ * every field a plain property, `guardedHandler` included — satisfied it.
+ * Feeding that literal to `combineAdminRoutes` produced a genuinely
+ * branded `AdminRoute` that passed `isGatedRoute`, registered in
+ * `getRouteMap`, and served every request under its prefix to any
+ * authenticated user with no permission check at all. The permission
+ * catalog never learned of it either, so `assertPermissionsResolvable`
+ * stayed silent.
+ *
+ * That is not a hypothetical shape. Returning a bare `AdminRouteEntry` is
+ * an established in-repo idiom (`priceCheckRouteEntry`,
+ * `replacementRouteEntries` in `@murumets-ee/commerce`) — both legitimately
+ * obtain theirs from `defineAdminRoute`, but an author copying the shape
+ * and building the literal by hand landed exactly here. Author error, the
+ * exact class PR 3 exists to close.
+ *
+ * Branding the ENTRY closes the gap at the same two layers as `GATED`:
+ * the required `readonly` member makes a hand-written literal a compile
+ * error, and `combineAdminRoutes` re-checks structurally at runtime for
+ * the plain-JS / `as`-cast paths where types are erased.
+ *
+ * ## Why it is not exported from the barrel
+ *
+ * Same rule as `GATED`: exported from THIS MODULE (so the minter and the
+ * combiner can name the key with no cast) but deliberately NOT re-exported
+ * from `src/index.ts`, and the package's `exports` map has no deep paths.
+ * A `unique symbol` makes that airtight — a same-named
+ * `Symbol('lumi.admin-route.entry')` declared elsewhere is a DIFFERENT
+ * `unique symbol` type and does not satisfy the property.
+ *
+ * ## Why a plain enumerable own property — and why that is not enough
+ *
+ * Identical rationale to `GATED`: it must survive `{ ...entry }` spread,
+ * or an entry the compiler blessed would be rejected at combine time.
+ * Symbol keys are already excluded from `Object.keys`, `for…in` and
+ * `JSON.stringify`, so enumerability costs nothing in serialization noise.
+ *
+ * But spread-survival is EXACTLY what makes the envelope the wrong anchor
+ * for provenance. The brand travels with a copy while the gate does not:
+ *
+ * ```ts
+ * const legit = defineAdminRoute({ …real permission, real gate… })
+ * combineAdminRoutes([{ ...legit, guardedHandler: async () => new Response('PWNED') }])
+ * ```
+ *
+ * That literal carries a genuine `ENTRY_GATED`, typechecks with zero casts
+ * and zero suppressions, and — until `MINTED_GUARDS` — combined into
+ * a fully-branded `AdminRoute` that served its whole prefix ungated. It is
+ * strictly EASIER than the hand-built literal this brand closed, which
+ * needed `as unknown as` plus eleven hand-written fields.
+ *
+ * So the brand is only ONE of the two layers. The runtime provenance
+ * anchor is `MINTED_GUARDS`, which is keyed on the identity of the
+ * `guardedHandler` function itself — the thing that actually holds the
+ * gate, and the thing a decorator swaps. The brand keeps its own job:
+ * making a hand-written literal a COMPILE error, which a `WeakSet` can
+ * never do.
+ *
+ * ## Threat model
+ *
+ * Unchanged from `GATED`: this stops author error and `as` casts, not
+ * hostile code already executing in the process, which can read the key
+ * off any legitimately minted entry via `Object.getOwnPropertySymbols`.
+ */
+declare const ENTRY_GATED: unique symbol;
+/**
+ * The compiled output of {@link defineAdminRoute}. The handler is wrapped
+ * in a permission gate (`guardedHandler`); the original is preserved as
+ * `handler` for tests + introspection.
+ *
+ * **Not constructible by hand, and not re-pointable after the fact.** Three
+ * things enforce that, and each covers a hole the others do not:
+ *
+ *   1. The {@link ENTRY_GATED} brand can only be named inside this package,
+ *      so a hand-written literal is a COMPILE error.
+ *   2. Every field is `readonly`, so `entry.guardedHandler = mine` is a
+ *      COMPILE error too — the plain-mutation form of the same attack.
+ *   3. `MINTED_GUARDS` records the `guardedHandler` function identity
+ *      at mint time, and {@link combineAdminRoutes} requires it at RUNTIME.
+ *      This is the only layer that catches `{ ...entry, guardedHandler:
+ *      mine }` — a fresh literal, so `readonly` never applies to it, and a
+ *      faithful spread, so the brand comes along for the ride.
+ *
+ * `defineAdminRoute` — which requires a `permission`, registers it in the
+ * catalog, and builds `guardedHandler` itself — is therefore the only way
+ * to produce a value that survives all three. Declare the entry's TYPE
+ * (`function xRouteEntries(): AdminRouteEntry[]`) freely; just build the
+ * values with the factory.
+ *
+ * Generic over `TApp` (see the `TApp` threading note above) — the
+ * registered `path` here is the plain compiled string, no longer
+ * constrained by {@link SegmentPath} (that constraint applies only at
+ * {@link defineAdminRoute}'s call site).
+ */
+interface AdminRouteEntry<TApp = unknown> {
+  /**
+   * Nominal brand — present ONLY on entries minted by
+   * {@link defineAdminRoute}. See {@link ENTRY_GATED} for the full
+   * rationale; the short version is that this property is what stops a
+   * hand-built entry literal from laundering an ungated handler through
+   * `combineAdminRoutes` and out the other side as a branded
+   * {@link AdminRoute}. It does NOT, on its own, stop a *copy* of a real
+   * entry with a substituted gate — that is `MINTED_GUARDS`'s job.
+   */
+  readonly [ENTRY_GATED]: true;
+  readonly prefix: string;
+  readonly path: string;
+  readonly method: AdminRouteMethod;
+  readonly permission: string;
+  /** Parsed left side of `permission`. */
+  readonly resource: string;
+  /** Parsed right side of `permission`. */
+  readonly action: string;
+  readonly defaultRoles: readonly string[];
+  readonly description: string | undefined;
+  /** Original user handler (unwrapped). */
+  readonly handler: AdminRouteHandler<TApp>;
+  /**
+   * Permission-gated handler. Returns 403 if `ctx.checkPermission(resource,
+   * action)` is false; otherwise delegates to {@link handler}.
+   *
+   * On denial, emits a `permission.denied` audit entry via `ctx.audit`
+   * (when available) BEFORE the 403 response — no per-route audit wiring
+   * needed. The entry's metadata carries the permission string, caller
+   * role, HTTP method, route coordinates, and request segments.
+   *
+   * **This function's IDENTITY is the provenance anchor.** It is recorded
+   * in `MINTED_GUARDS` at mint time and re-checked by
+   * {@link combineAdminRoutes}. Replacing it — by assignment (blocked by
+   * `readonly`) or by spreading into a new literal (blocked at runtime) —
+   * is refused, INCLUDING by a decorator that faithfully calls through.
+   * To add behaviour around a route, wrap the `handler` you pass into
+   * {@link defineAdminRoute}.
+   */
+  readonly guardedHandler: AdminRouteHandler<TApp>;
+  /**
+   * Whether this entry catches every unmatched sub-path under
+   * `(prefix, method)`. Mirrors {@link DefineAdminRouteSpec.matchAnyPath}
+   * — captured on the compiled entry so `combineAdminRoutes` can wire
+   * the dispatcher's catch-all slot.
+   */
+  readonly matchAnyPath: boolean;
+}
+/**
+ * One entry per `(resource, action)` pair contributed by `defineAdminRoute`,
+ * `defineFeature`, or `defineAdminPage` (forthcoming). Consumed by:
+ *
+ *   - `upsertBuiltInRoles` to seed default grants
+ *   - Permission Matrix UI (PR-D)
+ *   - `buildResourceCatalog` migration (PR-F)
+ */
+interface PermissionCatalogEntry {
+  resource: string;
+  action: string;
+  /** `'<resource>:<action>'` — the full permission string. */
+  permission: string;
+  /** Roles that get this grant on a fresh upsert. */
+  defaultRoles: readonly string[];
+  /** Free-text description; surfaced in the audit UI. */
+  description: string | undefined;
+  /**
+   * Where this entry came from. `'route'` = `defineAdminRoute`,
+   * `'page'` = `defineAdminPage`, `'feature'` = `defineFeature`. The
+   * Matrix UI groups by this when rendering.
+   */
+  source: 'route' | 'page' | 'feature';
+}
+/**
+ * Register a permission in the catalog. Idempotent — repeat calls for the
+ * same permission union the `defaultRoles`. Exported for factory code only
+ * (`defineAdminRoute` / `defineFeature` / forthcoming `defineAdminPage`)
+ * to share the same map; plugin code should call a factory instead — the
+ * factories validate input shape (no `:` in resource/action, non-empty
+ * fields, etc.) that this raw primitive does not.
+ *
+ * **Returns the resulting catalog entry.** On a fresh registration this is
+ * the input `entry`; on a repeat registration this is the post-merge entry
+ * (existing first-wins `source` + `description`, unioned `defaultRoles`).
+ * Callers that need to expose the authoritative catalog state should use
+ * the return value rather than the input draft — see `defineFeature`.
+ */
+declare function registerPermission(entry: PermissionCatalogEntry): PermissionCatalogEntry;
+/**
+ * Snapshot of the current catalog as a `Map<permission, entry>`.
+ *
+ * Returns a NEW map each call — callers can mutate the result without
+ * affecting the registry. Read-only access to the live map is intentional
+ * — the registry's invariants (e.g. unioned defaults) belong to
+ * `registerPermission`, not to call sites.
+ */
+declare function getPermissionCatalog(): Map<string, PermissionCatalogEntry>;
+/**
+ * Test-only — clear the catalog between test suites that exercise factory
+ * registration. NEVER call in production code; the catalog is global state
+ * by design.
+ */
+declare function _resetPermissionCatalog(): void;
+/**
+ * Remove every catalog entry with `source: 'feature'`. Used by
+ * `resolveShell` to rebuild the feature subset deterministically on every
+ * call — features come exclusively from `Plugin.shared.features` in the
+ * input plugin list, so the catalog should reflect the CURRENT input,
+ * not the accumulated history.
+ *
+ * **Lifecycle contract:** `resolveShell` owns `source: 'feature'`
+ * registrations. Direct `defineFeature` callers (tests, scripts) that
+ * also call `resolveShell` will have their direct registrations cleared
+ * when `resolveShell` next runs — same as `defineAdminRoute` entries
+ * registered at module load aren't owned by `resolveShell` but features
+ * registered IN this call are.
+ *
+ * Test-only direct callers that need their features to survive a
+ * subsequent `resolveShell` either (a) re-call `defineFeature` after
+ * `resolveShell`, or (b) declare them via a fixture plugin in the
+ * `resolveShell` input.
+ */
+declare function clearFeaturePermissions(): void;
+/**
+ * **The canonical primitive** for emitting audit entries from a route handler.
+ *
+ * `ctx.audit?.(...)` directly is a footgun: a synchronous throw inside the
+ * audit adapter (bad serialization, malformed metadata, broken logger) would
+ * turn the intended response into a 500. This wrapper swallows sync throws —
+ * the response always lands.
+ *
+ * **Every audit emission from a route handler should go through this primitive
+ * instead of calling `ctx.audit?.(...)` directly.** That removes the
+ * "did the developer remember to add try/catch?" question from every call
+ * site — the safe primitive IS the API.
+ *
+ * Sync-throw isolation only. Async-rejection handling for the `void`-typed
+ * `AuditLogFn` happens centrally in `@murumets-ee/admin-ui`'s
+ * `buildAuditLogFn` (issue #373) — the adapter that fronts the actual audit
+ * logger is responsible for catching `Promise<void>` rejection.
+ *
+ * @example
+ * ```ts
+ * import { safeAudit } from '@murumets-ee/core'
+ *
+ * if (somethingFailed) {
+ *   safeAudit(ctx, {
+ *     action: 'commerce.import.run.rejected',
+ *     entityType: 'import_run',
+ *     userId: ctx.user.id,
+ *     metadata: { reason: 'size mismatch', storageKey },
+ *   })
+ *   return errorJson('...', 400)
+ * }
+ * ```
+ */
+declare function safeAudit(ctx: Parameters<AdminRouteHandler>[1], entry: Parameters<NonNullable<Parameters<AdminRouteHandler>[1]['audit']>>[0]): void;
+/**
+ * Spec for {@link emitPermissionDenied}. Mirrors the subset of
+ * {@link DefineAdminRouteSpec} that's relevant to audit metadata. Inline-gated
+ * routes supply this manually; the wrapper builds it from its own spec.
+ */
+interface PermissionDenialContext {
+  /** The permission that was denied, in `'<resource>:<action>'` form. */
+  permission: string;
+  /** HTTP method of the request. */
+  method: AdminRouteMethod;
+  /** URL prefix segment (the `prefix` field of the route's `defineAdminRoute` spec). */
+  prefix: string;
+  /** Path within the prefix (the `path` field; `''` for prefix-root). */
+  path: string;
+  /**
+   * Extra audit metadata merged into the persisted entry's `metadata` block.
+   *
+   * Use sparingly — most permission-denial events have everything they need
+   * from the standard fields. The two known consumers as of writing:
+   *
+   *   - `kind: 'dispatch-miss'` from `makeDispatcher` so audit-search can
+   *     distinguish wrapper-gated 403s (caller hit a registered route they
+   *     can't access) from dispatcher-miss 403s (caller probed for an
+   *     unknown sub-path under a prefix they have zero visibility into).
+   *     Wrapper-gated emits don't set `kind`; absence = wrapper-gated.
+   *   - `requiredAny: string[]` from `makeDispatcher` listing the full
+   *     prefix permission set the caller lacks (vs. the single
+   *     representative `permission` field). Lets forensics see whether
+   *     the caller was missing one specific grant or all of them.
+   *
+   * Caller-supplied keys override standard keys on collision. Out-of-band
+   * `userId`/`userName` etc. are not allowed via this path (they live on
+   * the top-level audit entry, not in `metadata`).
+   */
+  extraMetadata?: Record<string, unknown>;
+}
+/**
+ * Emit the standard `permission.denied` audit entry for a denied request.
+ *
+ * Sync-throw isolated: a failing audit adapter MUST NOT turn the intended 403
+ * into a 500. Async-rejection handling for the `void`-typed `AuditLogFn` lives
+ * separately in `@murumets-ee/admin-ui`'s `buildAuditLogFn` (#373).
+ *
+ * The audit shape is filterable by `action = 'permission.denied'`, with
+ * structured metadata for forensics (permission, role, HTTP method, route
+ * coordinates, request segments). `userName` and `role` are conditionally
+ * spread so undefined values don't pollute the persisted metadata.
+ *
+ * `entityType: 'permission'` (singular) is intentional — it describes the
+ * abstract grant being denied. Compare with `@murumets-ee/auth`'s permission-
+ * management routes which use `entityType: 'permissions'` (plural) for
+ * actions like `permissions.update` / `permissions.role.create`. The semantic
+ * split: `permission` = "denial event"; `permissions` = "role-management
+ * resource being CRUD'd". Audit-search filters targeting either category
+ * should query both when looking for any permission-related activity.
+ */
+declare function emitPermissionDenied(ctx: Parameters<AdminRouteHandler>[1], spec: PermissionDenialContext): void;
+/**
+ * The standard 403 response for permission denial. Body shape:
+ * `{ error, code: 'forbidden' }`. Frontend callers can branch on
+ * `body.code === 'forbidden'` uniformly across every admin denial.
+ *
+ * Pair with {@link emitPermissionDenied} at every inline permission check:
+ *
+ * ```ts
+ * if (!ctx.checkPermission(resource, action)) {
+ *   emitPermissionDenied(ctx, { permission: `${resource}:${action}`, method, prefix, path })
+ *   return permissionDeniedResponse(`${resource}:${action}`, ctx.user.role)
+ * }
+ * ```
+ */
+declare function permissionDeniedResponse(permission: string, role: string | undefined): Response;
+/**
+ * Declare an admin API route with its required permission.
+ *
+ * The returned {@link AdminRouteEntry} is consumed by
+ * {@link combineAdminRoutes}, which collapses many entries into the
+ * legacy `AdminRoute[]` shape that `createAdminApiHandler` already
+ * dispatches.
+ *
+ * **Side effect:** registers the permission in the process-local
+ * catalog. Calling the factory at module-load time (the normal usage,
+ * inside a `routes/*.ts` file) means the catalog is fully populated by
+ * the time the api-handler boots.
+ *
+ * **Auto-audit:** when the wrapper denies a request (the caller's role
+ * lacks `permission`), it emits a `permission.denied` entry via
+ * `ctx.audit` before returning 403. Metadata includes the permission
+ * string, caller role, HTTP method, route coordinates, and segments.
+ * Every denial leaves a trail without per-route boilerplate; the prior
+ * pattern relied on inline `auditRejection`-style helpers that were
+ * forgotten on most routes (search, parts-search, taxonomy, etc.),
+ * making UUID-enumeration probes / permission-bypass attempts invisible
+ * post-hoc. Filter the audit search on `action = 'permission.denied'`.
+ *
+ * @example
+ * ```ts
+ * import { defineAdminRoute } from '@murumets-ee/core'
+ *
+ * export const replyRoute = defineAdminRoute({
+ *   prefix: 'ticketing',
+ *   path: 'reply',
+ *   method: 'POST',
+ *   permission: 'ticket:update',
+ *   defaultRoles: ['admin', 'agent'],
+ *   description: 'Post an agent reply to a ticket conversation',
+ *   handler: async (req, ctx) => { return new Response('ok') },
+ * })
+ * ```
+ */
+declare function defineAdminRoute<TApp = unknown, const P extends string = string>(spec: DefineAdminRouteSpec<TApp, P>): AdminRouteEntry<TApp>;
+/**
+ * Spec passed to {@link defineFeature}.
+ *
+ * Plugin-level NON-CRUD resources whose permission grants aren't tied to a
+ * single route or entity — e.g. `ticketing.bulk-edit` with actions
+ * `['view', 'execute']`, or `commerce.imports` with `['view', 'export',
+ * 'cancel']`. Use `defineAdminRoute` for routes and `defineAdminPage` for
+ * pages; `defineFeature` is the catalog hook for everything that's neither.
+ *
+ * The resource string is the same shape as a `defineAdminRoute` permission's
+ * left side. Actions are the right side — one catalog entry is emitted per
+ * `(resource, action)` pair, exactly as if `defineAdminRoute` had been
+ * called once per action with a no-op handler.
+ *
+ * @example
+ * ```ts
+ * defineFeature({
+ *   resource: 'ticketing.bulk-edit',
+ *   actions: ['view', 'execute'],
+ *   defaultRoles: ['admin', 'agent'],
+ *   description: 'Operate ticketing bulk-edit tools',
+ * })
+ * ```
+ */
+interface DefineFeatureSpec {
+  /**
+   * Resource string — left side of the permission. Must be non-empty and
+   * not contain `:` (the action separator). Convention: dot-notation for
+   * plugin-prefixed names (`'ticketing.bulk-edit'`, `'commerce.imports'`).
+   */
+  resource: string;
+  /**
+   * Actions on this resource. Each becomes a catalog entry
+   * `<resource>:<action>`. Must be non-empty; each action must be a
+   * non-empty string without `:`. Duplicates within the same call are
+   * rejected (would be silently deduped by `registerPermission` but the
+   * call-site shape suggests programmer error).
+   */
+  actions: readonly string[];
+  /**
+   * Built-in roles that should be granted EVERY action on this resource
+   * on first deploy / on `upsertBuiltInRoles`. Defaults to `[]`. The same
+   * default-roles set applies to every action — if different actions
+   * need different default grants, register separate `defineFeature`
+   * calls (or use `defineAdminRoute` for the action that needs a
+   * different grant).
+   */
+  defaultRoles?: readonly string[];
+  /**
+   * Optional description for the Permission Matrix UI (PR-D) and audit
+   * logs. Plain-text, no markdown. Applied to every catalog entry the
+   * call produces; per-action descriptions need separate `defineFeature`
+   * calls (one per action).
+   */
+  description?: string;
+}
+/**
+ * Register a non-CRUD plugin resource in the permission catalog.
+ *
+ * **Plugin authors should NOT call this directly.** Contribute features
+ * declaratively via `Plugin.shared.features: DefineFeatureSpec[]` — the
+ * framework's merge step at boot iterates that array and calls this
+ * factory for each spec. The declarative path is the supported plugin-
+ * authoring API; direct invocation is reserved for tests / scripts /
+ * non-plugin call sites that need to populate the catalog explicitly.
+ *
+ * The returned `PermissionCatalogEntry[]` contains ONE entry per `(resource,
+ * action)` pair — the same shape every other catalog consumer
+ * (`upsertBuiltInRoles`, Permission Matrix UI, `buildResourceCatalog`)
+ * already understands. Each returned entry reflects the AUTHORITATIVE
+ * post-merge catalog state: on a fresh registration it equals the input
+ * spec's fields; on a repeat registration (something else already
+ * contributed the same `(resource, action)` pair) the entry carries the
+ * first registrant's `source` + `description` and the union of every
+ * registrant's `defaultRoles`. Callers consume the return value as a
+ * truthful snapshot, not the draft this call would have registered.
+ *
+ * Unlike {@link defineAdminRoute}, `defineFeature` does NOT produce a
+ * handler — its only contribution is the catalog registration. Use this
+ * for non-route, non-entity-action permissions that the toolkit's auth
+ * layer should know about: feature flags an admin can grant per-role,
+ * bulk operations that aren't a discrete HTTP endpoint, scheduled-job
+ * "run-now" capabilities, etc.
+ *
+ * **Why a wrapper exists when `registerPermission` already does the job:**
+ * the wrapper validates input shape (non-empty resource, non-empty
+ * actions, no `:` in either, no duplicate actions in the same call),
+ * splits a multi-action declaration into the right number of catalog
+ * entries, and sets `source: 'feature'` so the Matrix UI can group by
+ * declaration site. `registerPermission` is the lower-level primitive
+ * shared with `defineAdminRoute`; plugin code should reach for
+ * `defineFeature` instead.
+ *
+ * **Idempotency:** repeat calls for the same `(resource, action)` pair
+ * union their `defaultRoles` (same behavior as `defineAdminRoute`
+ * registering the same permission twice). Two plugins both declaring
+ * `'ticketing.bulk-edit:execute'` produce one catalog entry with the
+ * combined defaults.
+ *
+ * @example Plugin authoring (declarative — preferred):
+ * ```ts
+ * import type { Plugin } from '@murumets-ee/core'
+ *
+ * export function ticketingPlugin(): Plugin {
+ *   return {
+ *     name: '@app/ticketing',
+ *     shared: {
+ *       features: [
+ *         {
+ *           resource: 'ticketing.bulk-edit',
+ *           actions: ['view', 'execute'],
+ *           defaultRoles: ['admin', 'agent'],
+ *           description: 'Operate ticketing bulk-edit tools',
+ *         },
+ *       ],
+ *     },
+ *   }
+ * }
+ * ```
+ *
+ * @example Tests / scripts (direct invocation):
+ * ```ts
+ * import { defineFeature } from '@murumets-ee/core'
+ *
+ * const entries = defineFeature({
+ *   resource: 'ticketing.bulk-edit',
+ *   actions: ['view', 'execute'],
+ *   defaultRoles: ['admin', 'agent'],
+ * })
+ * // entries[0].source === 'feature'
+ * ```
+ */
+declare function defineFeature(spec: DefineFeatureSpec): PermissionCatalogEntry[];
+/**
+ * Collapse a list of `defineAdminRoute` outputs into the legacy
+ * `AdminRoute[]` shape that `createAdminApiHandler` dispatches.
+ *
+ * Routes are grouped by `prefix`. Each prefix's resulting `AdminRoute`
+ * gets per-method handlers that dispatch on the leading path segment
+ * matching the entry's `path` (or the root segment when `path === ''`).
+ *
+ * Sub-path dispatch is strictly single-level — `path` cannot contain
+ * `/` (rejected by `defineAdminRoute` at registration). Dynamic IDs are
+ * read by the handler from `ctx.segments[1..]`. This matches the
+ * existing convention every plugin already uses (see ticketing's
+ * `dispatch()` for the prior art).
+ *
+ * Conflict detection: two entries claiming the same `(prefix, method,
+ * path)` triple throw at combine time — better to fail at boot than to
+ * silently shadow a route.
+ *
+ * Provenance check, in two parts (finding H1 and its residual):
+ *
+ *   1. The entry must carry the {@link ENTRY_GATED} brand — it must LOOK
+ *      like something {@link defineAdminRoute} produced.
+ *   2. Its `guardedHandler` must be one {@link defineAdminRoute} actually
+ *      minted (`MINTED_GUARDS`). Part 1 alone is insufficient: a
+ *      spread copy carries the brand while substituting the gate.
+ *
+ * Either failure throws. **A decorator that wraps `guardedHandler` fails
+ * part 2 and is refused** — intentionally, since a wrapper's continued
+ * gating cannot be verified from here. Wrap the `handler` passed into
+ * {@link defineAdminRoute} instead.
+ */
+declare function combineAdminRoutes<TApp = unknown>(entries: readonly AdminRouteEntry<TApp>[]): AdminRoute<TApp>[];
+//#endregion
+export { type AdminRoute, type AdminRouteEntry, type AdminRouteHandler, type AdminRouteMethod, type AuditLogFn, type AuthUser, type DefineAdminRouteSpec, type DefineFeatureSpec, type PermissionCatalogEntry, type PermissionChecker, type PermissionDenialContext, type PermissionString, type SegmentPath, _resetPermissionCatalog, clearFeaturePermissions, combineAdminRoutes, defineAdminRoute, defineFeature, emitPermissionDenied, getPermissionCatalog, isGatedRoute, permissionDeniedResponse, registerPermission, safeAudit };
+//# sourceMappingURL=index.d.mts.map