myagentmemory 0.4.12 → 0.4.14

package/dist/plugin-bootstrap.js

@@ -0,0 +1,628 @@
+import { createHash, createPublicKey, randomUUID, verify } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { AGENT_MEMORY_PLUGIN_API_VERSION, isSafeBundlePath, validateBundleManifestV1, } from "./plugin-host.js";
+import { TemporaryPluginBackend } from "./plugin-service.js";
+export const OFFICIAL_BUNDLE_ID = "agentmemory.pro";
+export const OFFICIAL_PLUGIN_IDS = ["agentmemory.session-intelligence", "agentmemory.web-console"];
+const MISSING_ENTITLEMENT = {
+    plan: null,
+    state: "missing",
+    features: [],
+    capabilities: {},
+    reason: "No signed AgentMemory commercial entitlement is installed",
+};
+const OFFICIAL_PLUGINS = [
+    { id: OFFICIAL_PLUGIN_IDS[0], name: "Session Intelligence" },
+    { id: OFFICIAL_PLUGIN_IDS[1], name: "Web Console" },
+];
+const PACKAGE_MAX_BYTES = 64 * 1024 * 1024;
+const PACKAGE_MAX_EXPANDED_BYTES = 128 * 1024 * 1024;
+const PACKAGE_MAX_FILES = 10_000;
+const TEMPORARY_RELEASE_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEASefZFUVFy1EmvGbd0ckHZThmPgqQ3u9HCwZRReAZQW8=
+-----END PUBLIC KEY-----`;
+export class PluginBootstrapFailure extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "PluginBootstrapFailure";
+    }
+}
+export class UnavailablePluginBackend {
+    async getLocalEntitlement() {
+        return structuredClone(MISSING_ENTITLEMENT);
+    }
+    async resolveAccess() {
+        return {
+            kind: "unavailable",
+            entitlement: structuredClone(MISSING_ENTITLEMENT),
+            error: {
+                code: "service_not_configured",
+                message: "The AgentMemory commercial service is not configured in this build",
+            },
+        };
+    }
+    async listReleases() {
+        return [];
+    }
+    async downloadArtifact() {
+        throw new PluginBootstrapFailure("service_not_configured", "The AgentMemory commercial service is not configured in this build");
+    }
+    async getManagementAction() {
+        return null;
+    }
+}
+export class RejectingReleaseVerifier {
+    verifyRelease() {
+        throw new PluginBootstrapFailure("signing_keys_unavailable", "No commercial release signing keys are configured");
+    }
+}
+export class Ed25519ReleaseVerifier {
+    keys = new Map();
+    constructor(keys) {
+        for (const [keyId, key] of Object.entries(keys))
+            this.keys.set(keyId, createPublicKey(key));
+    }
+    verifyRelease(release) {
+        validateRelease(release);
+        const key = this.keys.get(release.signature.keyId);
+        if (!key)
+            throw new PluginBootstrapFailure("unknown_signing_key", "The release uses an unknown signing key");
+        const signature = decodeBase64Strict(release.signature.value, "release signature");
+        const valid = verify(null, releaseSigningPayload(release), key, signature);
+        if (!valid)
+            throw new PluginBootstrapFailure("signature_invalid", "The commercial release signature is invalid");
+    }
+}
+export class FilePluginInstallStore {
+    root;
+    constructor(root = getDefaultPluginInstallRoot()) {
+        this.root = path.resolve(root);
+    }
+    readReceipt(bundleId) {
+        validateId(bundleId, "bundle");
+        const receiptPath = this.receiptPath(bundleId);
+        if (!fs.existsSync(receiptPath))
+            return null;
+        const stat = fs.lstatSync(receiptPath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new PluginBootstrapFailure("receipt_invalid", "The plugin install receipt is not a regular file");
+        let receipt;
+        try {
+            receipt = JSON.parse(fs.readFileSync(receiptPath, "utf-8"));
+        }
+        catch {
+            throw new PluginBootstrapFailure("receipt_invalid", "The plugin install receipt is not valid JSON");
+        }
+        validateReceipt(receipt, bundleId);
+        return receipt;
+    }
+    hasInstalledBundle(receipt) {
+        try {
+            const directory = this.versionPath(receipt.bundleId, receipt.version);
+            const marker = path.join(directory, ".package-sha256");
+            const entrypoint = resolveManagedPath(directory, receipt.entrypoint);
+            return (fs.lstatSync(directory).isDirectory() &&
+                !fs.lstatSync(directory).isSymbolicLink() &&
+                fs.lstatSync(entrypoint).isFile() &&
+                !fs.lstatSync(entrypoint).isSymbolicLink() &&
+                fs.readFileSync(marker, "utf-8").trim() === receipt.packageSha256);
+        }
+        catch {
+            return false;
+        }
+    }
+    async install(packageBytes, release, healthCheck = defaultHealthCheck) {
+        validateRelease(release);
+        this.ensureRoot();
+        const releaseDigest = sha256(packageBytes);
+        if (release.size !== packageBytes.byteLength)
+            throw new PluginBootstrapFailure("artifact_size_mismatch", "The downloaded package size does not match its release");
+        if (release.packageSha256 !== releaseDigest)
+            throw new PluginBootstrapFailure("artifact_digest_mismatch", "The downloaded package digest does not match its release");
+        const lock = this.acquireLock();
+        const stagingDirectory = path.join(this.root, "staging", `${release.manifest.id}-${randomUUID()}`);
+        try {
+            const packageValue = decodePluginPackage(packageBytes);
+            if (JSON.stringify(packageValue.manifest) !== JSON.stringify(release.manifest))
+                throw new PluginBootstrapFailure("package_manifest_mismatch", "The package manifest does not match its release");
+            extractPackage(packageValue, stagingDirectory);
+            fs.writeFileSync(path.join(stagingDirectory, ".package-sha256"), `${releaseDigest}\n`, { mode: 0o600 });
+            await healthCheck(stagingDirectory, release);
+            const target = this.versionPath(release.manifest.id, release.manifest.version);
+            fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+            if (fs.existsSync(target)) {
+                const markerPath = path.join(target, ".package-sha256");
+                const targetStat = fs.lstatSync(target);
+                if (targetStat.isSymbolicLink() ||
+                    !targetStat.isDirectory() ||
+                    !fs.existsSync(markerPath) ||
+                    fs.readFileSync(markerPath, "utf-8").trim() !== releaseDigest)
+                    throw new PluginBootstrapFailure("version_conflict", "The target plugin version already exists with different contents");
+                removeManagedDirectory(this.root, stagingDirectory);
+            }
+            else {
+                fs.renameSync(stagingDirectory, target);
+            }
+            const previous = this.readReceipt(release.manifest.id);
+            const receipt = {
+                schemaVersion: 1,
+                bundleId: release.manifest.id,
+                version: release.manifest.version,
+                channel: release.manifest.channel,
+                pluginApi: AGENT_MEMORY_PLUGIN_API_VERSION,
+                entrypoint: release.manifest.entrypoint,
+                packageSha256: release.packageSha256,
+                installedAt: new Date().toISOString(),
+                ...(previous && previous.version !== release.manifest.version ? { previousVersion: previous.version } : {}),
+            };
+            this.writeReceipt(receipt);
+            return receipt;
+        }
+        finally {
+            if (fs.existsSync(stagingDirectory)) {
+                try {
+                    removeManagedDirectory(this.root, stagingDirectory);
+                }
+                catch {
+                    // Preserve the primary failure. Staging remains inert because no receipt references it.
+                }
+            }
+            this.releaseLock(lock);
+        }
+    }
+    uninstall(bundleId) {
+        validateId(bundleId, "bundle");
+        this.ensureRoot();
+        const lock = this.acquireLock();
+        try {
+            const receipt = this.readReceipt(bundleId);
+            if (!receipt)
+                return null;
+            const versions = path.join(this.root, "bundles", bundleId);
+            if (fs.existsSync(versions))
+                removeManagedDirectory(this.root, versions);
+            fs.unlinkSync(this.receiptPath(bundleId));
+            return receipt;
+        }
+        finally {
+            this.releaseLock(lock);
+        }
+    }
+    ensureRoot() {
+        ensureRegularDirectory(this.root, true);
+        ensureRegularDirectory(path.join(this.root, "receipts"));
+        ensureRegularDirectory(path.join(this.root, "staging"));
+        ensureRegularDirectory(path.join(this.root, "bundles"));
+    }
+    receiptPath(bundleId) {
+        return resolveManagedPath(this.root, `receipts/${bundleId}.json`);
+    }
+    versionPath(bundleId, version) {
+        validateId(bundleId, "bundle");
+        validateVersion(version);
+        return resolveManagedPath(this.root, `bundles/${bundleId}/${version}`);
+    }
+    writeReceipt(receipt) {
+        const target = this.receiptPath(receipt.bundleId);
+        const temporary = `${target}.tmp-${process.pid}-${randomUUID()}`;
+        fs.writeFileSync(temporary, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(temporary, target);
+    }
+    acquireLock() {
+        const lockPath = path.join(this.root, "install.lock");
+        try {
+            const descriptor = fs.openSync(lockPath, "wx", 0o600);
+            fs.writeFileSync(descriptor, `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`);
+            return { descriptor, path: lockPath };
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw new PluginBootstrapFailure("install_in_progress", "Another plugin installation is already in progress", true);
+            throw error;
+        }
+    }
+    releaseLock(lock) {
+        try {
+            fs.closeSync(lock.descriptor);
+        }
+        catch {
+            // Preserve the primary install result; a later command will report a retained lock.
+        }
+        try {
+            fs.unlinkSync(lock.path);
+        }
+        catch {
+            // Preserve the primary install result; a later command will report a retained lock.
+        }
+    }
+}
+export class PluginBootstrapV1 {
+    options;
+    platform;
+    architecture;
+    constructor(options) {
+        this.options = options;
+        this.platform = options.platform ?? process.platform;
+        this.architecture = options.architecture ?? process.arch;
+    }
+    async list() {
+        const receipt = this.validReceipt();
+        const entitlement = await this.options.backend.getLocalEntitlement();
+        const available = Boolean(receipt) && isEntitled(entitlement);
+        return this.result("plugin.list", receipt ? "current" : "not_installed", true, receipt, entitlement, {
+            plugins: OFFICIAL_PLUGINS.map((plugin) => ({
+                ...plugin,
+                installed: Boolean(receipt),
+                available,
+                entitlement: entitlement.state,
+            })),
+        });
+    }
+    async status(channel = "stable") {
+        const receipt = this.validReceipt();
+        const entitlement = await this.options.backend.getLocalEntitlement();
+        if (!receipt)
+            return this.result("plugin.status", "not_installed", true, null, entitlement);
+        if (!isEntitled(entitlement))
+            return this.result("plugin.status", entitlement.state === "expired" ? "renewal_required" : "unavailable", true, receipt, entitlement);
+        try {
+            const access = await this.options.backend.resolveAccess({
+                bundleId: OFFICIAL_BUNDLE_ID,
+                installedVersion: receipt.version,
+                channel,
+                allowAuthentication: false,
+            });
+            if (access.kind !== "granted")
+                return this.result("plugin.status", "current", true, receipt, entitlement);
+            const release = await this.selectRelease(channel, access.artifactGrant);
+            if (release && compareVersions(release.manifest.version, receipt.version) > 0)
+                return this.result("plugin.status", "update_available", true, receipt, entitlement);
+        }
+        catch {
+            // Status stays useful offline. Install/update surfaces the detailed service error.
+        }
+        return this.result("plugin.status", "current", true, receipt, entitlement);
+    }
+    async install(options = {}) {
+        return this.reconcile("plugin.install", true, options);
+    }
+    async update(options = {}) {
+        if (!this.validReceipt()) {
+            return this.failure("plugin.update", "not_installed", await this.options.backend.getLocalEntitlement(), "plugin_not_installed", "AgentMemory Pro is not installed; run `agent-memory plugin install` first");
+        }
+        return this.reconcile("plugin.update", false, options);
+    }
+    async uninstall() {
+        const entitlement = await this.options.backend.getLocalEntitlement();
+        const removed = this.options.store.uninstall(OFFICIAL_BUNDLE_ID);
+        if (!removed)
+            return this.result("plugin.uninstall", "not_installed", true, null, entitlement);
+        return this.result("plugin.uninstall", "uninstalled", true, removed, entitlement, { version: null });
+    }
+    async manage() {
+        const receipt = this.validReceipt();
+        const entitlement = await this.options.backend.getLocalEntitlement();
+        const nextAction = await this.options.backend.getManagementAction();
+        if (!nextAction)
+            return this.failure("plugin.manage", "unavailable", entitlement, "service_not_configured", "AgentMemory account management is not configured in this build", receipt);
+        return this.result("plugin.manage", receipt ? "current" : "not_installed", true, receipt, entitlement, {
+            nextAction,
+        });
+    }
+    async reconcile(command, allowAuthentication, options) {
+        const channel = options.channel ?? "stable";
+        const previous = this.validReceipt();
+        try {
+            const access = await this.options.backend.resolveAccess({
+                bundleId: OFFICIAL_BUNDLE_ID,
+                installedVersion: previous?.version,
+                channel,
+                allowAuthentication: allowAuthentication && options.allowAuthentication !== false,
+            });
+            if (access.kind === "auth_required" || access.kind === "renewal_required")
+                return this.result(command, access.kind, false, previous, access.entitlement, {
+                    nextAction: access.nextAction,
+                    error: {
+                        code: access.kind,
+                        message: access.nextAction.message ?? "User action is required before installation can continue",
+                    },
+                });
+            if (access.kind === "unavailable")
+                return this.result(command, "unavailable", false, previous, access.entitlement, { error: access.error });
+            const release = await this.selectRelease(channel, access.artifactGrant);
+            if (!release)
+                return this.failure(command, "unavailable", access.entitlement, "compatible_release_not_found", "No signed AgentMemory Pro release is compatible with this core and platform", previous);
+            if (previous &&
+                previous.version === release.manifest.version &&
+                this.options.store.hasInstalledBundle(previous))
+                return this.result(command, "current", true, previous, access.entitlement);
+            this.options.verifier.verifyRelease(release);
+            const packageBytes = await this.options.backend.downloadArtifact({
+                release,
+                artifactGrant: access.artifactGrant,
+            });
+            const installed = await this.options.store.install(packageBytes, release, this.options.healthCheck);
+            return this.result(command, previous ? "upgraded" : "installed", true, installed, access.entitlement, {
+                previousVersion: previous?.version ?? null,
+            });
+        }
+        catch (error) {
+            const failure = normalizeFailure(error);
+            return this.failure(command, "unavailable", await this.options.backend.getLocalEntitlement(), failure.code, failure.message, previous, failure.retryable);
+        }
+    }
+    async selectRelease(channel, artifactGrant) {
+        const releases = await this.options.backend.listReleases({
+            bundleId: OFFICIAL_BUNDLE_ID,
+            channel,
+            artifactGrant,
+        });
+        const compatible = [];
+        let verificationFailure = null;
+        for (const release of releases) {
+            try {
+                validateRelease(release);
+            }
+            catch {
+                continue;
+            }
+            if (release.manifest.id !== OFFICIAL_BUNDLE_ID ||
+                release.manifest.channel !== channel ||
+                release.manifest.pluginApi !== AGENT_MEMORY_PLUGIN_API_VERSION ||
+                (release.platform !== "any" && release.platform !== this.platform) ||
+                (release.architecture !== "any" && release.architecture !== this.architecture) ||
+                !supportsVersionRange(release.manifest.core, this.options.coreVersion))
+                continue;
+            try {
+                this.options.verifier.verifyRelease(release);
+                compatible.push(release);
+            }
+            catch (error) {
+                verificationFailure ??= normalizeFailure(error);
+            }
+        }
+        if (!compatible.length && verificationFailure)
+            throw verificationFailure;
+        return (compatible.sort((left, right) => compareVersions(right.manifest.version, left.manifest.version))[0] ?? null);
+    }
+    validReceipt() {
+        const receipt = this.options.store.readReceipt(OFFICIAL_BUNDLE_ID);
+        return receipt && this.options.store.hasInstalledBundle(receipt) ? receipt : null;
+    }
+    result(command, result, ok, receipt, entitlement, overrides = {}) {
+        return {
+            schemaVersion: 1,
+            command,
+            ok,
+            result,
+            bundle: receipt
+                ? {
+                    id: receipt.bundleId,
+                    previousVersion: overrides.previousVersion ?? receipt.previousVersion ?? null,
+                    version: overrides.version === undefined ? receipt.version : overrides.version,
+                    channel: receipt.channel,
+                }
+                : null,
+            entitlement: structuredClone(entitlement),
+            ...(overrides.plugins ? { plugins: overrides.plugins } : {}),
+            nextAction: overrides.nextAction ?? null,
+            ...(overrides.error ? { error: overrides.error } : {}),
+        };
+    }
+    failure(command, result, entitlement, code, message, receipt = null, retryable = false) {
+        return this.result(command, result, false, receipt, entitlement, {
+            error: { code, message, ...(retryable ? { retryable } : {}) },
+        });
+    }
+}
+export function createDefaultPluginBootstrap(coreVersion) {
+    const store = new FilePluginInstallStore();
+    const backend = new TemporaryPluginBackend({ root: store.root, coreVersion });
+    return new PluginBootstrapV1({
+        coreVersion,
+        backend,
+        verifier: new Ed25519ReleaseVerifier({ "agentmemory-temporary-2026-08": TEMPORARY_RELEASE_PUBLIC_KEY }),
+        store,
+        healthCheck: async (directory, release) => {
+            const { createInstalledBundleHealthCheck } = await import("./plugin-runtime.js");
+            await createInstalledBundleHealthCheck(coreVersion, backend, store.root)(directory, release);
+        },
+    });
+}
+export function getDefaultPluginInstallRoot() {
+    const override = process.env.AGENT_MEMORY_PLUGIN_DIR?.trim();
+    return path.resolve(override || path.join(os.homedir(), ".agent-memory", "system", "plugins"));
+}
+export function encodePluginPackage(packageValue) {
+    validatePackage(packageValue);
+    return Buffer.from(`${JSON.stringify(packageValue)}\n`, "utf-8");
+}
+export function releaseSigningPayload(release) {
+    return Buffer.from(JSON.stringify({
+        schemaVersion: release.schemaVersion,
+        manifest: release.manifest,
+        platform: release.platform,
+        architecture: release.architecture,
+        packageSha256: release.packageSha256,
+        size: release.size,
+    }), "utf-8");
+}
+export function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function compareVersions(left, right) {
+    const leftParts = parseVersion(left);
+    const rightParts = parseVersion(right);
+    for (let index = 0; index < 3; index++) {
+        if (leftParts[index] > rightParts[index])
+            return 1;
+        if (leftParts[index] < rightParts[index])
+            return -1;
+    }
+    return 0;
+}
+export function supportsVersionRange(range, version) {
+    const clauses = range.trim().split(/\s+/).filter(Boolean);
+    if (!clauses.length)
+        return false;
+    return clauses.every((clause) => {
+        const match = /^(>=|>|<=|<|=)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(clause);
+        if (!match)
+            return false;
+        const comparison = compareVersions(version, match[2]);
+        switch (match[1] ?? "=") {
+            case ">=":
+                return comparison >= 0;
+            case ">":
+                return comparison > 0;
+            case "<=":
+                return comparison <= 0;
+            case "<":
+                return comparison < 0;
+            default:
+                return comparison === 0;
+        }
+    });
+}
+function validateRelease(release) {
+    if (release.schemaVersion !== 1)
+        throw new PluginBootstrapFailure("release_invalid", "Unsupported release schema");
+    validateBundleManifestV1(release.manifest);
+    if (!release.platform.trim() || !release.architecture.trim())
+        throw new PluginBootstrapFailure("release_invalid", "Release platform metadata is incomplete");
+    if (!/^[a-f0-9]{64}$/.test(release.packageSha256))
+        throw new PluginBootstrapFailure("release_invalid", "Release package digest is invalid");
+    if (!Number.isSafeInteger(release.size) || release.size <= 0 || release.size > PACKAGE_MAX_BYTES)
+        throw new PluginBootstrapFailure("release_invalid", "Release package size is invalid");
+    if (release.signature.algorithm !== "ed25519" || !release.signature.keyId.trim() || !release.signature.value.trim())
+        throw new PluginBootstrapFailure("release_invalid", "Release signature metadata is invalid");
+}
+function decodePluginPackage(packageBytes) {
+    if (packageBytes.byteLength > PACKAGE_MAX_BYTES)
+        throw new PluginBootstrapFailure("package_too_large", "The plugin package exceeds the compressed-size limit");
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(packageBytes).toString("utf-8"));
+    }
+    catch {
+        throw new PluginBootstrapFailure("package_invalid", "The plugin package is not valid JSON");
+    }
+    validatePackage(value);
+    return value;
+}
+function validatePackage(value) {
+    if (value.schemaVersion !== 1)
+        throw new PluginBootstrapFailure("package_invalid", "Unsupported plugin package schema");
+    validateBundleManifestV1(value.manifest);
+    if (!Array.isArray(value.files) || !value.files.length || value.files.length > PACKAGE_MAX_FILES)
+        throw new PluginBootstrapFailure("package_invalid", "The plugin package file count is invalid");
+    const paths = new Set();
+    let expandedSize = 0;
+    for (const file of value.files) {
+        if (!isSafeBundlePath(file.path))
+            throw new PluginBootstrapFailure("package_path_invalid", "Plugin package path is unsafe");
+        if (paths.has(file.path))
+            throw new PluginBootstrapFailure("package_path_duplicate", "Plugin package contains duplicate paths");
+        paths.add(file.path);
+        if (!/^[a-f0-9]{64}$/.test(file.sha256))
+            throw new PluginBootstrapFailure("package_invalid", `Plugin package digest is invalid for ${file.path}`);
+        const content = decodeBase64Strict(file.contentBase64, `content for ${file.path}`);
+        expandedSize += content.byteLength;
+        if (expandedSize > PACKAGE_MAX_EXPANDED_BYTES)
+            throw new PluginBootstrapFailure("package_too_large", "The plugin package exceeds the expanded-size limit");
+        if (sha256(content) !== file.sha256)
+            throw new PluginBootstrapFailure("package_file_digest_mismatch", `Plugin package file digest failed for ${file.path}`);
+    }
+    if (!paths.has(value.manifest.entrypoint))
+        throw new PluginBootstrapFailure("package_entrypoint_missing", "The plugin package does not contain its entrypoint");
+}
+function extractPackage(packageValue, stagingDirectory) {
+    fs.mkdirSync(stagingDirectory, { recursive: false, mode: 0o700 });
+    for (const file of packageValue.files) {
+        const target = resolveManagedPath(stagingDirectory, file.path);
+        fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(target, decodeBase64Strict(file.contentBase64, `content for ${file.path}`), {
+            mode: file.executable ? 0o755 : 0o644,
+            flag: "wx",
+        });
+    }
+}
+async function defaultHealthCheck(directory, release) {
+    const entrypoint = resolveManagedPath(directory, release.manifest.entrypoint);
+    const stat = fs.lstatSync(entrypoint);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new PluginBootstrapFailure("health_check_failed", "The plugin entrypoint is not a regular file");
+}
+function validateReceipt(receipt, expectedBundleId) {
+    if (receipt.schemaVersion !== 1 || receipt.bundleId !== expectedBundleId)
+        throw new PluginBootstrapFailure("receipt_invalid", "The plugin install receipt has the wrong identity");
+    validateId(receipt.bundleId, "bundle");
+    validateVersion(receipt.version);
+    if (!receipt.channel.trim() || receipt.pluginApi !== AGENT_MEMORY_PLUGIN_API_VERSION)
+        throw new PluginBootstrapFailure("receipt_invalid", "The plugin install receipt is incompatible");
+    if (!isSafeBundlePath(receipt.entrypoint) || !/^[a-f0-9]{64}$/.test(receipt.packageSha256))
+        throw new PluginBootstrapFailure("receipt_invalid", "The plugin install receipt contains invalid paths or digests");
+}
+function validateId(value, label) {
+    if (!/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(value))
+        throw new PluginBootstrapFailure(`${label}_id_invalid`, `Invalid ${label} id: ${value}`);
+}
+function validateVersion(value) {
+    parseVersion(value);
+}
+function parseVersion(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/.exec(value);
+    if (!match)
+        throw new PluginBootstrapFailure("version_invalid", `Invalid semantic version: ${value}`);
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function resolveManagedPath(root, relative) {
+    if (!isSafeBundlePath(relative))
+        throw new PluginBootstrapFailure("path_invalid", "Managed plugin path is unsafe");
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, ...relative.split("/"));
+    if (resolved === resolvedRoot || !resolved.startsWith(`${resolvedRoot}${path.sep}`))
+        throw new PluginBootstrapFailure("path_invalid", "Managed plugin path escapes its root");
+    return resolved;
+}
+function ensureRegularDirectory(directory, recursive = false) {
+    if (!fs.existsSync(directory))
+        fs.mkdirSync(directory, { recursive, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new PluginBootstrapFailure("install_root_invalid", "The plugin install root and its managed directories must be regular directories");
+}
+function removeManagedDirectory(root, target) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedTarget = path.resolve(target);
+    if (resolvedTarget === resolvedRoot || !resolvedTarget.startsWith(`${resolvedRoot}${path.sep}`))
+        throw new PluginBootstrapFailure("path_invalid", "Refusing to remove a path outside the plugin install root");
+    const stat = fs.lstatSync(resolvedTarget);
+    if (stat.isSymbolicLink())
+        throw new PluginBootstrapFailure("path_invalid", "Refusing to remove a symbolic link");
+    if (!stat.isDirectory())
+        throw new PluginBootstrapFailure("path_invalid", "Managed removal target is not a directory");
+    fs.rmSync(resolvedTarget, { recursive: true, force: false });
+}
+function decodeBase64Strict(value, label) {
+    if (!value || !/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0)
+        throw new PluginBootstrapFailure("base64_invalid", `Invalid base64 ${label}`);
+    const decoded = Buffer.from(value, "base64");
+    if (decoded.toString("base64") !== value)
+        throw new PluginBootstrapFailure("base64_invalid", `Non-canonical base64 ${label}`);
+    return decoded;
+}
+function isEntitled(entitlement) {
+    return entitlement.state === "active" || entitlement.state === "grace";
+}
+function normalizeFailure(error) {
+    if (error instanceof PluginBootstrapFailure)
+        return error;
+    return new PluginBootstrapFailure("plugin_install_failed", error instanceof Error ? error.message : String(error));
+}