@jchat/addon-sdk 1.0.0-alpha.27 → 1.0.0-alpha.28

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @jchat/addon-sdk
 
+## 1.0.0-alpha.28
+
+### Minor Changes
+
+- Add ABAC ability evaluator, authorizeOwnership, and AddonCan UI primitive
+
+### Patch Changes
+
+- Add comprehensive JSDoc documentation and align context ownership helpers
+
+- Bumped `@jchat/*` dependencies:
+  - [`ui@1.0.0-alpha.27`](https://github.com/jchatcloud/jchat/releases/tag/ui@v1.0.0-alpha.27)
+
 ## 1.0.0-alpha.27
 
 ### Patch Changes

package/dist/cli.d.mts

@@ -1,35 +1,54 @@
 import { l as AddonManifest } from "./contracts2.mjs";
 import { InlineConfig } from "vite";
 //#region src/cli.d.ts
-/** Options for resolving addon build configuration. */
+/** Options supplied to {@link resolveAddonBuildConfig} to configure addon compilation and bundling. */
 export interface AddonCliOptions {
+  /** Root workspace directory of the addon (defaults to `process.cwd()`). */
   rootDir?: string;
+  /** CLI execution subcommand (`'build'`, `'dev'`, or `'help'`). */
   command?: "build" | "dev" | "help";
+  /** Vite compilation mode (`'production'` or `'development'`). */
   mode?: "production" | "development";
+  /** Whether to watch filesystem changes and trigger live rebuilds. */
   watch?: boolean;
+  /**
+   * Whether to bundle distribution artifacts into an installation `.zip` archive upon build
+   * completion.
+   */
   zip?: boolean;
+  /** Optional PEM/PKCS8 private key string used to cryptographically sign the distribution archive. */
   signingPrivateKey?: string;
 }
 /**
- * Automatically loads the addon manifest from `src/manifest.ts`, `src/manifest.js`, or
- * `src/manifest.json`.
+ * Dynamically loads and validates the addon manifest from standard file locations:
+ * `src/manifest.ts`, `src/manifest.js`, `src/manifest.mjs`, or `src/manifest.json`.
  *
- * @param rootDir - Root directory of the addon workspace.
- * @returns Parsed {@link AddonManifest}.
+ * @param rootDir - Root directory path of the addon package.
+ * @returns A promise resolving to the parsed {@link AddonManifest}.
+ * @throws {Error} When no manifest file can be found in the `src/` directory.
  */
 export declare function loadAddonManifest(rootDir: string): Promise<AddonManifest>;
 /**
- * Resolves the full Vite configuration for building a JChat addon, merging user custom configs if
- * present.
+ * Resolves and composes the complete Vite configuration for compiling a JChat addon.
  *
- * @param options - CLI build options.
- * @returns Fully merged {@link InlineConfig} for Vite.
+ * Automatically integrates:
+ *
+ * - Tailwind CSS Vite compiler plugin
+ * - Core JChat Addon plugin (`jchatAddon`) with asset bundling and signing
+ * - Custom user Vite configurations (`vite.config.{ts,js,mjs,cjs}`) with deduplication
+ *
+ * @param options - Configuration options for the build pipeline.
+ * @returns A promise resolving to the fully merged {@link InlineConfig} for Vite.
  */
 export declare function resolveAddonBuildConfig(options?: AddonCliOptions): Promise<InlineConfig>;
 /**
- * Main CLI handler for `jchat-addon`.
+ * Main CLI entry point handler for the `jchat-addon` binary command.
+ *
+ * Parses command-line arguments, configures build parameters (mode, watch, zip packaging), resolves
+ * configuration via {@link resolveAddonBuildConfig}, and executes the Vite build lifecycle.
  *
- * @param args - CLI arguments (defaults to `process.argv.slice(2)`).
+ * @param args - CLI arguments array (defaults to `process.argv.slice(2)`).
+ * @returns A promise that resolves when compilation or dev server starts.
  */
 export declare function runAddonCli(args?: string[]): Promise<void>;
 //#endregion

package/dist/cli.mjs

@@ -5,6 +5,14 @@ import tailwindcss from "@tailwindcss/vite";
 import { pathToFileURL } from "node:url";
 import { build, loadConfigFromFile, mergeConfig } from "vite";
 //#region src/cli.ts
+/**
+* Recursively inspects a Vite plugin configuration to determine whether a plugin with the specified
+* name is already registered.
+*
+* @param plugins - Vite plugin or array/nested tree of plugins.
+* @param name - Target plugin identifier name to locate (e.g. `'jchat-addon'`).
+* @returns `true` if the plugin is registered, `false` otherwise.
+*/
 function hasPlugin(plugins, name) {
 	if (!plugins) return false;
 	if (Array.isArray(plugins)) return plugins.some((p) => hasPlugin(p, name));
@@ -12,11 +20,12 @@ function hasPlugin(plugins, name) {
 	return false;
 }
 /**
-* Automatically loads the addon manifest from `src/manifest.ts`, `src/manifest.js`, or
-* `src/manifest.json`.
+* Dynamically loads and validates the addon manifest from standard file locations:
+* `src/manifest.ts`, `src/manifest.js`, `src/manifest.mjs`, or `src/manifest.json`.
 *
-* @param rootDir - Root directory of the addon workspace.
-* @returns Parsed {@link AddonManifest}.
+* @param rootDir - Root directory path of the addon package.
+* @returns A promise resolving to the parsed {@link AddonManifest}.
+* @throws {Error} When no manifest file can be found in the `src/` directory.
 */
 async function loadAddonManifest(rootDir) {
 	const existingPath = [
@@ -36,11 +45,16 @@ async function loadAddonManifest(rootDir) {
 	throw new Error(`Could not find addon manifest in ${rootDir}/src (expected manifest.ts or manifest.json)`);
 }
 /**
-* Resolves the full Vite configuration for building a JChat addon, merging user custom configs if
-* present.
+* Resolves and composes the complete Vite configuration for compiling a JChat addon.
 *
-* @param options - CLI build options.
-* @returns Fully merged {@link InlineConfig} for Vite.
+* Automatically integrates:
+*
+* - Tailwind CSS Vite compiler plugin
+* - Core JChat Addon plugin (`jchatAddon`) with asset bundling and signing
+* - Custom user Vite configurations (`vite.config.{ts,js,mjs,cjs}`) with deduplication
+*
+* @param options - Configuration options for the build pipeline.
+* @returns A promise resolving to the fully merged {@link InlineConfig} for Vite.
 */
 async function resolveAddonBuildConfig(options = {}) {
 	const rootDir = path.resolve(options.rootDir || process.cwd());
@@ -83,9 +97,13 @@ async function resolveAddonBuildConfig(options = {}) {
 	return baseConfig;
 }
 /**
-* Main CLI handler for `jchat-addon`.
+* Main CLI entry point handler for the `jchat-addon` binary command.
+*
+* Parses command-line arguments, configures build parameters (mode, watch, zip packaging), resolves
+* configuration via {@link resolveAddonBuildConfig}, and executes the Vite build lifecycle.
 *
-* @param args - CLI arguments (defaults to `process.argv.slice(2)`).
+* @param args - CLI arguments array (defaults to `process.argv.slice(2)`).
+* @returns A promise that resolves when compilation or dev server starts.
 */
 async function runAddonCli(args = process.argv.slice(2)) {
 	let command = "build";

package/dist/contracts2.d.mts

@@ -173,6 +173,7 @@ interface AddonRequestUser {
   id: string;
   permissions?: string[];
   siteId?: string;
+  isOwner?: boolean;
 }
 /** Standard attachment contract for chat messages and addon file attachments. */
 interface AddonAttachment {

package/dist/index.mjs

@@ -1,196 +1,5 @@
+import { _ as hasPermission, a as useAddonSDK, c as useAddonInfiniteQuery, d as useQueryClient, f as AbilityBuilder, g as createMongoAbility, h as createAddonAbility, i as getAddonSdkVersion, l as useAddonMutation, m as authorizeResourceOwnership, n as defineAddonManifest, o as verifyAddonEntitlement, p as ForbiddenError, r as defineAddonServer, s as createMockAddonServerContext, t as AddonPipelineAbortError, u as useAddonQuery, v as subject } from "./src.mjs";
 import { HOST_LOCALES, MOUNT_POINTS } from "./contracts.mjs";
 import { i as useTranslation, n as createTranslator, r as useLocale, t as LocaleContext } from "./i18n.mjs";
 import { ADDON_ID_PATTERN, COMPATIBILITY_RANGE_PATTERN, MAX_ADDON_ARCHIVE_BYTES, assertSafeRelativePath, canonicalManifest, createCanonicalAddonDigest, isCompatibilityRange, sortValue, validateAddonManifest } from "./signing.mjs";
-import { createMockAddonServerContext } from "./testing.mjs";
-import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-//#region package.json
-var version = "1.0.0-alpha.26";
-//#endregion
-//#region src/query.ts
-/**
-* Perform a declarative, cached GET request using the host's shared React Query instance.
-* Automatically injects authentication headers and prefixes addon paths.
-*
-* @example
-*   ;```tsx
-*   const { data, isLoading } = useAddonQuery<{ polls: Poll[] }>({
-*     path: "/polls",
-*     queryKey: [siteId]
-*   })
-*   ```
-*/
-function useAddonQuery(options) {
-	const sdk = useAddonSDK();
-	const { path, queryKey = [], queryFn, ...queryOptions } = options;
-	const effectiveKey = path !== void 0 ? [path, ...queryKey] : queryKey;
-	const effectiveFn = queryFn ?? (() => {
-		if (!path) throw new Error("useAddonQuery requires either a `path` or a custom `queryFn`");
-		return sdk.api.get(path);
-	});
-	return useQuery({
-		...queryOptions,
-		queryKey: effectiveKey,
-		queryFn: effectiveFn
-	});
-}
-/**
-* Perform a paginated or infinite scrolling request using the host's shared React Query instance.
-*
-* @example
-*   ;```tsx
-*   const { data, fetchNextPage, hasNextPage } = useAddonInfiniteQuery<GifResponse, Error, number>({
-*   path: (page) => `/trending?offset=${page * 20}`,
-*   initialPageParam: 0,
-*   getNextPageParam: (lastPage, allPages) => (lastPage.hasMore ? allPages.length : undefined)
-*   })
-*   ```
-*/
-function useAddonInfiniteQuery(options) {
-	const sdk = useAddonSDK();
-	const { path, queryKey = [], queryFn, ...infiniteOptions } = options;
-	const effectiveKey = [typeof path === "string" ? path : "infinite", ...queryKey];
-	const effectiveFn = queryFn ?? (async (context) => {
-		const pageParam = context.pageParam;
-		const resolvedPath = typeof path === "function" ? path(pageParam) : path;
-		if (!resolvedPath) throw new Error("useAddonInfiniteQuery requires either a `path` or a custom `queryFn`");
-		return sdk.api.get(resolvedPath);
-	});
-	return useInfiniteQuery({
-		...infiniteOptions,
-		queryKey: effectiveKey,
-		queryFn: effectiveFn
-	});
-}
-/**
-* Perform a declarative mutation using the host's shared React Query instance. Automatically
-* executes the request and can invalidate specified query keys upon success.
-*
-* @example
-*   ;```tsx
-*   const { mutate, isPending } = useAddonMutation<Poll, CreatePollInput>({
-*     path: "/polls",
-*     method: "POST",
-*     invalidateQueries: [["/polls"]],
-*     onSuccess: () => sdk.toast("Poll created!", "success")
-*   })
-*   ```
-*/
-function useAddonMutation(options) {
-	const sdk = useAddonSDK();
-	const queryClient = useQueryClient();
-	const { path, method = "POST", invalidateQueries = [], mutationFn, onSuccess, ...mutationOptions } = options;
-	const effectiveFn = mutationFn ?? (async (variables) => {
-		const resolvedPath = typeof path === "function" ? path(variables) : path ?? "";
-		if (!resolvedPath) throw new Error("useAddonMutation requires a valid 'path' or 'mutationFn'.");
-		if (method === "PUT") return sdk.api.put(resolvedPath, variables);
-		if (method === "DELETE") return sdk.api.delete(resolvedPath);
-		return sdk.api.post(resolvedPath, variables);
-	});
-	return useMutation({
-		...mutationOptions,
-		mutationFn: effectiveFn,
-		onSuccess: async (...args) => {
-			if (invalidateQueries.length > 0) await Promise.all(invalidateQueries.map((key) => queryClient.invalidateQueries({ queryKey: key })));
-			if (onSuccess) await onSuccess(...args);
-		}
-	});
-}
-//#endregion
-//#region src/index.ts
-/**
-* @jchat/addon-sdk
-*
-*   Lightweight SDK for Jchat addon developers. Provides TypeScript types for addon props, manifest
-*   schema, and host API access. This package is always EXTERNALISED from addon bundles — the host
-*   app provides the runtime implementation.
-*/
-/** Standard error thrown or handled when an addon message pipeline hook aborts sending. */
-var AddonPipelineAbortError = class extends Error {
-	code;
-	reason;
-	constructor(error) {
-		super(error.reason || error.code);
-		this.name = "AddonPipelineAbortError";
-		this.code = error.code;
-		this.reason = error.reason;
-	}
-};
-/** Define a manifest with full validation-friendly typing while preserving literal values. */
-function defineAddonManifest(manifest) {
-	return manifest;
-}
-/** Define a typed server factory without widening its addon database interface. */
-function defineAddonServer(factory) {
-	return factory;
-}
-/**
-* Access the host application's SDK. Provides authenticated API access, toast notifications, and
-* navigation.
-*
-* This function is a shell; the real implementation is provided by the Jchat host environment at
-* runtime.
-*
-* @example
-*   ;```tsx
-*   import { useAddonSDK } from "@jchat/addon-sdk"
-*
-*   export default function MyAddon({ mountPoint }: AddonProps) {
-*     const sdk = useAddonSDK()
-*
-*     const handleClick = async () => {
-*       const data = await sdk.api.get("/trending")
-*       sdk.toast("Fetched trending posts!", "success")
-*     }
-*   }
-*   ```
-*/
-function useAddonSDK() {
-	const hostUseAddonSDK = typeof window !== "undefined" ? window.__JCHAT_EXTERNALS__?.JchatAddonSDK?.useAddonSDK : void 0;
-	if (hostUseAddonSDK && hostUseAddonSDK !== useAddonSDK) return hostUseAddonSDK();
-	throw new Error("AddonSDK must be used within the Jchat host environment.");
-}
-/**
-* Get the version of the addon SDK. This is useful for checking compatibility with the host
-* application.
-*
-* @example
-*   ;```tsx
-*   import { getAddonSdkVersion } from "@jchat/addon-sdk"
-*
-*   console.log(getAddonSdkVersion())
-*   ```
-*
-* @returns
-*/
-function getAddonSdkVersion() {
-	return version;
-}
-/**
-* Verifies purchase entitlement and identity integrity for commercial addons. Throws an error if
-* the addon fails entitlement verification or if its manifest ID has been tampered with to
-* impersonate another addon.
-*
-* @example
-*   ;```ts
-*   export default ({ verifyEntitlement, db, t }: AddonServerContext, app: AddonApp) => {
-*     verifyAddonEntitlement("tubescanpro", verifyEntitlement)
-*     return app.get("/trending", async () => { ... })
-*   }
-*   ```
-*
-* @param addonId - The canonical addon ID defined by the publisher (e.g. 'tubescanpro')
-* @param target - Either the `verifyEntitlement` function from context or the `AddonServerContext`
-*   object itself
-* @returns True if valid
-* @throws Error if entitlement verification fails
-*/
-function verifyAddonEntitlement(addonId, target) {
-	const verifyFn = typeof target === "function" ? target : target?.verifyEntitlement;
-	if (verifyFn) {
-		if (!verifyFn(addonId)) throw new Error(`addon_entitlement_verification_failed:${addonId}`);
-		return true;
-	}
-	return true;
-}
-//#endregion
-export { ADDON_ID_PATTERN, AddonPipelineAbortError, COMPATIBILITY_RANGE_PATTERN, HOST_LOCALES, LocaleContext, MAX_ADDON_ARCHIVE_BYTES, MOUNT_POINTS, assertSafeRelativePath, canonicalManifest, createCanonicalAddonDigest, createMockAddonServerContext, createTranslator, defineAddonManifest, defineAddonServer, getAddonSdkVersion, isCompatibilityRange, sortValue, useAddonInfiniteQuery, useAddonMutation, useAddonQuery, useAddonSDK, useLocale, useQueryClient, useTranslation, validateAddonManifest, verifyAddonEntitlement };
+export { ADDON_ID_PATTERN, AbilityBuilder, AddonPipelineAbortError, COMPATIBILITY_RANGE_PATTERN, ForbiddenError, HOST_LOCALES, LocaleContext, MAX_ADDON_ARCHIVE_BYTES, MOUNT_POINTS, assertSafeRelativePath, authorizeResourceOwnership, canonicalManifest, createAddonAbility, createCanonicalAddonDigest, createMockAddonServerContext, createMongoAbility, createTranslator, defineAddonManifest, defineAddonServer, getAddonSdkVersion, hasPermission, isCompatibilityRange, sortValue, subject, useAddonInfiniteQuery, useAddonMutation, useAddonQuery, useAddonSDK, useLocale, useQueryClient, useTranslation, validateAddonManifest, verifyAddonEntitlement };

package/dist/index2.d.mts

@@ -1,9 +1,115 @@
 import { i as IconPack, n as IconComponent, r as IconName } from "./types.mjs";
 import { _ as HOST_LOCALES, a as AddonChatMessage, b as MountPoint, c as AddonDistribution, d as AddonRequestUser, f as AddonRuntimeLog, g as AddonUser, h as AddonRuntimeLogSource, i as AddonAttachment, l as AddonManifest, m as AddonRuntimeLogLevel, n as ActiveAddonFrontend, o as AddonCommandDefinition, p as AddonRuntimeLogFilter, r as AddonArchiveFile, s as AddonCommandParameter, t as ActiveAddon, u as AddonPermissionDefinition, v as HostLocale, y as MOUNT_POINTS } from "./contracts2.mjs";
 import { a as canonicalManifest, c as sortValue, i as assertSafeRelativePath, l as validateAddonManifest, n as COMPATIBILITY_RANGE_PATTERN, o as createCanonicalAddonDigest, r as MAX_ADDON_ARCHIVE_BYTES, s as isCompatibilityRange, t as ADDON_ID_PATTERN } from "./signing2.mjs";
+import { AbilityBuilder, MongoAbility, createMongoAbility, subject } from "@casl/ability";
 import { InfiniteData, MutationFunction, QueryFunction, QueryFunctionContext, QueryKey, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryResult, useQueryClient } from "@tanstack/react-query";
 import { Elysia, t } from "elysia";
 import { ColumnType, Generated, Insertable, JSONColumnType, Kysely, Selectable, Updateable } from "kysely";
+//#region src/permissions.d.ts
+/**
+ * Standard forbidden exception thrown when an actor lacks required permissions or fails ownership
+ * checks.
+ */
+export declare class ForbiddenError extends Error {
+  readonly status = 403;
+  readonly code = "FORBIDDEN";
+  /**
+   * Initializes a new ForbiddenError instance.
+   *
+   * @param message - User-friendly error message detailing the authorization failure.
+   */
+  constructor(message?: string);
+}
+/**
+ * Authorization scope granted when accessing or mutating a resource:
+ *
+ * - `"own"`: Actor is the author/owner possessing the `.own` permission (or platform owner).
+ * - `"any"`: Actor is an administrator/moderator overriding ownership via the `.any` permission.
+ */
+export type ResourceOwnershipScope = "own" | "any";
+/** Configuration payload supplied to {@link authorizeResourceOwnership}. */
+export interface ResourceOwnershipInput {
+  /** Unique identifier of the authenticated user performing the action. */
+  actorId: string;
+  /** Array of effective permission strings held by the actor in the current tenancy context. */
+  actorPermissions: string[];
+  /** Unique identifier of the user who owns or created the target resource. */
+  ownerId: string;
+  /**
+   * Permission string required if the actor is the resource owner (e.g.
+   * `'addon.pollwise.close.own'`).
+   */
+  ownPermission: string;
+  /**
+   * Permission string required if the actor is mutating another user's resource (e.g.
+   * `'addon.pollwise.close.any'`).
+   */
+  anyPermission: string;
+  /**
+   * Human-readable entity noun used in error messages (e.g. `"poll"`, `"story"`, `"comment"`).
+   * Defaults to `"resource"`.
+   */
+  resourceLabel?: string;
+  /**
+   * Optional factory function creating a custom error instance on authorization denial. Defaults to
+   * {@link ForbiddenError}.
+   */
+  errorFactory?: (message: string) => Error;
+  /**
+   * Whether the actor possesses site owner / super admin status, granting unconditional bypass.
+   * Defaults to `false`.
+   */
+  isOwner?: boolean;
+}
+/**
+ * Checks whether an actor holds a specific permission with wildcard support.
+ *
+ * Evaluation rules:
+ *
+ * 1. Exact match (`'addon.pollwise.close.own'` matches `'addon.pollwise.close.own'`).
+ * 2. Global wildcard (`'*'` grants all actions).
+ * 3. Segment wildcards (`'addon.pollwise.*'` grants `'addon.pollwise.close.own'`).
+ *
+ * @param userPermissions - Array of permissions possessed by the user.
+ * @param required - Permission string required for the requested action.
+ * @returns `true` if the user is granted the required permission, `false` otherwise.
+ */
+export declare function hasPermission(userPermissions: string[], required: string): boolean;
+/**
+ * Evaluates Attribute-Based Access Control (ABAC) ownership rules to prevent Broken Object-Level
+ * Authorization (BOLA / IDOR) vulnerabilities.
+ *
+ * Resolution flow:
+ *
+ * 1. **Site Owner Bypass**: If `isOwner === true` or holding `'*'`, access is granted unconditionally.
+ * 2. **Author Ownership**: If `actorId === ownerId` and actor holds `ownPermission`, grants `"own"`.
+ * 3. **Moderator Override**: If actor holds `anyPermission`, grants `"any"`.
+ * 4. **Denial**: Throws an error generated by `errorFactory` (defaults to {@link ForbiddenError}).
+ *
+ * @param input - Ownership parameters, actor credentials, and required permissions.
+ * @returns The resolved {@link ResourceOwnershipScope} (`"own"` or `"any"`).
+ * @throws {ForbiddenError} When the actor lacks required ownership or moderator privileges.
+ */
+export declare function authorizeResourceOwnership({ actorId, actorPermissions, ownerId, ownPermission, anyPermission, resourceLabel, errorFactory, isOwner: actorIsOwner }: ResourceOwnershipInput): ResourceOwnershipScope;
+/** CASL MongoAbility contract for Addon entities and attribute evaluation. */
+export type AddonAbility = MongoAbility<[string, string | Record<string, unknown>]>;
+/**
+ * Creates a CASL Ability instance for an addon actor with automated permission convention mapping
+ * and optional custom rule extensions.
+ *
+ * Convention mapping:
+ *
+ * - Global `'*'` or `isOwner: true` $\rightarrow$ `can('manage', 'all')`
+ * - `*.any` (e.g. `'addon.pollwise.close.any'`) $\rightarrow$ `can('close', 'all')`
+ * - `*.own` (e.g. `'addon.pollwise.close.own'`) $\rightarrow$ `can('close', 'all', { userId: actor.id
+ *   })`
+ *
+ * @param actor - Authenticated request user context.
+ * @param defineRules - Optional callback to register custom CASL ability rules.
+ * @returns A frozen CASL {@link AddonAbility} instance.
+ */
+export declare function createAddonAbility(actor: AddonRequestUser | null | undefined, defineRules?: (builder: AbilityBuilder<AddonAbility>) => void): AddonAbility;
+//#endregion
 //#region src/i18n.d.ts
 export type HostLanguage = HostLocale;
 export type AddonTranslationDictionary = Record<string, unknown>;
@@ -152,26 +258,57 @@ export declare function useAddonInfiniteQuery<TData = unknown, TError = Error, T
 export declare function useAddonMutation<TData = unknown, TVariables = unknown, TError = Error, TContext = unknown>(options: UseAddonMutationOptions<TData, TVariables, TError, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;
 //#endregion
 //#region src/testing.d.ts
+/** Configuration options supplied to {@link createMockAddonServerContext}. */
 export interface MockAddonServerContextOptions {
+  /** Simulated tenant site identifier (defaults to `'site_test_123'`). */
   siteId?: string;
+  /** Simulated addon configuration settings returned by `context.getConfig()`. */
   config?: Record<string, unknown>;
+  /** Simulated user profile returned by `context.getUser()` and `context.getUsers()`. */
   user?: Partial<AddonUser>;
+  /**
+   * Simulated commercial license entitlement status returned by `context.verifyEntitlement()`.
+   * Defaults to `true`.
+   */
   isEntitled?: boolean;
 }
+/** Inspection fixtures and mock context returned by {@link createMockAddonServerContext}. */
 export interface MockAddonContextResult {
+  /** The fully functioning mock {@link AddonServerContext} instance. */
   context: AddonServerContext;
+  /** Array capturing all events emitted via `context.emit()`, enabling assertions in unit tests. */
   emittedEvents: Array<{
     event: string;
     payload: unknown;
     target?: AddonServerEmitTarget;
   }>;
+  /** Array capturing all pipeline hooks registered via `context.pipeline.register()`. */
   registeredHooks: AddonPipelineHooks[];
+  /** In-memory Map of key-value cache entries written via `context.cache`. */
   cacheEntries: Map<string, unknown>;
+  /** In-memory Map of Redis Set collections written via `context.cache.setAdd()` / `setRemove()`. */
   cacheSets: Map<string, Set<string>>;
 }
 /**
- * Creates an in-memory, zero-dependency AddonServerContext mock for testing addon server factories
- * and pipeline hooks offline in CI without requiring live databases or Redis.
+ * Creates an in-memory, zero-dependency {@link AddonServerContext} mock for testing addon server
+ * routes, lifecycle handlers, and pipeline hooks offline in CI without requiring live database
+ * connections or Redis.
+ *
+ * Provides complete mock implementations of:
+ *
+ * - **Key-Value & Set Cache**: Supports `get`, `set` (with TTL simulation), `del`, `incr`, `expire`,
+ *   `ttl`, `setAdd`, `setRemove`, and `setMembers` with automatic tenant/addon namespacing.
+ * - **Sliding-Window Rate Limiting**: In-memory timestamp-bucket rate limiting via `consume`.
+ * - **Event Capturing**: Records emitted events in {@link MockAddonContextResult.emittedEvents} with
+ *   canonical `addon:<addonId>:<event>` prefixing.
+ * - **Pipeline Hook Registration**: Inspects registered hook stages and handlers.
+ * - **Fine-Grained ABAC & Ownership**: Enforces CASL `can` attribute queries and BOLA protection via
+ *   `authorizeOwnership`.
+ * - **License Entitlement**: Deterministic commercial entitlement verification.
+ *
+ * @param addonId - Unique identifier of the addon under test.
+ * @param options - Optional mock configuration parameters.
+ * @returns A {@link MockAddonContextResult} containing the mock context and inspection fixtures.
  */
 export declare function createMockAddonServerContext(addonId: string, options?: MockAddonServerContextOptions): MockAddonContextResult;
 //#endregion
@@ -371,10 +508,36 @@ export interface AddonServerContext<TDatabase = Record<string, Record<string, un
    * @returns True if valid, or false if entitlement is missing or invalid
    */
   verifyEntitlement?: (expectedAddonId?: string) => boolean;
+  /**
+   * Enforces resource ownership rules ('own' vs 'any' permissions). Prevents Broken Object-Level
+   * Authorization (BOLA/IDOR).
+   *
+   * @param params - The actor, owner ID, and permission requirements
+   * @returns "own" if the actor owns the resource, or "any" if granted via moderator/admin
+   *   privileges
+   * @throws ForbiddenError if neither condition is satisfied
+   */
+  authorizeOwnership: (params: {
+    actor: AddonRequestUser;
+    ownerId: string;
+    ownPermission: string;
+    anyPermission: string;
+    resourceLabel?: string;
+  }) => ResourceOwnershipScope;
+  /**
+   * Evaluates fine-grained Attribute-Based Access Control (ABAC) rules for custom addon entities.
+   *
+   * @param actor - The authenticated request user
+   * @param action - Action to perform (e.g. 'read', 'delete', 'close')
+   * @param subject - Entity name (e.g. 'poll', 'story', 'track')
+   * @param attributes - Resource attributes (e.g. { userId: poll.userId, status: 'open' })
+   * @returns True if allowed, false otherwise
+   */
+  can: (actor: AddonRequestUser | null | undefined, action: string, subject: string, attributes?: Record<string, unknown>) => boolean;
 }
 /**
  * Elysia app instance provided to addon server endpoints with Jchat macro metadata (e.g.
- * requirePermission) typed.
+ * requirePermission, requireOwnership) typed.
  */
 export type AddonApp = Elysia<"", {
   decorator: {};
@@ -391,6 +554,12 @@ export type AddonApp = Elysia<"", {
   standaloneSchema: {};
   macro: {
     requirePermission?: string | string[];
+    requireOwnership?: {
+      resolveOwnerId: (context: unknown) => string | Promise<string | null | undefined>;
+      ownPermission: string;
+      anyPermission: string;
+      resourceLabel?: string;
+    };
   };
   macroFn: {};
   parser: {};
@@ -653,4 +822,4 @@ export declare function verifyAddonEntitlement(addonId: string, target?: ((expec
   verifyEntitlement?: (expectedAddonId?: string) => boolean;
 }): boolean;
 //#endregion
-export { ADDON_ID_PATTERN, type ActiveAddon, type ActiveAddonFrontend, type AddonArchiveFile, type AddonAttachment, type AddonChatMessage, type AddonCommandDefinition, type AddonCommandParameter, type AddonDistribution, type AddonManifest, type AddonPermissionDefinition, type AddonRequestUser, type AddonRuntimeLog, type AddonRuntimeLogFilter, type AddonRuntimeLogLevel, type AddonRuntimeLogSource, type AddonUser, COMPATIBILITY_RANGE_PATTERN, type ColumnType, type Generated, HOST_LOCALES, type IconComponent, type IconName, type IconPack, type InfiniteData, type Insertable, type JSONColumnType, MAX_ADDON_ARCHIVE_BYTES, MOUNT_POINTS, type MountPoint, type QueryKey, type Selectable, type Updateable, assertSafeRelativePath, canonicalManifest, createCanonicalAddonDigest, isCompatibilityRange, sortValue, useQueryClient, validateAddonManifest };
+export { ADDON_ID_PATTERN, AbilityBuilder, type ActiveAddon, type ActiveAddonFrontend, type AddonArchiveFile, type AddonAttachment, type AddonChatMessage, type AddonCommandDefinition, type AddonCommandParameter, type AddonDistribution, type AddonManifest, type AddonPermissionDefinition, type AddonRequestUser, type AddonRuntimeLog, type AddonRuntimeLogFilter, type AddonRuntimeLogLevel, type AddonRuntimeLogSource, type AddonUser, COMPATIBILITY_RANGE_PATTERN, type ColumnType, type Generated, HOST_LOCALES, type IconComponent, type IconName, type IconPack, type InfiniteData, type Insertable, type JSONColumnType, MAX_ADDON_ARCHIVE_BYTES, MOUNT_POINTS, type MongoAbility, type MountPoint, type QueryKey, type Selectable, type Updateable, assertSafeRelativePath, canonicalManifest, createCanonicalAddonDigest, createMongoAbility, isCompatibilityRange, sortValue, subject, useQueryClient, validateAddonManifest };