@nylorun/admin 0.5.0-beta → 0.6.0-beta

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.6.0-beta
+
+### Minor Changes
+
+- 50d0fb5: **The Admin API on its own listener.** A Runtime can serve the Admin API on an operator listener, so the port that faces browsers and reverse proxies serves the Tenant API alone. The stack does this by default.
+
+  - **Runtime.** With an operator listener (`adminPort` in `host.json`, or `NYLORUN_ADMIN_LISTEN_PORT`, `NYLORUN_ADMIN_LISTEN_HOST` and `NYLORUN_ADMIN_ALLOWED_HOSTS` in a container), the public listener answers `/v1/admin/**` with the opaque `404` and the operator listener serves the Admin API, Host shutdown and the Tenant API, never to browsers. Each checks `Host` against its own port. `/ready` needs both listening; a taken port on either exits with code 98. Without one, a single listener serves everything as before.
+  - **Stack.** `nylorun start` publishes the operator port on loopback (`NYLORUN_ADMIN_PORT`, default 8788), writes it to `host.json` as `adminPort`, and points Studio at `runtime:4001`. `nylorun status` prints it.
+  - **Admin client.** Reads `adminPort` from `host.json` and sends Admin API requests there (`admin.adminUrl`); `admin.url` stays the Tenant API URL. A `host.json` without `adminPort` keeps working.
+
+- 9d52189: **Embedding Studio in a desktop app.** Studio can be shown inside a desktop app such as Babai Desktop, in an iframe loaded from its URL and signed in by `postMessage` with a token limited to one Tenant.
+
+  - **`nylorun`.** The local stack lets Babai's origins frame Studio: `NYLORUN_STUDIO_FRAME_ANCESTORS` in `stack/.env` defaults to `nylorun://localhost http://nylorun.localhost` and is passed to the Studio container. `nylorun start --studio-embed-origin <origin>` (repeatable) adds an exact origin, such as a desktop app's dev server, and keeps it across starts until `--studio-embed-origin-reset`. Wildcards are refused. `nylorun status` lists the origins under `Embeds`, and `status --json` as `studio.embedOrigins`.
+  - **`@nylorun/admin`.** `mintStudioLoginToken({ studioUrl, adminKey, tenant?, subject? })` mints a single-use Studio login token from an app's backend. With `tenant`, the session it leads to reaches only that Tenant.
+  - **Studio.** `POST /_studio/sessions` exchanges such a token for a one-hour bearer session kept in the frame's memory; dashboard pages send `frame-ancestors` from the allowlist instead of `X-Frame-Options: DENY`; `?embed=1` hides Studio's branding, follows the app's theme and routes, and reports its own; `/tenants/:tenant/sessions/:session` opens a session by id. The cookie login of `nylorun studio` is unchanged.
+
+    The dashboard routes `/tenants/:tenant`, `/tenants/:tenant/agents/:agent`, `/tenants/:tenant/agents/:agent/sessions/:session`, `/tenants/:tenant/sessions/:session`, `/tenants/:tenant/vault` and `/tenants/:tenant/settings` are now a public contract for embedders: removing or changing one is a breaking change.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [c7614a4]
+- Updated dependencies [679c488]
+- Updated dependencies [c85cd9e]
+- Updated dependencies [4282d5f]
+- Updated dependencies [82d95ef]
+- Updated dependencies [f48f12f]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [c121144]
+- Updated dependencies [6ab4c59]
+- Updated dependencies [6ab4c59]
+- Updated dependencies [2ab8ed1]
+- Updated dependencies [c121144]
+- Updated dependencies [9546ac7]
+- Updated dependencies [9546ac7]
+- Updated dependencies [9d52189]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [18468d9]
+  - @nylorun/core@0.9.0-beta
+
 ## 0.5.0-beta
 
 ### Minor Changes

package/dist/client.d.ts

