@jchat/addon-sdk 1.0.0-alpha.3 → 1.0.0-alpha.31

package/dist/index.mjs

@@ -1,105 +1,5 @@
-//#region package.json
-var version = "1.0.0-alpha.3";
-//#endregion
-//#region src/contracts.ts
-/** Valid locations where an addon can be rendered within the Jchat layout. */
-const MOUNT_POINTS = {
-	/** Top of the main chat column */
-	CHAT_HEADER: "chat-header",
-	/** Below the main chat header, above messages */
-	CHAT_TOOLBAR: "chat-toolbar",
-	/** The persistent right-side sidebar */
-	CHAT_SIDEBAR: "chat-sidebar",
-	/** Top of the left sidebar (room list) */
-	SIDEBAR_TOP: "sidebar-top",
-	/** Bottom of the left sidebar */
-	SIDEBAR_BOTTOM: "sidebar-bottom",
-	/** Action list shown when clicking a user's avatar */
-	USER_POPOVER_ACTIONS: "user-popover-actions",
-	/** Menu shown when right-clicking a message */
-	MESSAGE_CONTEXT_MENU: "message-context-menu",
-	/** Floating overlay rendered on top of the message stream */
-	MESSAGE_FEED_OVERLAY: "message-feed-overlay",
-	/** Main admin dashboard area */
-	ADMIN_PANEL: "admin-panel",
-	/** User or site settings dashboard area */
-	SETTINGS_PANEL: "settings-panel",
-	/** The 'plus' (+) menu in the message composer */
-	CHAT_PLUS_MENU: "chat-plus-menu",
-	/** Custom tab in the emoji/gif selection panel */
-	EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab",
-	/** Full-screen or modal dialog specifically for TubeScan */
-	TUBESCAN_DIALOG: "tubescan-dialog"
-};
-//#endregion
-//#region src/index.ts
-/** 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() {
-	throw new Error("AddonSDK must be used within the Jchat host environment.");
-}
-/**
-* Access the host application's active icon pack. Returns the icon set matching the site's
-* configured icon pack preference.
-*
-* This function is a shell; the real implementation is provided by the Jchat host environment at
-* runtime.
-*
-* @example
-*   ;```tsx
-*   import { useIcons } from "@jchat/addon-sdk"
-*
-*   export default function MyAddon() {
-*     const { Icons } = useIcons()
-*     return <Icons.Send className="size-5" />
-*   }
-*   ```
-*/
-function useIcons() {
-	throw new Error("useIcons 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;
-}
-//#endregion
-export { MOUNT_POINTS, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonSDK, useIcons };
+import { _ as createMongoAbility, a as useAddonSDK, c as useAddonInfiniteQuery, d as useAddonSettings, f as useQueryClient, g as createAddonAbility, h as authorizeResourceOwnership, i as getAddonSdkVersion, l as useAddonMutation, m as ForbiddenError, n as defineAddonManifest, o as verifyAddonEntitlement, p as AbilityBuilder, r as defineAddonServer, s as createMockAddonServerContext, t as AddonPipelineAbortError, u as useAddonQuery, v as hasPermission, y 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";
+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, useAddonSettings, useLocale, useQueryClient, useTranslation, validateAddonManifest, verifyAddonEntitlement };

package/dist/signing.d.mts

@@ -0,0 +1,2 @@
+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";
+export { ADDON_ID_PATTERN, COMPATIBILITY_RANGE_PATTERN, MAX_ADDON_ARCHIVE_BYTES, assertSafeRelativePath, canonicalManifest, createCanonicalAddonDigest, isCompatibilityRange, sortValue, validateAddonManifest };

package/dist/signing.mjs

@@ -0,0 +1,136 @@
+import crypto from "node:crypto";
+import * as path$1 from "node:path";
+//#region src/signing.ts
+/** Maximum allowable byte size for an addon distribution package archive (25 MB). */
+const MAX_ADDON_ARCHIVE_BYTES = 26214400;
+/**
+* Regular expression validating canonical kebab-case addon identifiers (e.g. `'soundboard'`,
+* `'dj-drop'`).
+*/
+const ADDON_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Regular expression validating semver compatibility range expressions. */
+const COMPATIBILITY_RANGE_PATTERN = /^[0-9A-Za-z*^~<>=|.\-\s]+$/;
+/**
+* Asserts that a file path is a safe relative path, guarding against directory traversal attacks,
+* absolute paths, and non-canonical path separators.
+*
+* @param value - File path string to validate.
+* @param label - Human-friendly field name used for error reporting (e.g. `'Logo path'`, `'Bundle
+*   path'`).
+* @throws {Error} When the path is empty, absolute, contains backslashes, or attempts directory
+*   traversal (`..`).
+*/
+function assertSafeRelativePath(value, label) {
+	if (!value || path$1.isAbsolute(value) || value.includes("\\") || value.split("/").includes("..")) throw new Error(`${label} must be a safe relative path`);
+}
+/**
+* Type guard verifying whether a value is a valid semver compatibility range string.
+*
+* @param value - The value to check.
+* @returns `true` if the value is a valid non-empty compatibility range string within 64
+*   characters.
+*/
+function isCompatibilityRange(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= 64 && COMPATIBILITY_RANGE_PATTERN.test(value);
+}
+/**
+* Recursively sorts object keys alphabetically to guarantee deterministic, reproducible JSON
+* serialization for cryptographic signing and digest hashing.
+*
+* @param value - Object, array, or primitive value to normalize.
+* @returns A new structure with sorted keys at all nested levels.
+*/
+function sortValue(value) {
+	if (Array.isArray(value)) return value.map(sortValue);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).toSorted(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortValue(child)]));
+	return value;
+}
+/**
+* Produces a canonical JSON string representation of an {@link AddonManifest} with signature fields
+* blanked and all object keys sorted deterministically.
+*
+* @param manifest - Addon manifest to canonicalize.
+* @returns Normalized JSON string representation.
+*/
+function canonicalManifest(manifest) {
+	const copy = structuredClone(manifest);
+	if (copy.signature) {
+		copy.signature.digest = "";
+		copy.signature.value = "";
+	}
+	return JSON.stringify(sortValue(copy));
+}
+/**
+* Computes a deterministic SHA-256 cryptographic digest across an addon archive's contents.
+*
+* Files are processed in lexicographical path order, with manifest signature fields sanitized,
+* producing a tamper-evident package fingerprint.
+*
+* @param manifest - Addon manifest containing metadata and package declarations.
+* @param files - Array of files packaged inside the addon archive.
+* @returns Hex-encoded SHA-256 digest string.
+*/
+function createCanonicalAddonDigest(manifest, files) {
+	const hash = crypto.createHash("sha256");
+	const sortedFiles = [...files].toSorted((left, right) => left.path.localeCompare(right.path));
+	for (const file of sortedFiles) {
+		hash.update(file.path);
+		hash.update("\0");
+		hash.update(file.path === "manifest.json" ? canonicalManifest(manifest) : file.contents);
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+/**
+* Validates the structural, security, and schema integrity of an {@link AddonManifest}.
+*
+* Enforces:
+*
+* - Valid kebab-case identifier (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
+* - Non-empty name and version constraints
+* - Host and SDK compatibility range specifications
+* - Distribution model classification (`'free'` or `'commercial'`)
+* - Logo image file format (`.svg`, `.png`, `.webp`) and safe relative path
+* - Safe relative paths for client/server bundles, migrations, and seeds
+* - Canonical permission namespacing prefix (`addon.<id>.*`)
+*
+* @param manifest - Addon manifest object to inspect and validate.
+* @throws {Error} When any validation rule or security constraint is violated.
+*/
+function validateAddonManifest(manifest) {
+	if (!manifest.id || manifest.id.length > 40 || !ADDON_ID_PATTERN.test(manifest.id)) throw new Error("Manifest id must contain only lowercase letters, numbers, and hyphens");
+	if (!manifest.name || manifest.name.length > 120) throw new Error("Manifest name is invalid");
+	if (!manifest.version || String(manifest.version).length > 64) throw new Error("Manifest version is invalid");
+	if (!isCompatibilityRange(manifest.compatibility?.jchat) || !isCompatibilityRange(manifest.compatibility?.addonSdk)) throw new Error("Manifest must declare valid JChat and addon SDK compatibility ranges");
+	if (manifest.distribution !== void 0 && manifest.distribution !== "free" && manifest.distribution !== "commercial") throw new Error("Manifest distribution must be either 'free' or 'commercial'");
+	if (!manifest.logo || typeof manifest.logo !== "string" || !manifest.logo.trim()) throw new Error("Manifest logo is required");
+	const cleanLogo = manifest.logo.replace(/^\.\//, "");
+	assertSafeRelativePath(cleanLogo, "Logo path");
+	const logoExt = path$1.extname(cleanLogo).toLowerCase();
+	if (![
+		".svg",
+		".png",
+		".webp"
+	].includes(logoExt)) throw new Error("Manifest logo must be an SVG, PNG, or WebP image file");
+	const references = [manifest.frontend?.bundle, manifest.server?.bundle].filter((value) => Boolean(value));
+	for (const reference of references) assertSafeRelativePath(reference, "Bundle path");
+	for (const migration of manifest.server?.migrations ?? []) {
+		assertSafeRelativePath(migration, "Migration path");
+		if (!migration.startsWith("migrations/") || !migration.endsWith(".sql")) throw new Error("Migration paths must point to migrations/*.sql");
+	}
+	for (const seed of manifest.server?.seeds ?? []) {
+		assertSafeRelativePath(seed, "Seed path");
+		if (!seed.startsWith("seeds/") || !seed.endsWith(".json")) throw new Error("Seed paths must point to seeds/*.json");
+	}
+	const databaseFiles = [...manifest.server?.migrations ?? [], ...manifest.server?.seeds ?? []];
+	if (new Set(databaseFiles).size !== databaseFiles.length) throw new Error("Manifest database file paths must be unique");
+	const addonPermPrefix = `addon.${manifest.id}.`;
+	const declaredPerms = [
+		...manifest.accessPermission ? [manifest.accessPermission] : [],
+		...manifest.permissions ?? [],
+		...manifest.permissionDefinitions?.map((d) => d.name) ?? []
+	];
+	for (const perm of declaredPerms) if (!perm.startsWith(addonPermPrefix)) throw new Error(`Addon permission '${perm}' must start with '${addonPermPrefix}' prefix to prevent permission collisions`);
+}
+//#endregion
+export { ADDON_ID_PATTERN, COMPATIBILITY_RANGE_PATTERN, MAX_ADDON_ARCHIVE_BYTES, assertSafeRelativePath, canonicalManifest, createCanonicalAddonDigest, isCompatibilityRange, sortValue, validateAddonManifest };

package/dist/signing2.d.mts

@@ -0,0 +1,76 @@
+import { l as AddonManifest, r as AddonArchiveFile } from "./contracts2.mjs";
+//#region src/signing.d.ts
+/** Maximum allowable byte size for an addon distribution package archive (25 MB). */
+declare const MAX_ADDON_ARCHIVE_BYTES: number;
+/**
+ * Regular expression validating canonical kebab-case addon identifiers (e.g. `'soundboard'`,
+ * `'dj-drop'`).
+ */
+declare const ADDON_ID_PATTERN: RegExp;
+/** Regular expression validating semver compatibility range expressions. */
+declare const COMPATIBILITY_RANGE_PATTERN: RegExp;
+/**
+ * Asserts that a file path is a safe relative path, guarding against directory traversal attacks,
+ * absolute paths, and non-canonical path separators.
+ *
+ * @param value - File path string to validate.
+ * @param label - Human-friendly field name used for error reporting (e.g. `'Logo path'`, `'Bundle
+ *   path'`).
+ * @throws {Error} When the path is empty, absolute, contains backslashes, or attempts directory
+ *   traversal (`..`).
+ */
+declare function assertSafeRelativePath(value: string, label: string): void;
+/**
+ * Type guard verifying whether a value is a valid semver compatibility range string.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid non-empty compatibility range string within 64
+ *   characters.
+ */
+declare function isCompatibilityRange(value: unknown): value is string;
+/**
+ * Recursively sorts object keys alphabetically to guarantee deterministic, reproducible JSON
+ * serialization for cryptographic signing and digest hashing.
+ *
+ * @param value - Object, array, or primitive value to normalize.
+ * @returns A new structure with sorted keys at all nested levels.
+ */
+declare function sortValue(value: unknown): unknown;
+/**
+ * Produces a canonical JSON string representation of an {@link AddonManifest} with signature fields
+ * blanked and all object keys sorted deterministically.
+ *
+ * @param manifest - Addon manifest to canonicalize.
+ * @returns Normalized JSON string representation.
+ */
+declare function canonicalManifest(manifest: AddonManifest): string;
+/**
+ * Computes a deterministic SHA-256 cryptographic digest across an addon archive's contents.
+ *
+ * Files are processed in lexicographical path order, with manifest signature fields sanitized,
+ * producing a tamper-evident package fingerprint.
+ *
+ * @param manifest - Addon manifest containing metadata and package declarations.
+ * @param files - Array of files packaged inside the addon archive.
+ * @returns Hex-encoded SHA-256 digest string.
+ */
+declare function createCanonicalAddonDigest(manifest: AddonManifest, files: readonly AddonArchiveFile[]): string;
+/**
+ * Validates the structural, security, and schema integrity of an {@link AddonManifest}.
+ *
+ * Enforces:
+ *
+ * - Valid kebab-case identifier (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
+ * - Non-empty name and version constraints
+ * - Host and SDK compatibility range specifications
+ * - Distribution model classification (`'free'` or `'commercial'`)
+ * - Logo image file format (`.svg`, `.png`, `.webp`) and safe relative path
+ * - Safe relative paths for client/server bundles, migrations, and seeds
+ * - Canonical permission namespacing prefix (`addon.<id>.*`)
+ *
+ * @param manifest - Addon manifest object to inspect and validate.
+ * @throws {Error} When any validation rule or security constraint is violated.
+ */
+declare function validateAddonManifest(manifest: AddonManifest): void;
+//#endregion
+export { canonicalManifest as a, sortValue as c, assertSafeRelativePath as i, validateAddonManifest as l, COMPATIBILITY_RANGE_PATTERN as n, createCanonicalAddonDigest as o, MAX_ADDON_ARCHIVE_BYTES as r, isCompatibilityRange as s, ADDON_ID_PATTERN as t };