@cogenta/plugins 0.1.0

package/dist/host/worker-runner.js

@@ -0,0 +1,196 @@
+import { Worker } from 'node:worker_threads';
+import { CogentaError } from '@cogenta/core';
+import { resolveGrantedCapabilities } from '../permissions/resolve.js';
+/**
+ * The isolated worker boundary itself — "Tout plugin tiers s'exécute dans un
+ * worker séparé" (docs/lots/L7-extensibilite.md § Isolation). This is task
+ * 3's real deliverable: spawn a worker that cannot reach `fs`/`net`/`process`
+ * /env/secrets no matter what code runs inside it, talk to it over a real
+ * serialized message protocol, and kill it if it doesn't answer in time.
+ *
+ * What this does NOT build (deliberately, per the lot's own task split):
+ * the real capability-gated SDK object a plugin actually calls (task 4/5),
+ * or the full time/memory-limit-and-disable-with-alert policy (task 6) — the
+ * timeout below is the minimal, real mechanism this task's own tests need so
+ * a hostile or runaway plugin can't hang the process; task 6 owns the
+ * complete policy layer on top of it.
+ */
+const SANDBOX_ENTRY_URL = new URL('../guest/sandbox-entry.mjs', import.meta.url);
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_MAX_OLD_GENERATION_MB = 64;
+/**
+ * Node signals a `resourceLimits` heap-limit violation to the parent via the
+ * `Worker`'s `'error'` event, carrying a message from V8's own OOM reporting
+ * (observed shape: "Worker terminated due to reaching memory limit: JS heap
+ * out of memory") — never a distinct error class or a dedicated event type,
+ * so this is a real, deliberately narrow message-pattern match, not a guess
+ * at a documented API. Anything else that reaches `'error'`/a non-zero exit
+ * is classified `'crash'`: still real grounds to disable the plugin, just
+ * not a heap-limit violation specifically.
+ */
+function classifyFailure(message) {
+    return /heap|memory limit|out of memory/i.test(message) ? 'memory' : 'crash';
+}
+let nextRequestId = 1;
+/**
+ * Dispatches one real SDK call from the sandbox to its host-side handler
+ * (`./capabilities.js`) and reports the outcome back — the handler itself
+ * re-verifies the specific request (a domain, a storage key) against the
+ * specific granted capability parameters; this function only routes.
+ */
+async function handleSdkCall(message, handlers, grantedCapabilities, worker) {
+    const handler = handlers[message.method];
+    if (handler === undefined) {
+        const reply = {
+            type: 'sdk-error',
+            callId: message.callId,
+            message: `no host handler registered for "${message.method}"`,
+        };
+        worker.postMessage(reply);
+        return;
+    }
+    try {
+        const value = await handler(message.args, { grantedCapabilities });
+        const reply = { type: 'sdk-result', callId: message.callId, value };
+        worker.postMessage(reply);
+    }
+    catch (error) {
+        const reply = {
+            type: 'sdk-error',
+            callId: message.callId,
+            message: error instanceof Error ? error.message : String(error),
+        };
+        worker.postMessage(reply);
+    }
+}
+/**
+ * Runs `code` inside a fresh, isolated worker and reports the outcome.
+ * `code` is a classic (non-module) script body — the sandbox's real,
+ * documented restriction, not an accident: `vm.Script` without an
+ * `importModuleDynamically` callback refuses `import()`, and no `require`
+ * is ever injected into the sandbox, which is exactly what stops a plugin
+ * from reaching `node:fs`/`node:net` no matter which syntax it tries.
+ *
+ * A fresh `Worker` per call, not a pool — task 6 decides whether a
+ * long-lived, reusable worker (with the resource/time policy it owns) is
+ * worth the complexity; this task only needs a real, working isolation
+ * primitive to build on.
+ */
+export async function runIsolated(code, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const grantedCapabilities = options.grantedCapabilities ?? [];
+    const handlers = options.handlers ?? {};
+    const id = nextRequestId;
+    nextRequestId += 1;
+    const worker = new Worker(SANDBOX_ENTRY_URL, {
+        // Never inherit the host's environment — "n'a accès... ni aux variables
+        // d'environnement, ni aux secrets" is structural here, not a convention
+        // the plugin is merely asked to respect: an empty `env` means the
+        // worker's `process.env` (if it were even reachable, which it is not
+        // inside the vm sandbox either) genuinely has nothing in it.
+        env: {},
+        argv: [],
+        resourceLimits: {
+            maxOldGenerationSizeMb: options.maxOldGenerationSizeMb ?? DEFAULT_MAX_OLD_GENERATION_MB,
+            maxYoungGenerationSizeMb: 16,
+        },
+        stdout: false,
+        stderr: false,
+    });
+    return await new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void worker.terminate();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ ok: false, error: 'plugin worker timed out', reason: 'timeout' });
+        }, timeoutMs);
+        // `sdk-call` messages arrive zero or more times WHILE `code` runs, each
+        // one a real capability request that must be re-verified and executed
+        // host-side before the sandbox's own `await sdk.<ns>.<method>(...)` can
+        // resolve — this is the RPC loop the guest-side SDK methods (task 4)
+        // are built on. It stays a real `.on` listener, not `.once`, since a
+        // single run may call several SDK methods before finishing.
+        worker.on('message', (message) => {
+            if (message.type === 'result') {
+                finish({ ok: true, value: message.value });
+                return;
+            }
+            if (message.type === 'error') {
+                finish({ ok: false, error: message.message });
+                return;
+            }
+            void handleSdkCall(message, handlers, grantedCapabilities, worker);
+        });
+        worker.once('error', (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            finish({ ok: false, error: message, reason: classifyFailure(message) });
+        });
+        worker.once('exit', (exitCode) => {
+            if (exitCode !== 0) {
+                const message = `plugin worker exited with code ${exitCode}`;
+                finish({ ok: false, error: message, reason: 'crash' });
+            }
+        });
+        const request = { id, type: 'run', code, grantedCapabilities };
+        worker.postMessage(request);
+    });
+}
+/**
+ * The real entry point for actually running a resolved plugin — unlike
+ * `runIsolated`, which task 4 left accepting an externally-decided
+ * `grantedCapabilities` list as a placeholder, this computes that list
+ * itself via `resolveGrantedCapabilities` (task 5) from the plugin's real
+ * manifest and its real, persisted grants. A caller cannot bypass grant
+ * resolution by simply passing whatever capability list it wants — the only
+ * way a capability reaches the sandbox is a real row in the grant store.
+ *
+ * Task 6 adds the other two real gates the lot demands: a disabled plugin is
+ * refused BEFORE a worker is ever spawned (`PLUGIN_DISABLED`, not a silent
+ * no-op), and a timeout or memory-limit violation disables the plugin for
+ * every future run, not just the one that failed — "il ne peut pas faire
+ * tomber le CMS" is the isolation boundary's job (task 3); making sure it
+ * cannot even try again unsupervised is this task's.
+ */
+export async function runPlugin(manifest, code, grants, options) {
+    const alreadyDisabled = await options.disableStore.isDisabled(manifest.name);
+    if (alreadyDisabled !== null) {
+        throw new CogentaError({
+            code: 'PLUGIN_DISABLED',
+            message: `Plugin "${manifest.name}" is disabled (${alreadyDisabled.reason}, since ${alreadyDisabled.disabledAt}) and cannot be run.`,
+            hint: 'A human must explicitly re-enable this plugin before it can run again.',
+            details: { pluginName: manifest.name, reason: alreadyDisabled.reason },
+        });
+    }
+    const grantedCapabilities = resolveGrantedCapabilities(manifest, grants);
+    const result = await runIsolated(code, { ...options, grantedCapabilities });
+    if (!result.ok && (result.reason === 'timeout' || result.reason === 'memory')) {
+        await options.disableStore.disable(manifest.name, result.reason, result.error);
+        options.onPluginDisabled?.({
+            pluginName: manifest.name,
+            reason: result.reason,
+            at: new Date().toISOString(),
+            ...(result.error === undefined ? {} : { details: result.error }),
+        });
+    }
+    return result;
+}
+/** Throws instead of returning a discriminated failure — for call sites that want a plain success value or a real error. */
+export async function runIsolatedOrThrow(code, options) {
+    const result = await runIsolated(code, options);
+    if (result.ok)
+        return result.value;
+    throw new CogentaError({
+        code: result.error === 'plugin worker timed out'
+            ? 'PLUGIN_WORKER_TIMEOUT'
+            : 'PLUGIN_WORKER_RUNTIME_ERROR',
+        message: result.error ?? 'Plugin worker failed for an unknown reason.',
+        hint: 'Check the plugin code for an unhandled error, an infinite loop, or excessive memory use.',
+    });
+}
+//# sourceMappingURL=worker-runner.js.map