@@ -1,7 +1,13 @@
 import { type AdminStatus, type AdminTenant, type AdminTenantStatus, type TenantEnvelope } from "@nylorun/core/contracts";
 export type AdminSource = "options" | "environment" | "local-host";
 export interface ResolvedAdmin {
+    /** The Host's Tenant API URL (what a Project link names). */
     url: string;
+    /**
+     * Where the Admin API answers when the Host serves it on its own operator listener
+     * (`adminPort` in host.json). Defaults to `url`.
+     */
+    adminUrl?: string;
     key: string;
     source: AdminSource;
     home: string;
@@ -15,7 +21,10 @@ export declare function resolveAdminConnection(options?: {
     home?: string;
 }): ResolvedAdmin;
 export declare class AdminClient {
+    /** The Host's Tenant API URL. */
     readonly url: string;
+    /** Where Admin API requests go: the operator listener, or `url` on a single-port Host. */
+    readonly adminUrl: string;
     readonly source: AdminSource;
     private readonly key;
     private compatible;

package/dist/client.js

@@ -73,13 +73,19 @@ function readLocalHost(home) {
     }
     const host = config.host;
     const port = config.port;
+    const adminPort = config.adminPort;
     const adminKey = credentials.adminKey;
     if (typeof host !== "string" || typeof port !== "number")
         return undefined;
     if (typeof adminKey !== "string" || !/^[0-9a-f]{64}$/.test(adminKey)) {
         return undefined;
     }
-    return { url: `http://${host}:${port}`, key: adminKey };
+    return {
+        url: `http://${host}:${port}`,
+        // An older Host serves the Admin API on its only port.
+        adminUrl: `http://${host}:${typeof adminPort === "number" ? adminPort : port}`,
+        key: adminKey,
+    };
 }
 /**
  * Resolve Admin API connection once: options → environment → local Host.
@@ -116,6 +122,7 @@ export function resolveAdminConnection(options) {
     if (local) {
         return {
             url: local.url.replace(/\/$/, ""),
+            adminUrl: local.adminUrl.replace(/\/$/, ""),
             key: local.key,
             source: "local-host",
             home,
@@ -180,7 +187,10 @@ async function readBody(response) {
     }
 }
 export class AdminClient {
+    /** The Host's Tenant API URL. */
     url;
+    /** Where Admin API requests go: the operator listener, or `url` on a single-port Host. */
+    adminUrl;
     source;
     key;
     compatible = false;
@@ -188,6 +198,7 @@ export class AdminClient {
     features = [];
     constructor(resolved) {
         this.url = resolved.url;
+        this.adminUrl = resolved.adminUrl ?? resolved.url;
         this.source = resolved.source;
         this.key = resolved.key;
     }
@@ -206,7 +217,7 @@ export class AdminClient {
     async ensureCompatible(signal) {
         if (this.compatible)
             return;
-        const response = await fetch(`${this.url}/health`, {
+        const response = await fetch(`${this.adminUrl}/health`, {
             method: "GET",
             redirect: "error",
             signal,
@@ -233,7 +244,7 @@ export class AdminClient {
     }
     async request(path, init = {}, options = {}) {
         await this.ensureCompatible(init.signal === null ? undefined : init.signal);
-        const response = await fetch(this.url + path, {
+        const response = await fetch(this.adminUrl + path, {
             ...init,
             headers: this.adminHeaders(init),
             redirect: "error",

package/dist/index.d.ts

@@ -6,8 +6,12 @@ export { ERROR_CODES, PROTOCOL_FEATURES, compareVersions };
 export type { ErrorCode };
 export { AdminError };
 export { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey };
+export { mintStudioLoginToken } from "./studio-login.js";
 export interface Admin {
+    /** The Host's Tenant API URL. */
     readonly url: string;
+    /** Where Admin API requests go: the operator listener, or `url` on a single-port Host. */
+    readonly adminUrl: string;
     readonly source: "options" | "environment" | "local-host";
     status(): Promise<AdminStatus>;
     listTenants(): Promise<AdminTenant[]>;

package/dist/index.js

@@ -5,6 +5,7 @@ import { AdminError } from "./errors.js";
 export { ERROR_CODES, PROTOCOL_FEATURES, compareVersions };
 export { AdminError };
 export { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey };
+export { mintStudioLoginToken } from "./studio-login.js";
 export function createAdmin(options) {
     return new AdminClient(resolveAdminConnection(options));
 }

package/dist/studio-login.d.ts

@@ -0,0 +1,20 @@
+import { type StudioLoginTokenResponse } from "@nylorun/core/contracts";
+/**
+ * Mints a single-use Studio login token with the admin key (`POST
+ * /_studio/login-tokens`, Studio §8.4). An app that embeds Studio, such as
+ * Babai, calls this from its backend and hands only the token to its page,
+ * which passes it to the framed Studio in `init`.
+ *
+ * - `tenant` limits the session the token leads to to one Tenant; omit it for
+ *   a Host-wide token (what `nylorun studio` uses).
+ * - `subject` names the person, for Studio's logs.
+ */
+export declare function mintStudioLoginToken(options: {
+    /** Studio's URL, e.g. `studio.url` from `nylorun status --json`. */
+    studioUrl: string;
+    adminKey: string;
+    tenant?: string;
+    subject?: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<StudioLoginTokenResponse>;

package/dist/studio-login.js

@@ -0,0 +1,56 @@
+import { StudioLoginTokenRequestSchema, StudioLoginTokenResponseSchema, } from "@nylorun/core/contracts";
+import { AdminError } from "./errors.js";
+/**
+ * Mints a single-use Studio login token with the admin key (`POST
+ * /_studio/login-tokens`, Studio §8.4). An app that embeds Studio, such as
+ * Babai, calls this from its backend and hands only the token to its page,
+ * which passes it to the framed Studio in `init`.
+ *
+ * - `tenant` limits the session the token leads to to one Tenant; omit it for
+ *   a Host-wide token (what `nylorun studio` uses).
+ * - `subject` names the person, for Studio's logs.
+ */
+export async function mintStudioLoginToken(options) {
+    const body = StudioLoginTokenRequestSchema.safeParse({
+        ...(options.tenant !== undefined ? { tenant: options.tenant } : {}),
+        ...(options.subject !== undefined ? { subject: options.subject } : {}),
+    });
+    if (!body.success)
+        throw new AdminError("invalid_request", `Invalid Studio login token request: ${body.error.issues[0]?.message ?? "invalid"}`);
+    const fetcher = options.fetch ?? fetch;
+    const url = new URL("/_studio/login-tokens", options.studioUrl);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${options.adminKey}`,
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify(body.data),
+            redirect: "error",
+            signal: options.signal ?? AbortSignal.timeout(5000),
+        });
+    }
+    catch (error) {
+        throw new AdminError("connection_missing", `Studio is unavailable at ${url.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        let message = `Studio refused a login token (HTTP ${response.status}).`;
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.message === "string")
+                message = parsed.message;
+        }
+        catch {
+            /* keep the status message */
+        }
+        throw new AdminError(response.status === 401 ? "host_rejected" : "request_rejected", message, { status: response.status });
+    }
+    const parsed = StudioLoginTokenResponseSchema.safeParse(JSON.parse(text));
+    if (!parsed.success)
+        throw new AdminError("incompatible_host", "This Studio does not support login tokens limited to a Tenant; update the stack.");
+    return parsed.data;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/admin",
-  "version": "0.5.0-beta",
+  "version": "0.6.0-beta",
   "description": "Nylorun Admin API client for Tenants and Host status",
   "type": "module",
   "license": "Apache-2.0",
@@ -24,7 +24,7 @@
     "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\""
   },
   "dependencies": {
-    "@nylorun/core": "0.8.0-beta"
+    "@nylorun/core": "0.9.0-beta"
   },
   "peerDependencies": {
     "zod": "^4.6.5"