@oktis-works/plugin-runtime 0.6.1 → 0.7.1

package/dist/http.js

@@ -0,0 +1,314 @@
+// @oktis-works/plugin-runtime - api.http: cliente HTTP externo anti-SSRF
+//
+// Item 4 do plugin-parity-plan (+ Item 16 egress isolation). Camadas:
+//
+//   1. allowlist `httpPolicy.allowHosts` do manifesto (quando declarada);
+//   2. apenas scheme http/https;
+//   3. DNS pre-validation per HOP — EVERY resolved IP must be
+//      public (blocks RFC1918, loopback, link-local 169.254.169.254 =
+//      metadata de cloud, CGNAT, multicast, ULA/link-local IPv6);
+//   4. DNS pinning: o dispatcher (undici Agent) conecta exatamente no IP
+//      validado (elimina a janela de DNS rebinding entre lookup e connect);
+//   5. `manual` redirects with re-validation on every hop (max 3);
+//   6. timeout por tentativa e teto de corpo;
+//   7. retries only on network errors/5xx (GET/HEAD by default).
+//
+// Fail-closed: DNS that fails or resolves to a non-public IP NEVER lets the
+// request through, even if the runtime fetch ignored the dispatcher (Bun).
+import { promises as dnsPromises } from 'node:dns';
+import { Agent } from 'undici';
+import { PERMISSIONS } from '@oktis-works/plugin-sdk';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+export const MAX_TIMEOUT_MS = 60_000;
+export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+export const MAX_BODY_BYTES = 50 * 1024 * 1024;
+export const MAX_REDIRECTS = 3;
+/** Erro de api.http com flag de retentativa. */
+export class HttpError extends Error {
+    retriable;
+    constructor(message, retriable) {
+        super(message);
+        this.retriable = retriable;
+        this.name = 'HttpError';
+    }
+}
+/** Is the IPv4 publicly routable? Fail-closed on any special/reserved range. */
+export function isPublicIpv4(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return false;
+    const octets = parts.map((part) => Number(part));
+    if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255))
+        return false;
+    const a = octets[0] ?? 0;
+    const b = octets[1] ?? 0;
+    const c = octets[2] ?? 0;
+    if (a === 0)
+        return false; // 0.0.0.0/8 "este host"
+    if (a === 10)
+        return false; // RFC1918
+    if (a === 127)
+        return false; // loopback
+    if (a === 169 && b === 254)
+        return false; // link-local = metadata cloud (169.254.169.254)
+    if (a === 172 && b >= 16 && b <= 31)
+        return false; // RFC1918
+    if (a === 192 && b === 168)
+        return false; // RFC1918
+    if (a === 100 && b >= 64 && b <= 127)
+        return false; // CGNAT RFC6598
+    if (a === 192 && b === 0 && c === 0)
+        return false; // RFC6890 IETF
+    if (a === 198 && (b === 18 || b === 19))
+        return false; // benchmark RFC2544
+    if (a >= 224)
+        return false; // multicast (224/4) + broadcast/reservado (240/4)
+    return true;
+}
+/** Is the IPv6 publicly routable? Fail-closed: only 2000::/3 (global unicast). */
+export function isPublicIpv6(ip) {
+    const bare = (ip.split('%')[0] ?? '').toLowerCase();
+    if (bare === '::' || bare === '::1')
+        return false;
+    // IPv4-mapped ::ffff:a.b.c.d → aplica as regras de IPv4
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(bare);
+    if (mapped?.[1])
+        return isPublicIpv4(mapped[1]);
+    // leading '::' compression outside mapped → special/deprecated → blocked
+    if (bare.startsWith('::'))
+        return false;
+    const firstBlock = bare.split(':')[0] ?? '';
+    if (firstBlock.includes('.'))
+        return false; // v4-suffix not handled above
+    const hextet = Number.parseInt(firstBlock, 16);
+    if (Number.isNaN(hextet))
+        return false;
+    // 2000::/3 = the only assigned global unicast block
+    return hextet >= 0x2000 && hextet <= 0x3fff;
+}
+/** Any non-public IP in the list → false. */
+export function isPublicIp(ip) {
+    return ip.includes(':') ? isPublicIpv6(ip) : isPublicIpv4(ip);
+}
+/** Picks the first public address (for pinning). Throws when none. */
+export function selectPublicAddresses(addresses) {
+    const safe = addresses.find((entry) => isPublicIp(entry.address));
+    if (!safe) {
+        throw new HttpError(`host resolves only to non-public address(es): ${addresses.map((entry) => entry.address).join(', ')}`, false);
+    }
+    return safe;
+}
+/**
+ * Manifest allowlist: exact entry or `*.suffix.com` (subdomains — the apex
+ * needs its own entry). Empty/absent list = any host (advertising is still
+ * guaranteed by IP validation).
+ */
+export function isAllowedHost(hostname, allowHosts) {
+    if (!allowHosts || allowHosts.length === 0)
+        return true;
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    return allowHosts.some((entry) => {
+        const pattern = entry.trim().toLowerCase();
+        if (!pattern)
+            return false;
+        if (pattern.startsWith('*.')) {
+            const suffix = pattern.slice(1); // ".sufixo.com"
+            return host.endsWith(suffix) && host.length > suffix.length;
+        }
+        return host === pattern;
+    });
+}
+const defaultResolver = async (hostname) => {
+    const bare = hostname.replace(/^\[|\]$/g, '');
+    const addresses = await dnsPromises.lookup(bare, { all: true, verbatim: true });
+    return addresses.map((entry) => ({ address: entry.address, family: entry.family }));
+};
+/**
+ * Lookup "puro" usado pelo undici Agent: resolve E valida no MESMO passo —
+ * the returned IP is exactly what the connection uses (real pinning, no
+ * de rebinding).
+ */
+export function createSafeLookup(resolve = defaultResolver) {
+    return (hostname, _options, callback) => {
+        resolve(hostname).then((addresses) => {
+            try {
+                const safe = selectPublicAddresses(addresses);
+                callback(null, safe.address, safe.family);
+            }
+            catch (error) {
+                callback(error);
+            }
+        }, (error) => {
+            callback(error);
+        });
+    };
+}
+let sharedAgent = null;
+/** Dispatcher compartilhado com lookup validado (pinning). */
+export function getSafeAgent() {
+    if (!sharedAgent) {
+        sharedAgent = new Agent({
+            connect: {
+                // Signature compatible with net.LookupFunction via a structural cast
+                lookup: createSafeLookup(),
+            },
+        });
+    }
+    return sharedAgent;
+}
+/** Validates a target before touching the network (scheme + allowlist + public DNS). */
+export async function validateTargetUrl(rawUrl, allowHosts) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new HttpError(`invalid URL: ${rawUrl}`, false);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new HttpError(`scheme not allowed: ${url.protocol}`, false);
+    }
+    if (!isAllowedHost(url.hostname, allowHosts)) {
+        throw new HttpError(`host "${url.hostname}" is not in httpPolicy.allowHosts`, false);
+    }
+    let addresses;
+    try {
+        addresses = await defaultResolver(url.hostname);
+    }
+    catch (error) {
+        throw new HttpError(`DNS resolution failed for ${url.hostname}: ${error instanceof Error ? error.message : String(error)}`, false);
+    }
+    if (addresses.length === 0) {
+        throw new HttpError(`no addresses for ${url.hostname}`, false);
+    }
+    // EVERY IP must be public (round-robin with one private IP is also blocked)
+    const unsafe = addresses.filter((entry) => !isPublicIp(entry.address));
+    if (unsafe.length > 0) {
+        throw new HttpError(`host ${url.hostname} resolves to non-public address(es): ${unsafe.map((entry) => entry.address).join(', ')}`, false);
+    }
+    return url;
+}
+async function readBodyCapped(response, maxBytes) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    await reader.cancel().catch(() => undefined);
+                    throw new HttpError(`response body exceeds limit of ${maxBytes} bytes`, false);
+                }
+                chunks.push(value);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const merged = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+    return merged.toString('utf8');
+}
+async function readResponse(response, maxBytes) {
+    const body = await readBodyCapped(response, maxBytes);
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+    });
+    return {
+        status: response.status,
+        ok: response.ok,
+        headers,
+        body,
+        json() {
+            return JSON.parse(body);
+        },
+    };
+}
+/** Executa a cadeia de redirects (cada hop revalidado) — 1 tentativa. */
+async function runRedirects(rawUrl, allowHosts, config) {
+    let currentUrl = rawUrl;
+    let method = config.method;
+    let body = config.body;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+        const target = await validateTargetUrl(currentUrl, allowHosts);
+        const fetchInit = {
+            method,
+            headers: config.headers,
+            body: method === 'GET' || method === 'HEAD' ? undefined : body,
+            redirect: 'manual',
+            signal: AbortSignal.timeout(config.timeoutMs),
+            // Node/undici: conecta no IP validado (pinning). Runtimes que ignoram
+            // `dispatcher` (Bun) remain protected by the pre-validation above.
+            dispatcher: getSafeAgent(),
+        };
+        const response = await fetch(target.toString(), fetchInit);
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (!location)
+                return readResponse(response, config.maxBytes);
+            if (hop === MAX_REDIRECTS) {
+                throw new HttpError(`too many redirects (max ${MAX_REDIRECTS})`, false);
+            }
+            // Libera o corpo do redirect sem consumir
+            await response.body?.cancel().catch(() => undefined);
+            currentUrl = new URL(location, target).toString();
+            if (response.status === 303 ||
+                ((response.status === 301 || response.status === 302) && method === 'POST')) {
+                method = 'GET';
+                body = undefined;
+            }
+            continue;
+        }
+        return readResponse(response, config.maxBytes);
+    }
+    throw new HttpError(`too many redirects (max ${MAX_REDIRECTS})`, false);
+}
+export function createHttpApi(config) {
+    async function request(rawUrl, options = {}) {
+        config.requirePermission(PERMISSIONS.HTTP_OUTBOUND);
+        const method = (options.method ?? 'GET').toUpperCase();
+        const timeoutMs = Math.min(Math.max(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 1), MAX_TIMEOUT_MS);
+        const maxBytes = Math.min(Math.max(options.maxBytes ?? DEFAULT_MAX_BYTES, 1), MAX_BODY_BYTES);
+        const retries = Math.min(Math.max(Math.floor(options.retries ?? (method === 'GET' || method === 'HEAD' ? 2 : 0)), 0), 3);
+        const attemptConfig = {
+            method,
+            headers: options.headers,
+            body: options.body,
+            timeoutMs,
+            maxBytes,
+        };
+        let lastError;
+        for (let attempt = 0; attempt <= retries; attempt += 1) {
+            try {
+                const response = await runRedirects(rawUrl, config.allowHosts, attemptConfig);
+                if (response.status >= 500 && attempt < retries) {
+                    lastError = new HttpError(`upstream ${response.status}`, true);
+                    await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
+                    continue;
+                }
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                const retriable = error instanceof HttpError ? error.retriable : true; // rede/timeout
+                if (!retriable || attempt >= retries)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    return {
+        request,
+        get: (url, options) => request(url, { ...options, method: 'GET' }),
+        post: (url, body, options) => request(url, { ...options, method: 'POST', body }),
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/i18n.d.ts

@@ -0,0 +1,16 @@
+import type { PluginManifest, PluginI18nApi } from '@oktis-works/plugin-sdk';
+/**
+ * Fallback chain for a locale: `pt-BR` → [`pt-BR`, `pt`, `en`];
+ * `en` → [`en`]; `fr` → [`fr`, `en`]. Duplicates removed.
+ */
+export declare function i18nFallbackChain(locale: string): string[];
+/** Replaces `{token}` placeholders with stringified params (missing → kept). */
+export declare function i18nInterpolate(template: string, params?: Record<string, unknown>): string;
+/**
+ * Loads manifest `locales[]` JSON files (flat key/value) into the plugin's
+ * i18n store. The filename defines the locale (`locales/pt-BR.json` →
+ * `pt-BR`). Malformed/out-of-tree files are skipped — never breaks boot.
+ * Returns the number of successfully loaded files.
+ */
+export declare function loadPluginLocales(pluginDir: string, manifest: PluginManifest, i18n: PluginI18nApi): Promise<number>;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAU1D;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAM1F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/i18n.js

@@ -0,0 +1,73 @@
+// @oktis-works/plugin-runtime - Plugin i18n helpers (Item 9 do plugin-parity-plan)
+//
+// Server-side translations for plugins:
+//   - `api.i18n.load(locale, bundle)` merges flat { key: string } bundles;
+//   - `api.i18n.translate(key, params?, locale?)` resolves through the
+//     fallback chain (requested locale → base language → 'en' → key) with
+//     {param} interpolation;
+//   - manifest `locales[]` JSON files (flat key/value) are loaded at boot.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Fallback chain for a locale: `pt-BR` → [`pt-BR`, `pt`, `en`];
+ * `en` → [`en`]; `fr` → [`fr`, `en`]. Duplicates removed.
+ */
+export function i18nFallbackChain(locale) {
+    const chain = [];
+    const push = (value) => {
+        if (value && !chain.includes(value))
+            chain.push(value);
+    };
+    push(locale);
+    const base = locale.split('-')[0];
+    if (base)
+        push(base);
+    push('en');
+    return chain;
+}
+/** Replaces `{token}` placeholders with stringified params (missing → kept). */
+export function i18nInterpolate(template, params) {
+    if (!params || typeof params !== 'object')
+        return template;
+    return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (match, token) => {
+        const value = params[token];
+        return value === undefined || value === null ? match : String(value);
+    });
+}
+/**
+ * Loads manifest `locales[]` JSON files (flat key/value) into the plugin's
+ * i18n store. The filename defines the locale (`locales/pt-BR.json` →
+ * `pt-BR`). Malformed/out-of-tree files are skipped — never breaks boot.
+ * Returns the number of successfully loaded files.
+ */
+export async function loadPluginLocales(pluginDir, manifest, i18n) {
+    const files = manifest.locales;
+    if (!Array.isArray(files) || files.length === 0)
+        return 0;
+    let loaded = 0;
+    for (const relative of files) {
+        if (typeof relative !== 'string' || relative.includes('..') || relative.startsWith('/'))
+            continue;
+        try {
+            const raw = await readFile(join(pluginDir, relative), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                continue;
+            const locale = relative.replace(/\.json$/, '').split('/').pop() ?? '';
+            if (!locale)
+                continue;
+            const bundle = {};
+            for (const [key, value] of Object.entries(parsed)) {
+                if (typeof value === 'string')
+                    bundle[key] = value;
+            }
+            i18n.load(locale, bundle);
+            loaded += 1;
+        }
+        catch {
+            // malformed locale file — skip (translation falls back to the key)
+        }
+    }
+    return loaded;
+}
+//# sourceMappingURL=i18n.js.map

package/dist/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { readPluginManifest, normalizePluginManifest } from './manifest.js';
 export type { ManifestSource, ReadManifestResult } from './manifest.js';
 export { HookRegistry, HookRegistryStore, getHookRegistry, getHookRegistryStore, setHookRegistry, setHookRegistryStore, setHookTenantResolver, getCurrentHookTenantId, } from './hook-registry.js';
 export type { AddHookOptions, AuditLogEntry, HookCallback } from './hook-registry.js';
-export { bootstrapPlugins, resetLoadedPlugins, listLoadedScopes, unloadScope, unloadTenant, getLoadedPluginRoutes } from './bootstrap.js';
+export { bootstrapPlugins, resetLoadedPlugins, listLoadedScopes, unloadScope, unloadTenant, getLoadedPluginRoutes, getLoadedPluginJobHandlers } from './bootstrap.js';
 export type { BootstrapPluginsOptions, BootstrapPluginsSql, PluginBootstrapResult, } from './bootstrap.js';
 export { createPluginApi, type PluginAPI, type PluginContext, type RouteDefinition, type TenantInfo, type UserInfo, type PluginApiDependencies, type PluginApiInternal, } from './plugin-api.js';
 export type { PluginFieldTypeManifest } from '@oktis-works/plugin-sdk';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAC5E,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC1I,YAAY,EACV,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,GACd,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAC5E,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AACtK,YAAY,EACV,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,GACd,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -2,7 +2,7 @@ export { PluginSandbox } from './sandbox.js';
 export { PluginLoader } from './loader.js';
 export { readPluginManifest, normalizePluginManifest } from './manifest.js';
 export { HookRegistry, HookRegistryStore, getHookRegistry, getHookRegistryStore, setHookRegistry, setHookRegistryStore, setHookTenantResolver, getCurrentHookTenantId, } from './hook-registry.js';
-export { bootstrapPlugins, resetLoadedPlugins, listLoadedScopes, unloadScope, unloadTenant, getLoadedPluginRoutes } from './bootstrap.js';
+export { bootstrapPlugins, resetLoadedPlugins, listLoadedScopes, unloadScope, unloadTenant, getLoadedPluginRoutes, getLoadedPluginJobHandlers } from './bootstrap.js';
 export { createPluginApi, } from './plugin-api.js';
 export { scopePluginCss, getPluginScopeAttribute, wrapWithPluginScope, lintPluginCss, } from './style-isolation.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE5E,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAM1I,OAAO,EACL,eAAe,GAQhB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,GACd,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE5E,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAMtK,OAAO,EACL,eAAe,GAQhB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,GACd,MAAM,sBAAsB,CAAC"}

package/dist/loader.d.ts

@@ -6,10 +6,18 @@ export interface DiscoveredPlugin {
 }
 export declare class PluginLoader {
     private pluginsDir;
+    private dependencyFailures;
     constructor(pluginsDir: string);
     discoverPlugins(): Promise<DiscoveredPlugin[]>;
     loadPlugin(manifest: PluginManifest, pluginPath: string): Promise<LoadedPlugin>;
     resolveDependencies(plugins: DiscoveredPlugin[]): DiscoveredPlugin[][];
+    getDependencyFailures(): Array<{
+        name: string;
+        error: string;
+    }>;
+    private propagateDependencyFailures;
+    private propagateBlockedDependencies;
+    private propagateDependencyFailuresOnce;
     topologicalSort(plugins: DiscoveredPlugin[], pluginMap: Map<string, DiscoveredPlugin>): string[];
     private visit;
     private groupByLevel;

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAS;gBAEf,UAAU,EAAE,MAAM;IAIxB,eAAe,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgB9C,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAuBrF,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,EAAE;IAMtE,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,MAAM,EAAE;IAYhG,OAAO,CAAC,KAAK;IAyBb,OAAO,CAAC,YAAY;IA2BpB,OAAO,CAAC,kBAAkB;YAYZ,YAAY;CAO3B"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAA6B;gBAE3C,UAAU,EAAE,MAAM;IAIxB,eAAe,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgB9C,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAyBrF,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,EAAE;IAuBtE,qBAAqB,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAI/D,OAAO,CAAC,2BAA2B;IAyBnC,OAAO,CAAC,4BAA4B;IAmBpC,OAAO,CAAC,+BAA+B;IAYvC,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,MAAM,EAAE;IAYhG,OAAO,CAAC,KAAK;IAyBb,OAAO,CAAC,YAAY;IA2BpB,OAAO,CAAC,kBAAkB;YAYZ,YAAY;CAc3B"}

package/dist/loader.js

@@ -1,10 +1,11 @@
-import { readdir } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { readdir, realpath } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
 import { satisfies, validRange } from 'semver';
 import { CMS_VERSION } from '@oktis-works/validation';
 import { readPluginManifest } from './manifest.js';
 export class PluginLoader {
     pluginsDir;
+    dependencyFailures = new Map();
     constructor(pluginsDir) {
         this.pluginsDir = resolve(pluginsDir);
     }
@@ -23,13 +24,15 @@ export class PluginLoader {
         return plugins;
     }
     async loadPlugin(manifest, pluginPath) {
-        // RULE-semver-compatibility: range compatibility.okcms deve satisfazer a versão do CMS
+        // RULE-semver-compatibility: the compatibility.okcms range must satisfy the CMS version
         const compat = manifest.compatibility?.okcms;
         if (typeof compat === 'string' && validRange(compat) && !satisfies(CMS_VERSION, compat)) {
-            throw new Error(`Plugin "${manifest.name}" requer OkCMS ${compat}, mas a versão atual é ${CMS_VERSION}`);
+            throw new Error(`Plugin "${manifest.name}" requires OkCMS ${compat}, but the current version is ${CMS_VERSION}`);
         }
-        const entryPath = resolve(join(pluginPath, manifest.main));
-        if (!entryPath.startsWith(this.pluginsDir)) {
+        const entryPath = await realpath(resolve(join(pluginPath, manifest.main)));
+        const pluginRoot = await realpath(this.pluginsDir);
+        const relativeEntry = relative(pluginRoot, entryPath);
+        if (relativeEntry.startsWith('..') || relativeEntry === '..' || relativeEntry.includes('\0')) {
             throw new Error(`Plugin entry point escapes plugins directory: ${manifest.main}`);
         }
         const mod = await import(entryPath);
@@ -42,16 +45,94 @@ export class PluginLoader {
         };
     }
     resolveDependencies(plugins) {
+        this.dependencyFailures.clear();
         const pluginMap = new Map(plugins.map(p => [p.manifest.name, p]));
-        const sorted = this.topologicalSort(plugins, pluginMap);
+        for (const plugin of plugins) {
+            for (const dependency of plugin.manifest.dependencies ?? []) {
+                const target = pluginMap.get(dependency.name);
+                if (!target) {
+                    if (dependency.optional)
+                        continue;
+                    this.dependencyFailures.set(plugin.manifest.name, `Plugin "${plugin.manifest.name}" requires missing dependency "${dependency.name}"`);
+                    continue;
+                }
+                const range = dependency.versionRange ?? dependency.version;
+                if (range && (!validRange(range) || !satisfies(target.manifest.version, range))) {
+                    this.dependencyFailures.set(plugin.manifest.name, `Plugin "${plugin.manifest.name}" requires ${dependency.name} ${range}, found ${target.manifest.version}`);
+                }
+            }
+        }
+        this.propagateDependencyFailures(plugins, pluginMap);
+        const eligible = plugins.filter((plugin) => !this.dependencyFailures.has(plugin.manifest.name));
+        const sorted = this.topologicalSort(eligible, new Map(eligible.map((plugin) => [plugin.manifest.name, plugin])));
         return this.groupByLevel(sorted, pluginMap);
     }
+    getDependencyFailures() {
+        return [...this.dependencyFailures.entries()].map(([name, error]) => ({ name, error }));
+    }
+    propagateDependencyFailures(plugins, pluginMap) {
+        this.propagateBlockedDependencies(plugins);
+        const state = new Map();
+        const stack = [];
+        const visit = (name) => {
+            if (this.dependencyFailures.has(name))
+                return;
+            if (state.get(name) === 'visited')
+                return;
+            if (state.get(name) === 'visiting') {
+                const start = stack.indexOf(name);
+                for (const cycleName of stack.slice(start)) {
+                    this.dependencyFailures.set(cycleName, `Circular dependency detected: ${cycleName}`);
+                }
+                return;
+            }
+            state.set(name, 'visiting');
+            stack.push(name);
+            for (const dependency of pluginMap.get(name)?.manifest.dependencies ?? [])
+                visit(dependency.name);
+            stack.pop();
+            state.set(name, 'visited');
+        };
+        for (const plugin of plugins)
+            visit(plugin.manifest.name);
+        this.propagateBlockedDependencies(plugins);
+    }
+    propagateBlockedDependencies(plugins) {
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const plugin of plugins) {
+                if (this.dependencyFailures.has(plugin.manifest.name))
+                    continue;
+                const dependency = (plugin.manifest.dependencies ?? []).find((candidate) => {
+                    return !candidate.optional && this.dependencyFailures.has(candidate.name);
+                });
+                if (!dependency)
+                    continue;
+                this.dependencyFailures.set(plugin.manifest.name, `Plugin "${plugin.manifest.name}" is blocked by failed dependency "${dependency.name}"`);
+                changed = true;
+            }
+        }
+    }
+    propagateDependencyFailuresOnce(plugins) {
+        for (const plugin of plugins) {
+            if (this.dependencyFailures.has(plugin.manifest.name))
+                continue;
+            const dependency = (plugin.manifest.dependencies ?? []).find((candidate) => {
+                return !candidate.optional && this.dependencyFailures.has(candidate.name);
+            });
+            if (dependency) {
+                this.dependencyFailures.set(plugin.manifest.name, `Plugin "${plugin.manifest.name}" is blocked by failed dependency "${dependency.name}"`);
+            }
+        }
+    }
     topologicalSort(plugins, pluginMap) {
         const visited = new Set();
         const visiting = new Set();
         const result = [];
         for (const plugin of plugins) {
-            this.visit(plugin.manifest.name, pluginMap, visited, visiting, result);
+            if (!this.dependencyFailures.has(plugin.manifest.name))
+                this.visit(plugin.manifest.name, pluginMap, visited, visiting, result);
         }
         return result;
     }
@@ -109,10 +190,17 @@ export class PluginLoader {
         return result.length > 0 ? result : [0];
     }
     async loadManifest(pluginPath) {
-        // Fonte única (WP6): `manifest.json` canônico vence `package.json` (npm).
+        // Single source (WP6): the canonical `manifest.json` wins over `package.json` (npm).
         // Antes a ordem era inversa — um plugin com ambos os arquivos era lido de
         // um jeito no loader e de outro no sync/CLI.
-        const { manifest } = await readPluginManifest(pluginPath);
+        // Runtime discovery is intentionally lenient: malformed declarations are
+        // allowed to reach bootstrap, where the plugin is isolated as a failed
+        // load instead of silently disappearing from runtime state. Installation
+        // and synchronization use strict validation separately.
+        const { manifest, issues } = await readPluginManifest(pluginPath);
+        if (!manifest && issues.length > 0) {
+            console.warn(`[plugins] rejected manifest in ${pluginPath}: ${issues.join('; ')}`);
+        }
         return manifest;
     }
 }