package/dist/host/worker-runner.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export type { CapabilityCallContext, CapabilityHandler } from './host/capabilities.js';
+export { createContentReadHandler, createHttpFetchHandler, createStorageReadHandler, createStorageWriteHandler, } from './host/capabilities.js';
+export type { IsolatedRunResult, PluginDisabledEvent, RunIsolatedOptions, RunPluginOptions, } from './host/worker-runner.js';
+export { runIsolated, runIsolatedOrThrow, runPlugin } from './host/worker-runner.js';
+export type { LoadPluginOptions, PluginSource, ResolvedPlugin } from './loader.js';
+export { loadPlugin, PLUGIN_MANIFEST_FILE_NAMES, resolveSignatureStatus } from './loader.js';
+export type { PluginBlockProvision, PluginCapabilityName, PluginManifest, PluginManifestIssue, PluginProvides, PluginRuntime, } from './manifest.js';
+export { definePlugin, PLUGIN_CAPABILITY_NAMES, PLUGIN_RUNTIMES, } from './manifest.js';
+export type { PluginCapabilityDescription, PluginCapabilityRisk, } from './permissions/describe.js';
+export { DESCRIBABLE_CAPABILITY_NAMES, describeCapability } from './permissions/describe.js';
+export type { PluginDisabledRecord, PluginDisableStore, PluginViolationReason, } from './permissions/disabled.js';
+export { createPluginDisableStore } from './permissions/disabled.js';
+export type { PluginGrant, PluginGrantStore } from './permissions/grants.js';
+export { createPluginGrantStore } from './permissions/grants.js';
+export { detectCapabilitiesNeedingApproval, resolveGrantedCapabilities, } from './permissions/resolve.js';
+export type { GrantedCapabilityReview, PendingCapabilityReview, } from './permissions/review.js';
+export { describePendingApproval, listGrantedCapabilities, revokeCapability, } from './permissions/review.js';
+export { ensurePluginTables, PERMISSION_TABLES } from './permissions/tables.js';
+export type { PluginRegistry, PluginRegistryOptions, PluginReviewDecision, PluginReviewResult, PluginSubmissionEntry, PluginSubmissionInput, PluginSubmissionStatus, } from './registries/plugins.js';
+export { createPluginRegistry } from './registries/plugins.js';
+export type { SkillRegistry, SkillReviewDecision, SkillReviewResult, SkillSubmissionEntry, SkillSubmissionInput, SkillSubmissionStatus, } from './registries/skills.js';
+export { createSkillRegistry } from './registries/skills.js';
+export type { SkinGallery, SkinGalleryEntry, SkinSubmissionInput, SkinSubmissionStatus, } from './registries/skins.js';
+export { createSkinGallery } from './registries/skins.js';
+export { ensureRegistryTables, REGISTRY_TABLES } from './registries/tables.js';
+export type { ThemeRegistry, ThemeRegistryEntry, ThemeRegistryOptions, ThemeSubmissionInput, ThemeSubmissionStatus, } from './registries/themes.js';
+export { createThemeRegistry } from './registries/themes.js';
+export type { SemverVersion } from './semver.js';
+export { compareVersions, parseVersion, satisfiesRange } from './semver.js';
+export type { SigningKeyPair } from './signing/keys.js';
+export { exportPrivateKey, exportPublicKey, generateSigningKeyPair } from './signing/keys.js';
+export { canonicalizeContent, canonicalizeManifest, signContent, signManifest, } from './signing/sign.js';
+export { readSignatureFile, TRUSTED_REGISTRY_PUBLIC_KEYS, verifyContentAgainstTrustedKeys, verifyContentSignature, verifyManifestSignature, verifyPluginSignature, } from './signing/verify.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,20 @@
+export { createContentReadHandler, createHttpFetchHandler, createStorageReadHandler, createStorageWriteHandler, } from './host/capabilities.js';
+export { runIsolated, runIsolatedOrThrow, runPlugin } from './host/worker-runner.js';
+export { loadPlugin, PLUGIN_MANIFEST_FILE_NAMES, resolveSignatureStatus } from './loader.js';
+export { definePlugin, PLUGIN_CAPABILITY_NAMES, PLUGIN_RUNTIMES, } from './manifest.js';
+export { DESCRIBABLE_CAPABILITY_NAMES, describeCapability } from './permissions/describe.js';
+export { createPluginDisableStore } from './permissions/disabled.js';
+export { createPluginGrantStore } from './permissions/grants.js';
+export { detectCapabilitiesNeedingApproval, resolveGrantedCapabilities, } from './permissions/resolve.js';
+export { describePendingApproval, listGrantedCapabilities, revokeCapability, } from './permissions/review.js';
+export { ensurePluginTables, PERMISSION_TABLES } from './permissions/tables.js';
+export { createPluginRegistry } from './registries/plugins.js';
+export { createSkillRegistry } from './registries/skills.js';
+export { createSkinGallery } from './registries/skins.js';
+export { ensureRegistryTables, REGISTRY_TABLES } from './registries/tables.js';
+export { createThemeRegistry } from './registries/themes.js';
+export { compareVersions, parseVersion, satisfiesRange } from './semver.js';
+export { exportPrivateKey, exportPublicKey, generateSigningKeyPair } from './signing/keys.js';
+export { canonicalizeContent, canonicalizeManifest, signContent, signManifest, } from './signing/sign.js';
+export { readSignatureFile, TRUSTED_REGISTRY_PUBLIC_KEYS, verifyContentAgainstTrustedKeys, verifyContentSignature, verifyManifestSignature, verifyPluginSignature, } from './signing/verify.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAA;AAO/B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAEpF,OAAO,EAAE,UAAU,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAS5F,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,eAAe,GAChB,MAAM,eAAe,CAAA;AAKtB,OAAO,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAM5F,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAEpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,EACL,iCAAiC,EACjC,0BAA0B,GAC3B,MAAM,0BAA0B,CAAA;AAKjC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAU/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAS9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAO5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAQ9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE3E,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAC7F,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,YAAY,GACb,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA"}

