nylorun 0.7.0-beta → 0.9.0-beta

package/dist/stack/operator-keys.js

@@ -0,0 +1,146 @@
+/**
+ * Operator keys (F9 I1, Host feature `operator-keys`) as the nylorun commands use them: the
+ * Admin API's `/v1/admin/keys` on a local Tenant's operator listener, with its admin key, and
+ * the keys nylorun keeps in the Host root (`project`, `cli`). nylorun depends on
+ * `@nylorun/core` only, so these are plain requests (`admin.keys` in `@nylorun/admin` makes
+ * the same).
+ */
+import { open, rm, stat } from "node:fs/promises";
+import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
+import { CliError } from "../errors.js";
+import { readCredentialsFile, writeCredentialsFile, } from "../project/link.js";
+/** The key `nylorun start` gives the projects it links. */
+export const PROJECT_KEY_ID = "project";
+/** The key nylorun commands use outside a linked project. */
+export const CLI_KEY_ID = "cli";
+async function adminRequest(admin, method, path) {
+    let response;
+    try {
+        response = await admin.fetch(`${admin.adminUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${admin.adminKey}`,
+                [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+                accept: "application/json",
+            },
+            redirect: "error",
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        throw new CliError(`The Admin API at ${admin.adminUrl} did not answer ${method} ${path} (${error instanceof Error ? error.message : String(error)}).`, 7);
+    }
+    const body = (await response.json().catch(() => ({})));
+    return { status: response.status, body };
+}
+function refused(method, path, answer) {
+    const message = typeof answer.body.message === "string" ? `: ${answer.body.message}` : "";
+    // An older Runtime has no key routes: the Admin API's "Route not found".
+    if (answer.status === 404 && answer.body.message === "Route not found")
+        return new CliError(`The Runtime does not serve operator keys (Host feature operator-keys). Update it: npx nylorun@latest start.`, 1);
+    return new CliError(`${method} ${path} returned ${answer.status}${message}`, 1);
+}
+const keyPath = (id) => `/v1/admin/keys/${encodeURIComponent(id)}`;
+/** Creates key `id` or rotates it; the answer holds the key, this once. */
+export async function putOperatorKey(admin, id) {
+    const answer = await adminRequest(admin, "PUT", keyPath(id));
+    if (answer.status !== 200 || typeof answer.body.key !== "string")
+        throw refused("PUT", keyPath(id), answer);
+    return answer.body;
+}
+export async function listOperatorKeys(admin) {
+    const answer = await adminRequest(admin, "GET", "/v1/admin/keys");
+    if (answer.status !== 200 || !Array.isArray(answer.body.keys))
+        throw refused("GET", "/v1/admin/keys", answer);
+    return answer.body.keys;
+}
+/** Deletes key `id`: false when there is none. */
+export async function deleteOperatorKey(admin, id) {
+    const answer = await adminRequest(admin, "DELETE", keyPath(id));
+    if (answer.status === 200)
+        return true;
+    if (answer.status === 404 && answer.body.message === `No key ${id}`)
+        return false;
+    throw refused("DELETE", keyPath(id), answer);
+}
+/**
+ * Whether `key` reaches the Tenant API at `runtimeUrl`: one authenticated read
+ * (`GET /v1/tenant`). An unknown key is the opaque 404; another answer is an error.
+ */
+export async function keyAuthenticates(fetch, runtimeUrl, key) {
+    let response;
+    try {
+        response = await fetch(`${runtimeUrl}/v1/tenant`, {
+            headers: {
+                authorization: `Bearer ${key}`,
+                [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+                accept: "application/json",
+            },
+            redirect: "error",
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (error) {
+        throw new CliError(`The Runtime at ${runtimeUrl} did not answer (${error instanceof Error ? error.message : String(error)}).`, 7);
+    }
+    await response.arrayBuffer().catch(() => undefined);
+    if (response.ok)
+        return true;
+    if (response.status === 401 || response.status === 403 || response.status === 404)
+        return false;
+    throw new CliError(`GET ${runtimeUrl}/v1/tenant returned ${response.status}.`, 7);
+}
+const LOCK_TIMEOUT_MS = 30_000;
+/** A lock older than this was left by a process that died. */
+const LOCK_STALE_MS = 60_000;
+/** Runs `fn` holding the lock file `path` (created exclusively), so one process puts a key. */
+async function withLock(path, fn) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const handle = await open(path, "wx", 0o600);
+            await handle.close();
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const held = await stat(path).catch(() => undefined);
+            if (held && Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+                await rm(path, { force: true });
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new CliError(`Another nylorun command holds ${path}. Remove it if none runs.`, 1);
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await rm(path, { force: true });
+    }
+}
+/**
+ * The operator key `id` kept in the Host root file `file` (0600): the file's key while it
+ * still authenticates, else `adopt` when it does (a key a project already holds), else a new
+ * key put through the Admin API and written to the file. One process at a time (`lock`), so
+ * concurrent commands share one key instead of rotating each other's.
+ */
+export async function hostKey(options) {
+    const { admin, runtimeUrl, id, file } = options;
+    return await withLock(options.lock, async () => {
+        const kept = await readCredentialsFile(file);
+        if (kept && (await keyAuthenticates(admin.fetch, runtimeUrl, kept.applicationKey)))
+            return { ...kept, put: false };
+        if (options.adopt && (await keyAuthenticates(admin.fetch, runtimeUrl, options.adopt.applicationKey))) {
+            await writeCredentialsFile(file, options.adopt);
+            return { ...options.adopt, put: false };
+        }
+        const put = await putOperatorKey(admin, id);
+        const credentials = { applicationKey: put.key, principalId: put.id };
+        await writeCredentialsFile(file, credentials);
+        return { ...credentials, put: true };
+    });
+}

package/dist/stack/paths.d.ts

@@ -8,10 +8,42 @@ export interface StackPaths {
     credentials: string;
     /** host-state.json: written only by a launcher-managed Runtime. */
     state: string;
+    /**
+     * cli-credentials.json: the operator key `cli` that `nylorun` commands use outside a linked
+     * project (`nylorun sandbox`), mode 0600.
+     */
+    cliCredentials: string;
+    /**
+     * project-credentials.json: the operator key `project` that `nylorun start` gives every
+     * project it links to this Tenant (a copy of their `.nylorun/credentials.json`), mode 0600.
+     */
+    projectCredentials: string;
+    /** operator-keys.lock: held while a command puts one of the keys above. */
+    keysLock: string;
     /** tenant.json: the Tenant's name and the project it was created for. */
     record: string;
+    /**
+     * identity.yaml: the trusted issuers (F9 I2), written by the operator. When it exists the
+     * runtime reads it at boot (`NYLORUN_IDENTITY_FILE`).
+     */
+    identity: string;
     /** The Tenant directory: homes, sandboxes, plugin data, logs. */
     tenant: string;
+    /**
+     * The Tenant directory's parts the harness container mounts (F6.2): workspaces, plugin data,
+     * and the home and temporary directory of MCP stdio servers.
+     */
+    harness: {
+        sandboxes: string;
+        pluginData: string;
+        home: string;
+        tmp: string;
+    };
+    /**
+     * Plugin roots on this machine (`plugins/`), mounted read-only at the same path into the
+     * runtime and harness containers, so a stdio MCP server's plugin root resolves there.
+     */
+    plugins: string;
     /** The keys directory, mounted only into the gateway (F4.2). */
     keys: string;
     /** The Tenant's vault key (KEK), `keys/vault-kek`. */

package/dist/stack/paths.js

@@ -7,8 +7,19 @@ export function stackPaths(hostRoot) {
         config: join(root, "host.json"),
         credentials: join(root, "host-credentials.json"),
         state: join(root, "host-state.json"),
+        cliCredentials: join(root, "cli-credentials.json"),
+        projectCredentials: join(root, "project-credentials.json"),
+        keysLock: join(root, "operator-keys.lock"),
         record: join(root, "tenant.json"),
+        identity: join(root, "identity.yaml"),
         tenant: join(root, "tenant"),
+        harness: {
+            sandboxes: join(root, "tenant", "sandboxes"),
+            pluginData: join(root, "tenant", "plugin-data"),
+            home: join(root, "tenant", "home"),
+            tmp: join(root, "tenant", "tmp"),
+        },
+        plugins: join(root, "plugins"),
         keys: join(root, "keys"),
         vaultKey: join(root, "keys", "vault-kek"),
         home: join(root, "home"),

package/dist/stack/prepare.d.ts

@@ -1,4 +1,4 @@
-import { type StackEnv } from "./env-file.js";
+import { type SandboxStackEnv, type StackEnv } from "./env-file.js";
 import { type HostConfigFile } from "./host-files.js";
 import type { StackImages } from "./images.js";
 import type { StackPaths } from "./paths.js";
@@ -16,7 +16,8 @@ export declare function readStackEnv(paths: Pick<StackPaths, "env">): Promise<im
  * Write everything `docker compose up` needs under the Host root:
  * host.json, host-credentials.json (0600), docker/compose.yaml,
  * docker/.env (0600) and docker/restate-identity.pem (0600). Ports and the
- * Postgres password persist in .env; the identity key persists in its PEM.
+ * Postgres password persist in .env; the identity key persists in its PEM. The harness token
+ * and mode persist too; whether Restate's UI is published is decided on every start.
  */
 export declare function prepareStack(input: {
     paths: StackPaths;
@@ -31,11 +32,9 @@ export declare function prepareStack(input: {
     ports: PortProbe;
     /** Ports other Tenants keep in their `.env`: never chosen for a port not chosen yet. */
     reserved?: ReadonlySet<number>;
-    /** `NYLORUN_DERIVED_PRINCIPALS` from the environment of `nylorun start`; else kept. */
-    derivedPrincipals?: string;
     /**
-     * Changes to the origins that may embed Studio: `reset` goes back to the
-     * defaults, `add` appends (for example a desktop app's dev server).
+     * Changes to the origins that may embed Studio: `reset` empties the list (the
+     * default), `add` appends (for example a desktop app's dev server).
      */
     studioEmbedOrigins?: {
         add?: readonly string[];
@@ -43,4 +42,11 @@ export declare function prepareStack(input: {
     };
     /** The measurement id Studio reports page views to; absent when telemetry is off. */
     studioAnalyticsId?: string;
+    /**
+     * The sandboxes settings (`nylorun sandbox enable`); null removes them (`disable`).
+     * Undefined keeps the persisted ones while `sandboxes/cluster.json` exists.
+     */
+    sandboxes?: SandboxStackEnv | null;
+    /** Publish Restate's UI and admin port (`start --restate-ui`); undefined keeps the last start's choice. */
+    restateUi?: boolean;
 }): Promise<PreparedStack>;

package/dist/stack/prepare.js

@@ -1,9 +1,11 @@
 import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
 import { chmod, readFile, rename, writeFile } from "node:fs/promises";
 import { renderComposeFile } from "./compose-file.js";
 import { parseFrameAncestors } from "@nylorun/core/contracts";
 import { CliError } from "../errors.js";
-import { DEFAULT_STUDIO_FRAME_ANCESTORS, parseDerivedPrincipals, parsePersisted, renderEnvFile, } from "./env-file.js";
+import { DEFAULT_STUDIO_FRAME_ANCESTORS, parsePersisted, renderEnvFile, } from "./env-file.js";
+import { sandboxesEnabled } from "../sandbox/cluster-file.js";
 import { ensureHostCredentials, ensureVaultKey, ensureHostLayout, writeStackHostConfig, } from "./host-files.js";
 import { choosePort, DEFAULT_PORTS } from "./ports.js";
 import { ensureIdentityKey } from "./restate-identity.js";
@@ -30,7 +32,8 @@ export async function readStackEnv(paths) {
  * Write everything `docker compose up` needs under the Host root:
  * host.json, host-credentials.json (0600), docker/compose.yaml,
  * docker/.env (0600) and docker/restate-identity.pem (0600). Ports and the
- * Postgres password persist in .env; the identity key persists in its PEM.
+ * Postgres password persist in .env; the identity key persists in its PEM. The harness token
+ * and mode persist too; whether Restate's UI is published is decided on every start.
  */
 export async function prepareStack(input) {
     const { paths } = input;
@@ -69,6 +72,12 @@ export async function prepareStack(input) {
         postgresPassword: persisted.postgresPassword ?? randomBytes(24).toString("hex"),
         // Kept across starts: a new token would recreate the runtime and gateway containers.
         gatesToken: persisted.gatesToken ?? randomBytes(32).toString("hex"),
+        // Kept across starts: a new token would recreate the runtime and harness containers.
+        harnessToken: persisted.harnessToken ?? randomBytes(32).toString("hex"),
+        harness: persisted.harness ?? "remote",
+        restateUi: input.restateUi ?? persisted.restateUi ?? false,
+        // Kept across starts: a new key would recreate the runtime, gateway and rustfs containers.
+        objectStoreSecretKey: persisted.objectStoreSecretKey ?? randomBytes(32).toString("hex"),
         restateIdentityKey: identity.publicKey,
         uid: input.uid,
         gid: input.gid,
@@ -78,10 +87,13 @@ export async function prepareStack(input) {
         studioFrameAncestors,
         studioAnalyticsId: input.studioAnalyticsId ?? "",
         tenantName: input.name,
-        derivedPrincipals: (input.derivedPrincipals?.trim()
-            ? parseDerivedPrincipals(input.derivedPrincipals, "NYLORUN_DERIVED_PRINCIPALS")
-            : (persisted.derivedPrincipals ?? ["project"])).join(","),
     };
+    const sandboxes = input.sandboxes === null
+        ? undefined
+        : (input.sandboxes ?? (sandboxesEnabled(paths.root) ? persisted.sandboxes : undefined));
+    // The sandboxes image follows the Runtime's, like the runtime image, on every start.
+    if (sandboxes)
+        env.sandboxes = { ...sandboxes, image: input.images.sandboxes };
     const { adminKey } = await ensureHostCredentials(paths);
     await ensureVaultKey(paths);
     const host = await writeStackHostConfig(paths, {
@@ -90,6 +102,12 @@ export async function prepareStack(input) {
         runtimeVersion: input.runtimeVersion,
     });
     await writeFileMode(paths.env, renderEnvFile(env), 0o600);
-    await writeFileMode(paths.compose, renderComposeFile(input.project, input.name), 0o644);
+    await writeFileMode(paths.compose, renderComposeFile(input.project, input.name, {
+        harness: env.harness,
+        ...(env.sandboxes ? { sandboxes: true } : {}),
+        ...(env.restateUi ? { restateUi: true } : {}),
+        // The trusted issuers, when the operator wrote an identity file; a change takes a restart.
+        ...(existsSync(paths.identity) ? { identity: true } : {}),
+    }), 0o644);
     return { env, host, adminKey, firstRun };
 }

package/dist/stack/sandbox.d.ts

@@ -0,0 +1,4 @@
+import { type StackDeps } from "./commands.js";
+export declare const sandboxUsage = "  sandbox ls [--tenant <name>] [--label <key=value>]... [--json]\n                                      the Tenant's sandboxes: id, kind, state, attached sessions and labels\n  sandbox rm <id> [--tenant <name>]   delete a sandbox and its files (refused while a turn runs in it)\n  sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--no-pull]\n                                      run the Tenant's sandboxes as pods on that kubeconfig context (agent-sandbox v1.0.5)\n  sandbox disable [--tenant <name>] [--delete-namespace]\n                                      stop the sandboxes service and forget the cluster\n  sandbox status [--tenant <name>] [--json]\n                                      the cluster, the sandboxes service's readiness and what it reports";
+/** `nylorun sandbox <ls|rm|enable|disable|status> ...` */
+export declare function sandboxCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/stack/sandbox.js

@@ -0,0 +1,106 @@
+/**
+ * `nylorun sandbox ls | rm`: the running local Tenant's sandbox resources (Host feature
+ * `sandboxes`), through its Tenant API with an operator key (`runningTenantApi`). Neither starts the
+ * Tenant. `nylorun sandbox enable|disable|status` (sandbox pods on a cluster, F7.2) live in
+ * `../sandbox/commands.ts`.
+ */
+import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
+import { CliError } from "../errors.js";
+import { runSandboxCommand, sandboxUsage as clusterUsage } from "../sandbox/commands.js";
+import { spawnKubectl } from "../sandbox/kubectl.js";
+import { parseStackFlags, runningTenantApi } from "./commands.js";
+export const sandboxUsage = `  sandbox ls [--tenant <name>] [--label <key=value>]... [--json]
+                                      the Tenant's sandboxes: id, kind, state, attached sessions and labels
+  sandbox rm <id> [--tenant <name>]   delete a sandbox and its files (refused while a turn runs in it)
+${clusterUsage}`;
+const usageError = (message) => new CliError(message, 2);
+async function call(deps, api, method, path) {
+    const response = await deps.fetch(`${api.runtimeUrl}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${api.applicationKey}`,
+            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+            accept: "application/json",
+        },
+        redirect: "error",
+        signal: AbortSignal.timeout(15_000),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (response.status === 404 && path === "/v1/sandboxes")
+        throw new CliError(`Tenant ${api.name} runs a Runtime without sandboxes. Update it: npx nylorun@latest start.`, 1);
+    if (!response.ok && response.status !== 404)
+        throw new CliError(`${method} ${path} returned ${response.status}${typeof body.message === "string" ? `: ${body.message}` : ""}`, 1);
+    return { status: response.status, body };
+}
+function labelsText(labels) {
+    const entries = Object.entries(labels);
+    return entries.length === 0 ? "-" : entries.map(([key, value]) => `${key}=${value}`).join(",");
+}
+async function ls(deps, args) {
+    const usage = "nylorun sandbox ls [--tenant <name>] [--label <key=value>]... [--json]";
+    const flags = parseStackFlags(args, { booleans: ["--json"], values: ["--tenant"], lists: ["--label"] }, usage);
+    if (flags.rest.length)
+        throw usageError(`Usage: ${usage}`);
+    const query = new URLSearchParams();
+    for (const label of flags.lists.get("--label") ?? []) {
+        if (label.indexOf("=") <= 0)
+            throw usageError(`--label must be key=value, not ${label}`);
+        query.append("label", label);
+    }
+    const name = flags.values.get("--tenant");
+    const api = await runningTenantApi(deps, name === undefined ? {} : { name });
+    const search = query.toString();
+    const { body } = await call(deps, api, "GET", `/v1/sandboxes${search ? `?${search}` : ""}`);
+    const sandboxes = (body.sandboxes ?? []);
+    if (flags.booleans.has("--json")) {
+        deps.out(JSON.stringify(sandboxes, null, 2));
+        return 0;
+    }
+    if (sandboxes.length === 0) {
+        deps.out(`No sandboxes on Tenant ${api.name}.`);
+        return 0;
+    }
+    const rows = [
+        ["ID", "KIND", "STATE", "SESSIONS", "LABELS"],
+        ...sandboxes.map((sandbox) => [
+            sandbox.id,
+            sandbox.kind,
+            sandbox.state,
+            String(sandbox.sessions.length),
+            labelsText(sandbox.labels),
+        ]),
+    ];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    for (const row of rows)
+        deps.out(row
+            .map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd(widths[column])))
+            .join("  "));
+    return 0;
+}
+async function rm(deps, args) {
+    const usage = "nylorun sandbox rm <id> [--tenant <name>]";
+    const flags = parseStackFlags(args, { values: ["--tenant"] }, usage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${usage}`);
+    const id = flags.rest[0];
+    const name = flags.values.get("--tenant");
+    const api = await runningTenantApi(deps, name === undefined ? {} : { name });
+    const { status, body } = await call(deps, api, "DELETE", `/v1/sandboxes/${encodeURIComponent(id)}`);
+    if (status === 404 || body.deleted !== true) {
+        deps.err(`No sandbox ${id} on Tenant ${api.name}.`);
+        return 1;
+    }
+    deps.out(`Deleted sandbox ${id} and its files.`);
+    return 0;
+}
+/** `nylorun sandbox <ls|rm|enable|disable|status> ...` */
+export async function sandboxCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "ls" || sub === "list")
+        return ls(deps, rest);
+    if (sub === "rm" || sub === "delete")
+        return rm(deps, rest);
+    if (sub === "enable" || sub === "disable" || sub === "status")
+        return runSandboxCommand(args, { stack: deps, kubectl: spawnKubectl(deps.env) });
+    throw usageError(`Usage:\n${sandboxUsage}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.7.0-beta",
+  "version": "0.9.0-beta",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Set up and run local Nylorun Tenants (Runtime and Studio) with Docker Compose",
@@ -30,18 +30,18 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/core": "0.11.0-beta"
+    "@nylorun/core": "0.13.0-beta"
   },
   "devDependencies": {
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "@types/node": "^26.5.0",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.2"
   },
   "bin": {
     "nylorun": "dist/cli.js"
   },
   "nylorun": {
-    "runtime": "0.15.2-beta",
-    "studio": "0.18.0-beta"
+    "runtime": "0.17.0-beta",
+    "studio": "0.20.0-beta"
   }
 }

package/dist/project/derived-key.d.ts

@@ -1,8 +0,0 @@
-/** The derived principal a Project uses; the local Runtime registers it on its Tenant. */
-export declare const PROJECT_PRINCIPAL_ID = "project";
-/**
- * Key of a derived principal on the local Tenant, from the admin key. A copy of
- * `deriveTenantKey` in `@nylorun/admin` (nylorun depends on `@nylorun/core` only); both are
- * tested against the same fixed vector.
- */
-export declare function deriveTenantKey(adminKey: string, tenantId: string, principalId: string): string;

package/dist/project/derived-key.js

@@ -1,18 +0,0 @@
-import { createHmac } from "node:crypto";
-/** The derived principal a Project uses; the local Runtime registers it on its Tenant. */
-export const PROJECT_PRINCIPAL_ID = "project";
-/**
- * Key of a derived principal on the local Tenant, from the admin key. A copy of
- * `deriveTenantKey` in `@nylorun/admin` (nylorun depends on `@nylorun/core` only); both are
- * tested against the same fixed vector.
- */
-export function deriveTenantKey(adminKey, tenantId, principalId) {
-    const message = Buffer.concat([
-        Buffer.from("nylorun/principal/v1", "utf8"),
-        Buffer.from([0]),
-        Buffer.from(principalId, "utf8"),
-        Buffer.from([0]),
-        Buffer.from(tenantId, "utf8"),
-    ]);
-    return createHmac("sha256", Buffer.from(adminKey, "utf8")).update(message).digest("hex");
-}