nylorun 0.8.0-beta → 0.9.0-beta

package/dist/stack/env-file.js

@@ -1,14 +1,10 @@
-import { DERIVED_PRINCIPAL_ID_PATTERN } from "@nylorun/core/compatibility";
 import { parseFrameAncestors } from "@nylorun/core/contracts";
 import { CliError } from "../errors.js";
 /**
- * Origins that may embed Studio by default: Babai Desktop's `nylorun` scheme on
- * macOS and Linux, and its WebView2 origin on Windows (Studio §8.9).
+ * Origins that may embed Studio by default: none. Embedding is opt-in: the operator lists
+ * the exact origins of the app that frames Studio (`--studio-embed-origin`, Studio §8.9).
  */
-export const DEFAULT_STUDIO_FRAME_ANCESTORS = [
-    "nylorun://localhost",
-    "http://nylorun.localhost",
-];
+export const DEFAULT_STUDIO_FRAME_ANCESTORS = [];
 const SANDBOX_KEYS = {
     token: "NYLORUN_SANDBOXES_TOKEN",
     image: "NYLORUN_SANDBOXES_IMAGE",
@@ -38,7 +34,6 @@ const KEYS = {
     studioFrameAncestors: "NYLORUN_STUDIO_FRAME_ANCESTORS",
     studioAnalyticsId: "NYLORUN_STUDIO_ANALYTICS_ID",
     tenantName: "NYLORUN_TENANT_NAME",
-    derivedPrincipals: "NYLORUN_DERIVED_PRINCIPALS",
 };
 /** Compose .env values: single quotes keep a value literal (no interpolation). */
 function quote(key, value) {
@@ -104,8 +99,8 @@ export function renderEnvFile(env) {
         line("runtimeImage"),
         line("studioImage"),
         "",
-        "# Exact origins that may show Studio in a frame (Babai Desktop). Kept across",
-        "# starts; change with nylorun start --studio-embed-origin <origin>.",
+        "# Exact origins that may show Studio in a frame; none by default. Kept across",
+        "# starts; add with nylorun start --studio-embed-origin <origin>.",
         line("studioFrameAncestors"),
         "",
         "# Studio's anonymous usage analytics; empty when off. Set on every start: turn",
@@ -113,10 +108,8 @@ export function renderEnvFile(env) {
         line("studioAnalyticsId"),
         "",
         "# The Tenant's name, which the Runtime gives the Tenant it creates on the first",
-        "# start, and the derived principals it registers on that Tenant (keys derived",
-        "# from the admin key; `project` is the Project link's).",
+        "# start.",
         line("tenantName"),
-        line("derivedPrincipals"),
         "",
         ...(sandboxes
             ? [
@@ -134,20 +127,6 @@ export function renderEnvFile(env) {
             : []),
     ].join("\n");
 }
-/**
- * `NYLORUN_DERIVED_PRINCIPALS`: comma-separated principal ids, as the Runtime accepts them
- * (not `studio`), with `project` first so the Project link's key always works.
- */
-export function parseDerivedPrincipals(raw, source) {
-    const ids = raw
-        .split(",")
-        .map((entry) => entry.trim())
-        .filter((entry) => entry !== "");
-    for (const id of ids)
-        if (!DERIVED_PRINCIPAL_ID_PATTERN.test(id) || id === "studio")
-            throw new CliError(`${source} has '${id}': each entry must match ${DERIVED_PRINCIPAL_ID_PATTERN} and not be studio.`, 2);
-    return [...new Set(["project", ...ids])];
-}
 /** Parse KEY=value lines; comments and blank lines are skipped. */
 export function parseEnvLines(text) {
     const values = new Map();
@@ -218,15 +197,6 @@ export function parsePersisted(text) {
     const objectStoreSecretKey = values.get(KEYS.objectStoreSecretKey);
     if (objectStoreSecretKey && /^[0-9a-f]{64}$/i.test(objectStoreSecretKey))
         out.objectStoreSecretKey = objectStoreSecretKey;
-    const principals = values.get(KEYS.derivedPrincipals);
-    if (principals !== undefined) {
-        try {
-            out.derivedPrincipals = parseDerivedPrincipals(principals, `${KEYS.derivedPrincipals} in docker/.env`);
-        }
-        catch {
-            /* rewritten from the default on the next start */
-        }
-    }
     const sandboxes = parseSandboxes(values);
     if (sandboxes)
         out.sandboxes = sandboxes;

package/dist/stack/index.d.ts

@@ -10,6 +10,12 @@ export declare function stackCommand(name: string, args: readonly string[], env:
 /** Entry for `nylorun sandbox ls|rm`. */
 export declare function sandboxCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
 export { sandboxUsage } from "./sandbox.js";
+/** Entry for `nylorun mcp connect`. */
+export declare function mcpCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+export { mcpUsage } from "./mcp.js";
+/** Entry for `nylorun key put|list|rm`. */
+export declare function keyCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+export { keyUsage } from "./keys.js";
 /** `nylorun studio`, landing on `next` when given, else on the Tenant's page. */
 export declare function studioCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>, options?: {
     next?: string;

package/dist/stack/index.js

@@ -2,7 +2,9 @@ import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { runStackCommand, runStudioCommand } from "./commands.js";
 import { spawnDocker } from "./docker.js";
+import { keyCommand as runKeyCommand } from "./keys.js";
 import { sandboxCommand as runSandboxCommand } from "./sandbox.js";
+import { mcpCommand as runMcpCommand } from "./mcp.js";
 import { pinnedVersion } from "./versions.js";
 import { loopbackPorts } from "./ports.js";
 export { ensureStack, isStackCommand, readStackStatus, stackUsage, studioLoginUrl, tenantStudioPath, STACK_SERVICES, } from "./commands.js";
@@ -20,7 +22,6 @@ function browserCommand(env) {
  */
 const STACK_ENV_OWNED = [
     "NYLORUN_TENANT_NAME",
-    "NYLORUN_DERIVED_PRINCIPALS",
     "NYLORUN_STUDIO_ANALYTICS_ID",
 ];
 /** Real dependencies: docker on PATH, global fetch, the terminal. */
@@ -85,6 +86,16 @@ export async function sandboxCommand(args, env) {
     return await runSandboxCommand(defaultStackDeps(env), args);
 }
 export { sandboxUsage } from "./sandbox.js";
+/** Entry for `nylorun mcp connect`. */
+export async function mcpCommand(args, env) {
+    return await runMcpCommand(defaultStackDeps(env), args);
+}
+export { mcpUsage } from "./mcp.js";
+/** Entry for `nylorun key put|list|rm`. */
+export async function keyCommand(args, env) {
+    return await runKeyCommand(defaultStackDeps(env), args);
+}
+export { keyUsage } from "./keys.js";
 /** `nylorun studio`, landing on `next` when given, else on the Tenant's page. */
 export async function studioCommand(args, env, options = {}) {
     return await runStudioCommand(args, defaultStackDeps(env), options);

package/dist/stack/keys.d.ts

@@ -0,0 +1,4 @@
+import { type StackDeps } from "./commands.js";
+export declare const keyUsage = "  key put <id> [--tenant <name>]     create the Tenant's key <id>, or rotate it (the old key stops working); prints the key once\n  key list [--tenant <name>] [--json] the Tenant's keys: id, role, when issued (never the keys)\n  key rm <id> [--tenant <name>]      delete key <id>: it stops working at once";
+/** `nylorun key <put|list|rm> ...` */
+export declare function keyCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/stack/keys.js

@@ -0,0 +1,72 @@
+/**
+ * `nylorun key put | list | rm`: the running local Tenant's operator keys (F9 I1, Host feature
+ * `operator-keys`), through its Admin API with the admin key. Revocable application keys by
+ * name, for app servers and other clients; none of these starts the Tenant.
+ */
+import { CliError } from "../errors.js";
+import { parseStackFlags, runningAdmin } from "./commands.js";
+import { deleteOperatorKey, listOperatorKeys, putOperatorKey } from "./operator-keys.js";
+export const keyUsage = `  key put <id> [--tenant <name>]     create the Tenant's key <id>, or rotate it (the old key stops working); prints the key once
+  key list [--tenant <name>] [--json] the Tenant's keys: id, role, when issued (never the keys)
+  key rm <id> [--tenant <name>]      delete key <id>: it stops working at once`;
+const usageError = (message) => new CliError(message, 2);
+async function put(deps, args) {
+    const usage = "nylorun key put <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 admin = await runningAdmin(deps, name === undefined ? {} : { name });
+    const key = await putOperatorKey(admin, id);
+    // The key alone on stdout, for scripts; it is not shown again.
+    deps.out(key.key);
+    deps.err(`${key.rotated ? "Rotated" : "Created"} key ${key.id} on Tenant ${admin.name}${key.rotated ? " (the previous key no longer works)" : ""}. Store it now: it is not shown again.`);
+    return 0;
+}
+async function list(deps, args) {
+    const usage = "nylorun key list [--tenant <name>] [--json]";
+    const flags = parseStackFlags(args, { booleans: ["--json"], values: ["--tenant"] }, usage);
+    if (flags.rest.length)
+        throw usageError(`Usage: ${usage}`);
+    const name = flags.values.get("--tenant");
+    const admin = await runningAdmin(deps, name === undefined ? {} : { name });
+    const keys = await listOperatorKeys(admin);
+    if (flags.booleans.has("--json")) {
+        deps.out(JSON.stringify(keys, null, 2));
+        return 0;
+    }
+    const rows = [["ID", "ROLE", "CREATED"], ...keys.map((key) => [key.id, key.role, key.createdAt])];
+    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 key 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 admin = await runningAdmin(deps, name === undefined ? {} : { name });
+    if (!(await deleteOperatorKey(admin, id))) {
+        deps.err(`No key ${id} on Tenant ${admin.name}.`);
+        return 1;
+    }
+    deps.out(`Deleted key ${id}: it no longer works.`);
+    return 0;
+}
+/** `nylorun key <put|list|rm> ...` */
+export async function keyCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "put")
+        return put(deps, rest);
+    if (sub === "list" || sub === "ls")
+        return list(deps, rest);
+    if (sub === "rm" || sub === "delete")
+        return rm(deps, rest);
+    throw usageError(`Usage:\n${keyUsage}`);
+}

package/dist/stack/mcp.d.ts

@@ -0,0 +1,8 @@
+import { type StackDeps } from "./commands.js";
+export declare const mcpUsage = "  mcp connect <url> --server <name> [--vault <id>] [--client-id <id>] [--tenant <name>] [--no-open]\n                                      sign the Tenant in to a remote MCP server with OAuth; the credential goes to the\n                                      installation vault mcp (or --vault), which sessions attach";
+/** The installation vault `connect` uses unless `--vault` names one. */
+export declare const MCP_VAULT_NAME = "mcp";
+/** How long `connect` waits for the browser sign-in: the Runtime keeps it for ten minutes. */
+export declare const CONNECT_TIMEOUT_MS: number;
+/** `nylorun mcp <connect> ...` */
+export declare function mcpCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/stack/mcp.js

@@ -0,0 +1,114 @@
+/**
+ * `nylorun mcp connect <url> --server <name>`: signs the running local Tenant in to a remote MCP
+ * server with OAuth (F9 C2), through its Tenant API with an operator key (`runningTenantApi`).
+ * The Runtime's keys module runs discovery, registration and the code exchange and seals the
+ * credential in an installation vault (`mcp` unless `--vault` names one); this command only
+ * opens the browser and waits for the credential to appear. It never starts the Tenant.
+ */
+import { randomUUID } from "node:crypto";
+import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
+import { CliError } from "../errors.js";
+import { parseStackFlags, runningTenantApi } from "./commands.js";
+export const mcpUsage = `  mcp connect <url> --server <name> [--vault <id>] [--client-id <id>] [--tenant <name>] [--no-open]
+                                      sign the Tenant in to a remote MCP server with OAuth; the credential goes to the
+                                      installation vault mcp (or --vault), which sessions attach`;
+/** The installation vault `connect` uses unless `--vault` names one. */
+export const MCP_VAULT_NAME = "mcp";
+/** How long `connect` waits for the browser sign-in: the Runtime keeps it for ten minutes. */
+export const CONNECT_TIMEOUT_MS = 10 * 60_000;
+const usageError = (message) => new CliError(message, 2);
+async function call(deps, api, method, path, body) {
+    const response = await deps.fetch(`${api.runtimeUrl}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${api.applicationKey}`,
+            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+            accept: "application/json",
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        redirect: "error",
+        signal: AbortSignal.timeout(150_000),
+    });
+    const answer = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        throw new CliError(`${method} ${path} returned ${response.status}${typeof answer.message === "string" ? `: ${answer.message}` : ""}`, 1);
+    return answer;
+}
+/** The URL as the vault binds it: origin, path and query, no default port, no fragment. */
+function bindingUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw usageError(`${input} is not a URL.`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw usageError(`${input} is not an http(s) URL.`);
+    if (url.username || url.password || url.hash)
+        throw usageError(`${input} must not carry userinfo or a fragment.`);
+    return `${url.origin}${url.pathname}${url.search}`;
+}
+/** The installation vault named `mcp`, created when there is none. */
+async function mcpVault(deps, api) {
+    const { vaults } = await call(deps, api, "GET", "/v1/vaults");
+    const found = vaults.find((vault) => vault.ownerUserId === "installation" && vault.name === MCP_VAULT_NAME);
+    if (found)
+        return found;
+    const key = `nylorun-mcp-${randomUUID()}`;
+    return await call(deps, api, "POST", "/v1/vaults", {
+        requestId: key,
+        idempotencyKey: key,
+        name: MCP_VAULT_NAME,
+        scope: "installation",
+    });
+}
+/** Each credential of the vault bound to `url`, by id, with when it last changed. */
+async function credentialsFor(deps, api, vaultId, url) {
+    const { credentials } = await call(deps, api, "GET", `/v1/vaults/${encodeURIComponent(vaultId)}/credentials`);
+    return new Map(credentials
+        .filter((item) => item.type === "oauth" && item.binding.url === url)
+        .map((item) => [item.id, item.rotatedAt ?? item.createdAt]));
+}
+async function connect(deps, args) {
+    const usage = "nylorun mcp connect <url> --server <name> [--vault <id>] [--client-id <id>] [--tenant <name>] [--no-open]";
+    const flags = parseStackFlags(args, { booleans: ["--no-open"], values: ["--server", "--vault", "--client-id", "--tenant"] }, usage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${usage}`);
+    const server = flags.values.get("--server");
+    if (!server)
+        throw usageError(`--server names the MCP server, as the agent declares it. Usage: ${usage}`);
+    const url = bindingUrl(flags.rest[0]);
+    const clientId = flags.values.get("--client-id");
+    const name = flags.values.get("--tenant");
+    const api = await runningTenantApi(deps, name === undefined ? {} : { name });
+    const vaultId = flags.values.get("--vault") ?? (await mcpVault(deps, api)).id;
+    const before = await credentialsFor(deps, api, vaultId, url);
+    const started = await call(deps, api, "POST", `/v1/vaults/${encodeURIComponent(vaultId)}/oauth/start`, { url, server, ...(clientId === undefined ? {} : { clientId }) });
+    deps.out(`Sign in to ${server} in your browser:`);
+    deps.out(`  ${started.authorizeUrl}`);
+    if (!flags.booleans.has("--no-open"))
+        await deps.openBrowser(started.authorizeUrl);
+    deps.out("Waiting for the sign-in to finish…");
+    const deadline = Math.min(Date.now() + CONNECT_TIMEOUT_MS, Date.parse(started.expiresAt) || Infinity);
+    const pollMs = deps.pollMs ?? 1000;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        const now = await credentialsFor(deps, api, vaultId, url);
+        for (const [id, changed] of now)
+            if (before.get(id) !== changed) {
+                deps.out(`Connected ${server} (${url}): credential ${id} in installation vault ${vaultId}.`);
+                deps.out(`Sessions use it when they attach the vault: vaultIds: ["${vaultId}"].`);
+                return 0;
+            }
+    }
+    throw new CliError(`The sign-in to ${server} did not finish in time. Run "nylorun mcp connect" again; the browser page says why when the server refused it.`, 1);
+}
+/** `nylorun mcp <connect> ...` */
+export async function mcpCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "connect")
+        return connect(deps, rest);
+    throw usageError(`Usage:\n${mcpUsage}`);
+}

package/dist/stack/operator-keys.d.ts

@@ -0,0 +1,39 @@
+import type { OperatorKey, PutOperatorKeyResponse } from "@nylorun/core/contracts";
+import { type KeyCredentials } from "../project/link.js";
+import type { FetchLike } from "./studio-login.js";
+/** Where a local Tenant's Admin API answers, and its admin key. */
+export interface AdminEndpoint {
+    fetch: FetchLike;
+    adminUrl: string;
+    adminKey: string;
+}
+/** The key `nylorun start` gives the projects it links. */
+export declare const PROJECT_KEY_ID = "project";
+/** The key nylorun commands use outside a linked project. */
+export declare const CLI_KEY_ID = "cli";
+/** Creates key `id` or rotates it; the answer holds the key, this once. */
+export declare function putOperatorKey(admin: AdminEndpoint, id: string): Promise<PutOperatorKeyResponse>;
+export declare function listOperatorKeys(admin: AdminEndpoint): Promise<OperatorKey[]>;
+/** Deletes key `id`: false when there is none. */
+export declare function deleteOperatorKey(admin: AdminEndpoint, id: string): Promise<boolean>;
+/**
+ * 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 declare function keyAuthenticates(fetch: FetchLike, runtimeUrl: string, key: string): Promise<boolean>;
+/**
+ * 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 declare function hostKey(options: {
+    admin: AdminEndpoint;
+    runtimeUrl: string;
+    id: string;
+    file: string;
+    lock: string;
+    adopt?: KeyCredentials;
+}): Promise<KeyCredentials & {
+    put: boolean;
+}>;

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,8 +8,25 @@ 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;
     /**

package/dist/stack/paths.js

@@ -7,7 +7,11 @@ 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"),

package/dist/stack/prepare.d.ts

@@ -32,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[];

package/dist/stack/prepare.js

@@ -1,9 +1,10 @@
 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";
@@ -86,9 +87,6 @@ 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
@@ -108,6 +106,8 @@ export async function prepareStack(input) {
         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.js

@@ -1,6 +1,6 @@
 /**
  * `nylorun sandbox ls | rm`: the running local Tenant's sandbox resources (Host feature
- * `sandboxes`), through its Tenant API as the Project's derived principal. Neither starts the
+ * `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`.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.8.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,7 +30,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/core": "0.12.0-beta"
+    "@nylorun/core": "0.13.0-beta"
   },
   "devDependencies": {
     "typescript": "npm:@typescript/typescript6@^6.0.2",
@@ -41,7 +41,7 @@
     "nylorun": "dist/cli.js"
   },
   "nylorun": {
-    "runtime": "0.16.0-beta",
-    "studio": "0.19.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;