package/dist/loader.d.ts

@@ -0,0 +1,81 @@
+import { type PluginManifest } from './manifest.js';
+/**
+ * Where a resolved plugin came from — structural, not cosmetic: task 9
+ * (signing) and the permissions screen's "avertissement permanent" both key
+ * off this. A `local`/`git` plugin is allowed in development mode without a
+ * signature; a `registry` plugin is not.
+ */
+export type PluginSource = 'registry' | 'local' | 'git';
+/**
+ * Checked in order, mirroring `@cogenta/core`'s `CONFIG_FILE_NAMES`
+ * (`load-config.ts`) exactly — a plugin's manifest is a user-authored file
+ * loaded the same way `cogenta.config.mjs`/`cogenta.schema.mjs` already are,
+ * not a bespoke new mechanism.
+ */
+export declare const PLUGIN_MANIFEST_FILE_NAMES: readonly ['plugin.manifest.ts', 'plugin.manifest.mts', 'plugin.manifest.js', 'plugin.manifest.mjs'];
+export interface ResolvedPlugin {
+    readonly manifest: PluginManifest;
+    readonly source: PluginSource;
+    /** Absolute path to the package root that was resolved. */
+    readonly packageRoot: string;
+    /** Absolute path to the manifest file that was loaded. */
+    readonly manifestPath: string;
+    /** Whether `manifest.engine` is satisfied by `engineVersion` (`loadPlugin`'s option). */
+    readonly engineCompatible: boolean;
+    /**
+     * `true` only for a `local` (or, once resolvable, `git`) source: allowed
+     * to run unsigned, "en mode développement" — the real datum a later admin
+     * banner's "avertissement permanent" would render. A `registry` plugin is
+     * never dev mode: it either verified or `loadPlugin` already refused it.
+     */
+    readonly devMode: boolean;
+    /** `true` only when a `registry` plugin's signature was checked and matched a trusted key. Always `false` in dev mode — there was nothing to check. */
+    readonly signatureVerified: boolean;
+}
+export interface LoadPluginOptions {
+    /**
+     * Cogenta's own version, checked against `manifest.engine`. No real,
+     * meaningful Cogenta version exists anywhere yet (pre-alpha; the root
+     * `package.json` carries no `version` field, and every workspace package
+     * still uses the `0.0.0` placeholder) — `engineCompatible` is real and
+     * correctly computed against whatever is passed here, but until a real
+     * versioning scheme exists, pass a real Cogenta version explicitly when
+     * one exists; the default below is a placeholder that makes every plugin
+     * appear compatible, which is the honest behaviour of "no check exists
+     * yet" rather than a fabricated pass/fail.
+     */
+    readonly engineVersion?: string;
+    /**
+     * Base64 SPKI Ed25519 public keys this call trusts for `registry`-source
+     * signature verification. Defaults to `TRUSTED_REGISTRY_PUBLIC_KEYS`
+     * (`./signing/verify.js`) — empty until a real registry exists, so every
+     * `registry` plugin fails verification by default rather than trusting a
+     * placeholder key.
+     */
+    readonly trustedPublicKeys?: readonly string[];
+}
+/**
+ * `source: 'registry'` is where "## Signature" (docs/lots/L7-extensibilite.md)
+ * actually bites: "Une signature invalide bloque, sans possibilité de passer
+ * outre depuis l'interface." There is deliberately no parameter here that
+ * lets a caller force past a missing/invalid signature — the only way past
+ * this function is a real, matching signature, because the override this
+ * shape could otherwise offer is exactly what the lot's own line means by
+ * "sans possibilité de passer outre." `local`/`git` sources skip
+ * verification entirely, by design ("autorisé en mode développement"), and
+ * are reported back as `devMode: true` for a future admin banner to render
+ * as the "avertissement permanent" the lot also asks for.
+ */
+export declare function resolveSignatureStatus(source: PluginSource, manifest: PluginManifest, manifestPath: string, trustedPublicKeys: readonly string[]): Promise<{
+    readonly devMode: boolean;
+    readonly signatureVerified: boolean;
+}>;
+/**
+ * Resolves a plugin reference to its package root and source kind, loads
+ * and validates its manifest (via `definePlugin`), verifies its signature
+ * when required, and reports engine compatibility. Executes no plugin code
+ * beyond importing the manifest-declaring module — spawning a worker to run
+ * the plugin's actual runtime is task 3, not this one.
+ */
+export declare function loadPlugin(reference: string, options?: LoadPluginOptions): Promise<ResolvedPlugin>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAQjE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,KAAK,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,YACrC,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,CACb,CAAA;AAEV,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,uJAAuJ;IACvJ,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;CACpC;AA4ED,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC/C;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,SAAS,MAAM,EAAE,GACnC,OAAO,CAAC;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;CAAE,CAAC,CA0B7E;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAiCzB"}

