@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/plugins/pro-state.js

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageVersion } from "../cli/home.js";
+import { env } from "../env.js";
+import { managed } from "../manage.js";
+/**
+ * Which Pro modules may load (docs/pro-modules.md). A Pro module is a closed
+ * plugin the linked account's plan includes, installed by pro.ts into a folder of its own. It
+ * loads while the entitlement the account's Manage-App signed lists it and has not ended, and
+ * only in the release it was built for. Kept apart from pro.ts, so the loader needs no network.
+ */
+/** Where Pro modules are installed: apart from the person's own plugins, not watched. */
+export const proModulesDir = () => join(env.dataDir, "pro-modules");
+/** Written beside an installed module: what was installed, for which release. */
+export const INSTALLED_FILE = ".engenty-module.json";
+export const ENTITLEMENT_SETTING = "pro.entitlement";
+let entitlement = null;
+export function currentEntitlement() {
+    return entitlement;
+}
+export function setEntitlement(value) {
+    entitlement = value;
+}
+/** `0.2.26` → `v0.2.26`: the release this runtime is. */
+export const runtimeTag = () => `v${packageVersion()}`;
+export function installedModule(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, INSTALLED_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function heldBack(source) {
+    if (managed) {
+        return "managed";
+    }
+    const installed = installedModule(source.root);
+    if (!installed || installed.id !== source.id) {
+        return "not_installed";
+    }
+    if (installed.runtime !== runtimeTag()) {
+        return "release";
+    }
+    if (!(entitlement && entitlement.expiresAt > Date.now())) {
+        return "unconfirmed";
+    }
+    if (!entitlement.modules.includes(source.id)) {
+        return "plan";
+    }
+    return null;
+}
+let held = new Map();
+/** The Pro modules that were found and did not load, with the reason, as of the last look. */
+export function heldBackModules() {
+    return held;
+}
+/**
+ * The Pro modules of a look at the folders that may load, marked as such. A Pro module never
+ * takes the id of a plugin found elsewhere.
+ */
+export function proSources(found, taken) {
+    const load = [];
+    const problems = [];
+    held = new Map();
+    for (const source of found) {
+        if (taken.has(source.id)) {
+            problems.push({
+                path: source.root,
+                message: `Plugin "${source.id}" is already loaded from another folder.`,
+            });
+            continue;
+        }
+        const reason = heldBack(source);
+        if (reason) {
+            held.set(source.id, reason);
+        }
+        else {
+            load.push({ ...source, pro: true });
+        }
+    }
+    return { load, problems };
+}

package/apps/runtime/dist/plugins/pro.js

@@ -0,0 +1,310 @@
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { unzipSync } from "fflate";
+import { accountToken, linkedAccount } from "../auth/account.js";
+import { env } from "../env.js";
+import { managed, verifySigned } from "../manage.js";
+import { deleteSetting, readSetting, writeSetting } from "../settings.js";
+import { MANIFEST_FILE } from "./discovery.js";
+import { findNewPlugins, reloadPlugin } from "./loader.js";
+import { signedByUs } from "./pro-keys.js";
+import { currentEntitlement, ENTITLEMENT_SETTING, heldBackModules, INSTALLED_FILE, installedModule, proModulesDir, runtimeTag, setEntitlement, } from "./pro-state.js";
+import { loadedPlugin } from "./registry.js";
+/*
+ * Pro modules on a runtime that runs alone (docs/pro-modules.md): the closed
+ * plugins the linked account's plan includes, fetched from its Manage-App.
+ *
+ *   GET /v1/modules?runtime=<release>              what is built for this release, the plan's
+ *                                                  part of it, and the signed entitlement
+ *   GET /v1/modules/:id/package?runtime=<release>  one module's zip
+ *
+ * A package is taken only when its SHA-256 and the signature over id, version, release and that
+ * hash check out against a key this runtime carries (pro-keys.ts): neither the Manage-App nor
+ * the way there can hand over code of their own.
+ */
+/** The audience of an entitlement, as the Manage-App signs it. */
+const AUDIENCE = "urn:engenty:wizards:modules";
+/** Larger packages are refused before they are read. */
+const MAX_PACKAGE = 30 * 1024 * 1024;
+/** What a package may hold, besides its manifest. */
+const PARTS = ["dist/", "migrations/"];
+const base = () => `${env.local.accountUrl}/v1/modules`;
+/** Something the person can mend or retry; the message is for them. */
+export class ProModuleError extends Error {
+    status;
+    code;
+    constructor(message, status = 400, code = "pro_module") {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+let listing = null;
+let lastError = null;
+// --- the entitlement -------------------------------------------------------------------
+/**
+ * At start, before the plugins load: what the last check said, while it lasts and belongs to the
+ * account that is linked now.
+ */
+export async function loadEntitlement() {
+    if (managed) {
+        return;
+    }
+    const [stored, account] = await Promise.all([
+        readSetting(ENTITLEMENT_SETTING),
+        linkedAccount(),
+    ]);
+    setEntitlement(stored && account && stored.tenantId === account.tenantId ? stored : null);
+}
+async function keep(value) {
+    setEntitlement(value);
+    if (value) {
+        await writeSetting(ENTITLEMENT_SETTING, value);
+    }
+    else {
+        await deleteSetting(ENTITLEMENT_SETTING);
+    }
+}
+/** Loads and unloads Pro modules after the entitlement changed. */
+async function apply(before) {
+    const after = currentEntitlement();
+    const same = before?.modules.join() === after?.modules.join() &&
+        (before?.expiresAt ?? 0) > Date.now() === (after?.expiresAt ?? 0) > Date.now();
+    if (!same) {
+        await findNewPlugins();
+    }
+}
+async function call(path, token) {
+    const url = new URL(`${base()}${path}`);
+    url.searchParams.set("runtime", runtimeTag());
+    const res = await fetch(url, {
+        headers: { authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(60_000),
+    }).catch(() => null);
+    if (!res) {
+        throw new ProModuleError("Your engenty account is not reachable right now.", 502, "offline");
+    }
+    return res;
+}
+/**
+ * Asks the account what its plan includes now, keeps the signed answer and fetches what an
+ * installed module needs (a new release, a new build). Unreachable: what was confirmed lasts
+ * until it ends.
+ */
+export async function refreshPro() {
+    if (managed) {
+        return;
+    }
+    const before = currentEntitlement();
+    const account = await linkedAccount();
+    if (!account) {
+        listing = null;
+        lastError = null;
+        await keep(null);
+        await apply(before);
+        return;
+    }
+    try {
+        const token = await accountToken();
+        if (!token) {
+            throw new ProModuleError("Your engenty account is not reachable right now.", 502, "offline");
+        }
+        const res = await call("", token);
+        if (res.status === 401) {
+            throw new ProModuleError("The engenty account no longer accepts this sign-in.", 403);
+        }
+        if (!res.ok) {
+            throw new ProModuleError(`The account did not answer as expected (${res.status}).`, 502);
+        }
+        const answer = (await res.json());
+        const claims = await verifySigned(answer.entitlement?.token ?? "", [AUDIENCE], env.local.accountUrl);
+        if (!claims || claims.sub !== account.tenantId || !Array.isArray(claims.modules)) {
+            throw new ProModuleError("The package's confirmation could not be checked.", 502);
+        }
+        listing = answer;
+        lastError = null;
+        await keep({
+            tenantId: account.tenantId,
+            modules: claims.modules.map(String),
+            plan: answer.plan ?? null,
+            expiresAt: (claims.exp ?? 0) * 1000,
+            checkedAt: Date.now(),
+        });
+        await apply(before);
+        await updateInstalled();
+    }
+    catch (err) {
+        lastError = err.message;
+        console.error("[pro modules]", lastError);
+    }
+}
+let timer = null;
+/** Checks at start, then once a day while the runtime runs; a check that failed, within the hour. */
+export function startProChecks() {
+    if (managed || timer) {
+        return;
+    }
+    void refreshPro();
+    timer = setInterval(() => {
+        const checkedAt = currentEntitlement()?.checkedAt ?? 0;
+        if (lastError || Date.now() - checkedAt > 23 * 3600_000) {
+            void refreshPro();
+        }
+    }, 3600_000);
+    timer.unref();
+}
+// --- installing ------------------------------------------------------------------------
+async function installedIds() {
+    const entries = await readdir(proModulesDir(), { withFileTypes: true }).catch(() => []);
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+}
+/** Installed modules built for another release or from another build are fetched anew. */
+async function updateInstalled() {
+    for (const id of await installedIds()) {
+        const entry = listing?.modules.find((m) => m.id === id);
+        const installed = installedModule(join(proModulesDir(), id));
+        if (entry?.included && installed?.sha256 !== entry.sha256) {
+            await installPro(id).catch((err) => console.error(`[pro modules] ${id}: update failed:`, err.message));
+        }
+    }
+}
+/** The files of a zip, refusing any that would land outside the module's folder. */
+function filesOf(zip) {
+    let files;
+    try {
+        files = unzipSync(zip);
+    }
+    catch {
+        throw new ProModuleError("The package is damaged.", 502);
+    }
+    const out = {};
+    for (const [name, data] of Object.entries(files)) {
+        if (name.endsWith("/")) {
+            continue;
+        }
+        const parts = name.split("/");
+        const safe = parts.every((p) => p && p !== "." && p !== ".." && !p.includes("\\"));
+        const allowed = name === MANIFEST_FILE || PARTS.some((part) => name.startsWith(part));
+        if (!(safe && allowed)) {
+            throw new ProModuleError(`The package holds a file it may not: ${name}`, 502);
+        }
+        out[name] = data;
+    }
+    return out;
+}
+/** Fetches one module of the plan, checks it and puts it in place; then it loads. */
+export async function installPro(id) {
+    if (managed) {
+        throw new ProModuleError("Not available here.", 404, "not_found");
+    }
+    const token = await accountToken();
+    if (!token) {
+        throw new ProModuleError("Sign in to your engenty account first (Settings → Account).", 409);
+    }
+    if (!listing) {
+        await refreshPro();
+    }
+    const entry = listing?.modules.find((m) => m.id === id);
+    if (!entry) {
+        throw new ProModuleError(`There is no build of this module for ${runtimeTag()}.`, 404, "not_found");
+    }
+    if (!entry.included) {
+        throw new ProModuleError("This module is not part of your plan.", 403, "plan");
+    }
+    const res = await call(`/${encodeURIComponent(id)}/package`, token);
+    if (!res.ok) {
+        throw new ProModuleError(`The module could not be fetched (${res.status}).`, 502);
+    }
+    if (Number(res.headers.get("content-length") ?? 0) > MAX_PACKAGE) {
+        throw new ProModuleError("The package is too large.", 502);
+    }
+    const zip = new Uint8Array(await res.arrayBuffer());
+    const sha256 = createHash("sha256").update(zip).digest("hex");
+    const genuine = sha256 === entry.sha256 &&
+        signedByUs({
+            id,
+            version: entry.version,
+            runtime: runtimeTag(),
+            sha256,
+            signature: entry.signature,
+        });
+    if (zip.length > MAX_PACKAGE || !genuine) {
+        throw new ProModuleError("The package is not signed by engenty and was discarded.", 502);
+    }
+    const files = filesOf(zip);
+    const manifest = JSON.parse(new TextDecoder().decode(files[MANIFEST_FILE] ?? new Uint8Array()));
+    if (manifest?.id !== id) {
+        throw new ProModuleError("The package does not belong to this module.", 502);
+    }
+    const dir = proModulesDir();
+    const target = join(dir, id);
+    const fresh = join(dir, `.new-${id}-${randomBytes(4).toString("hex")}`);
+    const old = join(dir, `.old-${id}-${randomBytes(4).toString("hex")}`);
+    await mkdir(fresh, { recursive: true });
+    try {
+        for (const [path, data] of Object.entries(files)) {
+            await mkdir(dirname(join(fresh, path)), { recursive: true });
+            await writeFile(join(fresh, path), data);
+        }
+        const installed = {
+            id,
+            version: entry.version,
+            runtime: runtimeTag(),
+            sha256,
+            installedAt: new Date().toISOString(),
+        };
+        await writeFile(join(fresh, INSTALLED_FILE), `${JSON.stringify(installed, null, 2)}\n`);
+        if (existsSync(target)) {
+            await rename(target, old);
+        }
+        await rename(fresh, target);
+    }
+    finally {
+        await rm(fresh, { recursive: true, force: true });
+        await rm(old, { recursive: true, force: true });
+    }
+    await reloadPlugin(id);
+}
+/** Removes an installed module; its tables and what is in them stay. */
+export async function removePro(id) {
+    if (managed || !(await installedIds()).includes(id)) {
+        throw new ProModuleError("This module is not installed.", 404, "not_found");
+    }
+    await rm(join(proModulesDir(), id), { recursive: true, force: true });
+    await findNewPlugins();
+}
+export async function proState() {
+    const entitlement = currentEntitlement();
+    const account = await linkedAccount();
+    const ids = new Set([...(listing?.modules.map((m) => m.id) ?? []), ...(await installedIds())]);
+    const modules = [...ids].sort().map((id) => {
+        const entry = listing?.modules.find((m) => m.id === id);
+        const installed = installedModule(join(proModulesDir(), id));
+        const plugin = loadedPlugin(id);
+        return {
+            id,
+            name: entry?.name ?? plugin?.source.manifest.name ?? id,
+            version: entry?.version ?? installed?.version ?? "",
+            description: entry?.description ?? plugin?.source.manifest.description ?? "",
+            size: entry?.size ?? null,
+            included: entitlement?.modules.includes(id) ?? false,
+            installed: installed ? { version: installed.version, runtime: installed.runtime } : null,
+            loaded: Boolean(plugin?.source.pro),
+            heldBack: heldBackModules().get(id) ?? null,
+            update: Boolean(entry?.included && installed && installed.sha256 !== entry.sha256),
+        };
+    });
+    return {
+        linked: Boolean(account),
+        /** Where the plans are: `<accountUrl>/billing`. */
+        accountUrl: env.local.accountUrl,
+        runtime: runtimeTag(),
+        plan: entitlement?.plan ?? listing?.plan ?? null,
+        expiresAt: entitlement ? new Date(entitlement.expiresAt).toISOString() : null,
+        checkedAt: entitlement ? new Date(entitlement.checkedAt).toISOString() : null,
+        error: lastError,
+        modules,
+    };
+}

package/apps/runtime/dist/plugins/public.js

@@ -0,0 +1,44 @@
+import { and, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { control, controlDb } from "../db/client.js";
+import { env } from "../env.js";
+import { currentTenant } from "../tenants/tenant.js";
+/**
+ * Public addresses of plugins (`server.publicUrl`): `/api/public/plugins/<plugin>/<ref>/…`. The
+ * ref names the tenant without giving its id away; one per tenant and plugin, kept for good.
+ * A shared route (`server.sharedUrl`) is `/api/public/plugins/<plugin>/shared/…` for every
+ * tenant: a ref is 24 characters, so it is never `shared`.
+ */
+export const SHARED = "shared";
+const rest = (path) => {
+    const p = path.startsWith("/") ? path : `/${path}`;
+    return p === "/" ? "" : p;
+};
+/** The full address of a plugin's public route for the current tenant. */
+export async function publicUrlOf(plugin, path) {
+    return `${env.publicUrl}/api/public/plugins/${plugin}/${await publicRefOf(plugin)}${rest(path)}`;
+}
+/** The full address of a plugin's shared route. */
+export function sharedUrlOf(plugin, path) {
+    return `${env.publicUrl}/api/public/plugins/${plugin}/${SHARED}${rest(path)}`;
+}
+/** The ref of a tenant's public address for a plugin (the current tenant's by default), made the first time. */
+export async function publicRefOf(plugin, tenantId = currentTenant()) {
+    const where = and(eq(control.pluginAddress.tenantId, tenantId), eq(control.pluginAddress.plugin, plugin));
+    let row = await controlDb.query.pluginAddress.findFirst({ where });
+    if (!row) {
+        await controlDb
+            .insert(control.pluginAddress)
+            .values({ ref: nanoid(24), tenantId, plugin })
+            .onConflictDoNothing();
+        row = (await controlDb.query.pluginAddress.findFirst({ where }));
+    }
+    return row.ref;
+}
+/** The tenant a plugin's public address belongs to. */
+export async function tenantOfAddress(plugin, ref) {
+    const row = await controlDb.query.pluginAddress.findFirst({
+        where: eq(control.pluginAddress.ref, ref),
+    });
+    return row?.plugin === plugin ? row.tenantId : null;
+}

package/apps/runtime/dist/plugins/registry.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { readFileSync } from "node:fs";
+import { env } from "../env.js";
+import { managed, tenantInfo } from "../manage.js";
+const plugins = new Map();
+let generations = 0;
+export function nextGeneration() {
+    return ++generations;
+}
+export function emptyRecord(source) {
+    return {
+        source,
+        generation: nextGeneration(),
+        error: null,
+        routes: [],
+        tools: new Map(),
+        contexts: [],
+        assistantTools: new Map(),
+        assistantPages: [],
+        publicRoutes: [],
+        sharedRoutes: [],
+        runners: new Map(),
+        jobs: new Map(),
+        starters: new Map(),
+        listeners: {},
+        migrations: [],
+        disposers: [],
+        stopped: new AbortController(),
+    };
+}
+export function setPlugin(record) {
+    plugins.set(record.source.id, record);
+}
+export function dropPlugin(id) {
+    const record = plugins.get(id);
+    plugins.delete(id);
+    return record;
+}
+export function loadedPlugin(id) {
+    return plugins.get(id);
+}
+export function loadedPlugins() {
+    return [...plugins.values()];
+}
+/** `/items/:id` as a pattern for the address below the plugin's own. */
+export function compileRoute(route) {
+    const params = [];
+    const path = route.path.startsWith("/") ? route.path : `/${route.path}`;
+    const source = path
+        .replace(/\/+$/, "")
+        .split("/")
+        .map((part) => {
+        if (part.startsWith(":")) {
+            params.push(part.slice(1));
+            return "([^/]+)";
+        }
+        return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("/");
+    return { route, pattern: new RegExp(`^${source}/?$`), params };
+}
+// --- which tenant has which plugin -----------------------------------------------------
+/**
+ * The ids of the plugins a tenant has. A runtime that runs alone has every plugin it loaded.
+ * Managed, a tenant has the ones in `PLUGINS_DEFAULT` and the ones the Manage-App lists for it
+ * (`modules` of `GET /v1/tenants/:id`).
+ */
+export async function pluginIdsOf(tenantId) {
+    if (!managed) {
+        return new Set(plugins.keys());
+    }
+    const listed = await tenantInfo(tenantId)
+        .then((info) => info.modules ?? [])
+        .catch(() => []);
+    return new Set([...env.plugins.defaults, ...listed].filter((id) => plugins.has(id)));
+}
+export async function pluginsOf(tenantId) {
+    const ids = await pluginIdsOf(tenantId);
+    return loadedPlugins().filter((p) => ids.has(p.source.id));
+}
+/** The tools the tenant's plugins add, by the id a step lists them under. */
+export async function pluginToolsOf(tenantId) {
+    return (await pluginsOf(tenantId)).flatMap((plugin) => [...plugin.tools.values()].map((tool) => ({
+        id: `${plugin.source.id}.${tool.name}`,
+        title: tool.title ?? tool.name,
+        description: tool.description,
+    })));
+}
+/** The starters the tenant's plugins bring, in the order the plugins registered them. */
+export async function pluginStartersOf(tenantId) {
+    return (await pluginsOf(tenantId)).flatMap((plugin) => [...plugin.starters.values()].map((starter) => ({
+        id: `${plugin.source.id}.${starter.id}`,
+        plugin,
+        starter,
+    })));
+}
+/** The built studio half as it is on disk now; null when the plugin has none. */
+export function pluginAsset(record, kind) {
+    const file = record.source[kind];
+    if (!file) {
+        return null;
+    }
+    try {
+        return {
+            file,
+            rev: createHash("sha256").update(readFileSync(file)).digest("hex").slice(0, 12),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const changes = new EventEmitter();
+changes.setMaxListeners(0);
+export function announceChange(change) {
+    changes.emit("change", change);
+}
+export function onPluginChange(listener) {
+    changes.on("change", listener);
+    return () => changes.off("change", listener);
+}