package/dist/loader.js

@@ -0,0 +1,190 @@
+import { access, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { CogentaError } from '@cogenta/core';
+import { definePlugin } from './manifest.js';
+import { satisfiesRange } from './semver.js';
+import { readSignatureFile, TRUSTED_REGISTRY_PUBLIC_KEYS, verifyPluginSignature, } from './signing/verify.js';
+/**
+ * Checked in order, mirroring `@cogenta/core`'s `CONFIG_FILE_NAMES`
+ * (`load-config.ts`) exactly — a plugin's manifest is a user-authored file
+ * loaded the same way `cogenta.config.mjs`/`cogenta.schema.mjs` already are,
+ * not a bespoke new mechanism.
+ */
+export const PLUGIN_MANIFEST_FILE_NAMES = [
+    'plugin.manifest.ts',
+    'plugin.manifest.mts',
+    'plugin.manifest.js',
+    'plugin.manifest.mjs',
+];
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A git reference: `git+https://...`, a bare `https://...\.git`, or the
+ * `github:owner/repo` shorthand. Cloning it is a real network/filesystem
+ * operation this task deliberately does not build — "résolution" here means
+ * "recognise a git source and refuse honestly," not "implement a git
+ * client." A local checkout of a git-sourced plugin is loaded exactly like
+ * any other local path once it exists on disk.
+ */
+function isGitReference(reference) {
+    return (reference.startsWith('git+') ||
+        reference.startsWith('github:') ||
+        /^https?:\/\/.+\.git$/.test(reference));
+}
+function looksLikeLocalPath(reference) {
+    return reference.startsWith('.') || reference.startsWith('/') || isAbsolute(reference);
+}
+async function findManifestFile(packageRoot) {
+    for (const name of PLUGIN_MANIFEST_FILE_NAMES) {
+        const candidate = join(packageRoot, name);
+        if (await exists(candidate))
+            return candidate;
+    }
+    throw new CogentaError({
+        code: 'PLUGIN_MANIFEST_FILE_NOT_FOUND',
+        message: `No plugin manifest found in ${packageRoot}.`,
+        hint: `Add one of: ${PLUGIN_MANIFEST_FILE_NAMES.join(', ')}.`,
+        details: { packageRoot },
+    });
+}
+async function importManifest(manifestPath) {
+    let module;
+    try {
+        module = (await import(pathToFileURL(manifestPath).href));
+    }
+    catch (error) {
+        throw new CogentaError({
+            code: 'PLUGIN_MANIFEST_LOAD_FAILED',
+            message: `Could not load ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`,
+            hint: manifestPath.endsWith('.ts')
+                ? 'A TypeScript manifest needs a Node runtime that strips types (Node 22.18+). Use plugin.manifest.mjs on an older one.'
+                : 'Check the file for a syntax error, and that every import it uses is installed.',
+            cause: error,
+            details: { manifestPath },
+        });
+    }
+    if (module.default === undefined) {
+        throw new CogentaError({
+            code: 'PLUGIN_MANIFEST_EXPORT_INVALID',
+            message: `${manifestPath} has no default export.`,
+            hint: 'Export the manifest as the default: `export default definePlugin({ … })`.',
+            details: { manifestPath },
+        });
+    }
+    // `definePlugin` re-validates even though a well-formed manifest module
+    // already called it once at module-load time — a manifest file could
+    // export a plain object instead of calling `definePlugin` itself, and
+    // this is the only place that can catch that.
+    return definePlugin(module.default);
+}
+const NO_REAL_ENGINE_VERSION_YET = '0.0.0';
+/**
+ * `source: 'registry'` is where "## Signature" (docs/lots/L7-extensibilite.md)
+ * actually bites: "Une signature invalide bloque, sans possibilité de passer
+ * outre depuis l'interface." There is deliberately no parameter here that
+ * lets a caller force past a missing/invalid signature — the only way past
+ * this function is a real, matching signature, because the override this
+ * shape could otherwise offer is exactly what the lot's own line means by
+ * "sans possibilité de passer outre." `local`/`git` sources skip
+ * verification entirely, by design ("autorisé en mode développement"), and
+ * are reported back as `devMode: true` for a future admin banner to render
+ * as the "avertissement permanent" the lot also asks for.
+ */
+export async function resolveSignatureStatus(source, manifest, manifestPath, trustedPublicKeys) {
+    if (source !== 'registry') {
+        return { devMode: true, signatureVerified: false };
+    }
+    const signature = await readSignatureFile(manifestPath);
+    if (signature === null) {
+        throw new CogentaError({
+            code: 'PLUGIN_SIGNATURE_MISSING',
+            message: `Plugin "${manifest.name}" has no signature file at ${manifestPath}.sig.`,
+            hint: 'Registry plugins must be signed. Install from a local path for unsigned development use.',
+            details: { pluginName: manifest.name, manifestPath },
+        });
+    }
+    const verified = verifyPluginSignature(manifest, signature, trustedPublicKeys);
+    if (!verified) {
+        throw new CogentaError({
+            code: 'PLUGIN_SIGNATURE_INVALID',
+            message: `Plugin "${manifest.name}"'s signature does not match any trusted key.`,
+            hint: 'The package may be tampered with, or its signing key is not (yet) trusted by this installation.',
+            details: { pluginName: manifest.name, manifestPath },
+        });
+    }
+    return { devMode: false, signatureVerified: true };
+}
+/**
+ * Resolves a plugin reference to its package root and source kind, loads
+ * and validates its manifest (via `definePlugin`), verifies its signature
+ * when required, and reports engine compatibility. Executes no plugin code
+ * beyond importing the manifest-declaring module — spawning a worker to run
+ * the plugin's actual runtime is task 3, not this one.
+ */
+export async function loadPlugin(reference, options = {}) {
+    const engineVersion = options.engineVersion ?? NO_REAL_ENGINE_VERSION_YET;
+    const trustedPublicKeys = options.trustedPublicKeys ?? TRUSTED_REGISTRY_PUBLIC_KEYS;
+    if (isGitReference(reference)) {
+        throw new CogentaError({
+            code: 'PLUGIN_SOURCE_NOT_FOUND',
+            message: `Git-sourced plugins are not resolvable yet: "${reference}".`,
+            hint: 'Clone the repository locally and pass its local path instead.',
+            details: { reference },
+        });
+    }
+    const source = looksLikeLocalPath(reference) ? 'local' : 'registry';
+    const packageRoot = await resolvePackageRoot(reference, source);
+    const manifestPath = await findManifestFile(packageRoot);
+    const manifest = await importManifest(manifestPath);
+    const { devMode, signatureVerified } = await resolveSignatureStatus(source, manifest, manifestPath, trustedPublicKeys);
+    return {
+        manifest,
+        source,
+        packageRoot,
+        manifestPath,
+        engineCompatible: satisfiesRange(engineVersion, manifest.engine),
+        devMode,
+        signatureVerified,
+    };
+}
+async function resolvePackageRoot(reference, source) {
+    if (source === 'local') {
+        const stats = await stat(reference).catch(() => null);
+        if (stats === null || !stats.isDirectory()) {
+            throw new CogentaError({
+                code: 'PLUGIN_SOURCE_NOT_FOUND',
+                message: `No plugin directory at "${reference}".`,
+                hint: 'Check the path — it must be an existing directory.',
+                details: { reference },
+            });
+        }
+        return reference;
+    }
+    // A registry package name: resolved via Node's own ESM resolution, the
+    // same mechanism any other workspace/npm dependency uses — no bespoke
+    // registry client. `import.meta.resolve` throws `ERR_MODULE_NOT_FOUND` on
+    // a package that is not installed, which is exactly the failure this task
+    // needs to report.
+    try {
+        const resolvedUrl = import.meta.resolve(`${reference}/package.json`);
+        return dirname(fileURLToPath(resolvedUrl));
+    }
+    catch (error) {
+        throw new CogentaError({
+            code: 'PLUGIN_SOURCE_NOT_FOUND',
+            message: `Could not resolve plugin package "${reference}": ${error instanceof Error ? error.message : String(error)}`,
+            hint: 'Install the plugin package, or pass a local path instead.',
+            cause: error,
+            details: { reference },
+        });
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

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