nylorun 0.8.0-beta → 0.9.0-beta

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # nylorun
 
+## 0.9.0-beta
+
+### Major Changes
+
+- bd478ee: **Subject tokens, browser keys and derived principals leave open source (F9 I3, protocol 7).** Upgrade these with the Runtime: they speak protocol 7, which this Runtime serves beside 4, 5 and 6; protocol 6 clients keep working on every route that remains. Browsers and apps present a trusted issuer's token (F9 I2), servers an operator key (F9 I1), and a person's own credentials come from the operator's credential resolver (F9 C1). See MIGRATION.md.
+
+  - **Breaking (`@nylorun/runtime`, `@nylorun/core`): subject tokens are gone.** `POST /v1/tokens`, `POST /v1/access/revocations`, subject-token verification, revocation epochs and the `subject.revoked` stream signal are removed; the routes answer `404`, and a JWT no trusted issuer signed is the opaque `404`. A stream opened with a token now ends only at its expiry (`event: nylorun.closed`, reason `token_expired`; `StreamClosedFrame` loses `revoked`). Migration `0010_oss_auth_removals` drops the `subject_epochs`, `subject_usage` and `publishable_keys` tables. The `token` caller is a trusted issuer's token only: it loses `role`, `limits` and `epoch`, and `issuer` is always set; `GET /v1/me` no longer reports `via: token`. Core drops `SUBJECT_TOKEN_TYPE`, `SUBJECT_TOKEN_AUDIENCE`, `subjectTokenIssuer` (the Runtime's own tokens use `tenantTokenIssuer`, same value), `CreateTokenRequest`/`Response`, `RevokeSubject*`, `SubjectTokenClaims`, `TOKEN_TTL_MIN_SECONDS` and `TOKEN_TTL_DEFAULT_SECONDS`; `TOKEN_SCOPES` is `agents:read`, `sessions:own`, `sandboxes:write`.
+  - **Breaking (`@nylorun/runtime`, `@nylorun/core`): the access policy and role limits are gone.** `GET`/`PUT /v1/access/policy` answer `404`, a turn is never refused with `429 limit_exceeded` for a role (limit requests at your proxy), and an existing `access.policy` setting is ignored. Core drops `AccessPolicy*`, `AccessRole*`, `RoleLimits*`, `DEFAULT_ACCESS_POLICY`, `PutAccessPolicyRequest` and `ROLE_NAME_PATTERN`.
+  - **Breaking (`@nylorun/runtime`, `@nylorun/core`): publishable keys and the Runtime's CORS are gone.** `/v1/access/publishable-keys*` answer `404`, `Nylorun-Key` is ignored, `NYLORUN_BROWSER_ACCESS` and `browserAccess` (host.json, `createHost`, `startEphemeralRuntime`) are removed, and the Runtime sends no CORS headers. A request with `Origin` reaches the Tenant routes of the public listener with no toggle: a trusted issuer's token is served, an application key or delivery token is `403 origin_rejected`; admin routes, `/health`, `/ready` and the operator listener still refuse `Origin`. Any `OPTIONS` request is `204` with `Allow` and no CORS header: the operator's proxy answers preflights. Route declarations lose `browser` (`x-nylorun-browser` leaves the OpenAPI document) and the `publishable` credential; the token security scheme is `issuerToken`. Core drops `PUBLISHABLE_KEY_HEADER`, `PUBLISHABLE_KEY_PATTERN`, `PUBLISHABLE_KEY_ID_PATTERN`, `tenantOfPublishableKey`, `newPublishableKey`, `newPublishableKeyId`, `PublishableKey*`, `OriginEntrySchema`, `originAllowed` and `LOOPBACK_ORIGIN_WILDCARDS`.
+  - **Breaking (`@nylorun/runtime`, `@nylorun/core`, `@nylorun/agents`): vault routes are application-only, and `vaults:own` is retired.** Every `/v1/vaults` route takes an application key acting for no one (operator keys, Studio); a request acting for a subject or a trusted issuer's token gets `403 scope_required`. `vaults:own` leaves `SUBJECT_SCOPES`, `TOKEN_SCOPES` and the issuer scopes; `Nylorun-Scopes` may still name it and it grants nothing. Existing user vaults stay attachable to their own owner's sessions. `client.createVault` takes `{ scope: "installation" }` or `ownerUserId`, and `client.listVaults()` takes an optional owner.
+  - **Breaking (`@nylorun/runtime`, `@nylorun/core`, `@nylorun/admin`, `nylorun`): derived principals are gone.** Only Studio's key is derived from the admin key. `NYLORUN_DERIVED_PRINCIPALS` is ignored and no longer written, `hostPrincipals` takes no `derived`, `startEphemeralRuntime` no `derivedPrincipals`, and `@nylorun/admin` drops `deriveTenantKey`, `PROJECT_PRINCIPAL_ID` and `admin.deriveTenantKey`. Keys an earlier Host derived stay in the database and keep working as ordinary keys; replace them with operator keys. Core renames `DERIVED_PRINCIPAL_ID_PATTERN` to `APPLICATION_KEY_ID_PATTERN`.
+  - **Breaking (`@nylorun/agents`):** `createTokenEndpoint`, `createBrowserClient` and the `@nylorun/agents/browser` entry, `client.tokens`, `TokensClient`, `PublishableKeysClient`, `client.access.getPolicy`/`putPolicy`/`revokeSubject`/`publishableKeys` and `Destination.publishableKey` are removed. `client.access.signingKeys` and `client.access.jwks()` stay, and `Destination.token` takes a trusted issuer's tokens.
+  - **Breaking (`@nylorun/cli`):** `nylo access policy|keys|revoke|token` are removed and name what replaces them; `nylo access signing-keys list|rotate|revoke` stays.
+  - **Breaking (`@nylorun/core`, `@nylorun/agents`, `@nylorun/studio`): the Studio embed message `open.babai` is now `open.session`** (`{ sessionId }`): it asks the embedding app to open that session in its own UI. Studio sends no such message itself.
+  - **Breaking (`nylorun`): Studio embedding is opt-in.** No origin may frame Studio by default; list your app's origins with `nylorun start --studio-embed-origin <origin>`. A Tenant's `.env` from an earlier nylorun keeps the origins it had until `--studio-embed-origin-reset`.
+  - `PROTOCOL_VERSION` is 7 and `HOST_PROTOCOL` 4–7; the Host features `subject-tokens`, `browser-access` and `derived-principals` are removed. `@nylorun/studio` and `@nylorun/create-agent` speak protocol 7.
+
+### Minor Changes
+
+- 8773586: **Installation vaults and a credential resolver (F9 C1).** A session's MCP credential now comes from its attached vaults, then from the operator's own credential resolver; nothing changes for existing vaults, and the protocol stays at 6.
+
+  - Installation vaults: `POST /v1/vaults` takes `scope: "installation"` (no `ownerUserId`) from an application key acting for no one; a request acting for a subject gets `403`. The vault is owned by `installation`, now a reserved subject like `host`. Any session may attach one and select its credentials. `GET /v1/vaults` from an application key lists them after the named person's vaults, and lists only them without `ownerUserId`; a request acting for a subject never sees one (the opaque `404`). The host model vault stays hidden and unattachable. Migration 0008 adds the scope.
+  - The credential resolver: `NYLORUN_RESOLVER_URL` and `NYLORUN_RESOLVER_TOKEN` on the gateway (`TenantConfig.resolver` and `startEphemeralRuntime({ resolver })` in process). When the session's vaults hold nothing for a remote MCP server's URL, the Runtime POSTs `{ owner, session, turn, target: { kind: "mcp", server, agent, url } }` with the resolver's bearer: `200 { headers, expiresAt? }` is used, `404` goes without a credential, and anything else or no answer within 5 s refuses the server with `credential_unavailable`. Owner and turn come from the session row. Answers are cached per owner and URL until `expiresAt`, at most 5 minutes (60 s without one), and concurrent misses share one request. See DEPLOYMENT.md, Credentials.
+  - `nylorun`: the gateway's Compose service passes `NYLORUN_RESOLVER_URL` and `NYLORUN_RESOLVER_TOKEN` from the shell that runs `nylorun start` (unset by default).
+  - Studio: the Vault page is now **Connections**, and creates installation vaults.
+
+- e1bfb4b: **MCP OAuth connect for installation vaults (F9 C2).** The installation can sign in once to a remote MCP server that uses OAuth, and every session that attaches the vault uses the credential. Additive; the protocol stays at 6.
+
+  - `POST /v1/vaults/{vaultId}/oauth/start` (application keys acting for no one, installation vaults only) takes `{ url, server, clientId? }` and answers `{ authorizeUrl, expiresAt }`. The Runtime discovers the server's authorization server (RFC 9728, then RFC 8414), registers itself (RFC 7591) unless `clientId` names a registered client, and starts an S256 PKCE sign-in whose `state` works once, for ten minutes. A server without registration and no `clientId` is `400 oauth_client_required`.
+  - `GET /v1/oauth/callback` takes the browser back: anonymous and unversioned like an artifact link, it exchanges the code and stores an `oauth` credential bound to the URL, named after `server` (connecting again rotates it), and answers a small HTML page. An unknown, used or expired `state` is `oauth_state_invalid`; the authorization server's refusal is `oauth_failed`. The callback's base is `NYLORUN_PUBLIC_URL` (`TenantConfig.publicUrl`), else the start request's origin.
+  - Every OAuth step runs in the gateway's keys module (F9-D14): the runtime container never sees a token, the PKCE verifier or a client secret, and makes no outbound call. Migration 0009 adds `oauth_pending`, with the verifier and secret sealed under the vault key. `Keys` gains `startOAuth` and `finishOAuth`.
+  - OAuth requests, including refresh of every OAuth vault credential, now go through `guardedFetch` (`tenant/outbound.ts`): the `NYLORUN_ENDPOINT_*` address policy checked on the address connected to, no redirects, a bounded answer. With `NYLORUN_ENDPOINT_PRIVATE=refuse` a token endpoint on a private address is refused, where refresh used to call it.
+  - `@nylorun/core`: `ERROR_CODES` adds `oauth_client_required`, `oauth_state_invalid` and `oauth_failed`; `StartOAuthRequestSchema` and `StartOAuthResponseSchema`.
+  - `nylorun mcp connect <url> --server <name> [--vault <id>] [--client-id <id>]`: creates the installation vault `mcp` if needed, opens the sign-in page and waits up to 10 minutes for the credential. See DEPLOYMENT.md, "Connecting a remote MCP server with OAuth".
+
+- 5cfaed9: **Operator keys, and project links on them (F9 I1).** The Admin API manages the Tenant's application keys by name: `PUT /v1/admin/keys/{id}` creates a key or rotates it and returns it once, `GET /v1/admin/keys` lists every key's id, role and issue time (never the keys), and `DELETE /v1/admin/keys/{id}` removes one. A rotated or deleted key stops authenticating on its next request. Ids follow `^[a-z][a-z0-9-]{0,31}$`; `studio` (derived from the admin key) is refused. Keys keep today's format (64 hex) and only their SHA-256 is stored, in the existing principals table (no migration). Host feature `operator-keys` (additive, protocol unchanged); core adds the `OperatorKey`, `ListOperatorKeysResponse`, `PutOperatorKeyResponse` and `DeleteOperatorKeyResponse` schemas.
+
+  - `@nylorun/admin`: `admin.keys.put(id)`, `admin.keys.list()` and `admin.keys.delete(id)`; they refuse with `incompatible_host` when the Host lacks `operator-keys`.
+  - `nylorun key put|list|rm <id>` manages a running local Tenant's keys; `put` prints the key once on stdout.
+  - `nylorun start` no longer derives the project's key. It keeps `.nylorun/credentials.json` while its key still reaches the Tenant (one authenticated read); otherwise it gives the project the operator key `project`, which the Host root keeps in `project-credentials.json` (0600) so every checkout linked to the Tenant shares it. An existing derived project key keeps working and is adopted.
+  - `nylorun sandbox` uses the linked project's key, or the operator key `cli` it puts once and keeps in `<Host root>/cli-credentials.json` (0600).
+  - The ephemeral Runtime (`startEphemeralRuntime`) no longer registers the derived `project` principal; pass `derivedPrincipals: ["project"]` to keep it. Derived principals (`NYLORUN_DERIVED_PRINCIPALS`, `deriveTenantKey`) still work on a Host.
+
+- b906050: **Studio for a team (F9 S1).** Studio can sit behind a sign-in proxy such as oauth2-proxy. A request with no Studio session that carries a JWT, in `X-Forwarded-Access-Token` or as an `Authorization` bearer that is not a Studio session, signs in when the Runtime's `GET /v1/me` verifies it and reports the `studio` scope: Studio sets its usual signed session cookie, which records the subject for its write log and ends no later than the token (at most the usual 30 days), and serves the request. Studio never trusts the header unverified and keeps nothing else. A token without the scope gets `403` naming `studio`; a token the Runtime refuses, or one that is not a JWT, gets `401`. Admitted people get Studio's Tenant-wide view; the CLI sign-in and embedding are unchanged, and a valid embed bearer session still wins. New `NYLORUN_STUDIO_ALLOWED_HOSTS`: extra `Host` values Studio serves, comma-separated (`studio.acme.dev`); its state changes accept that host's `https` and `http` origins, and the cookie is `Secure` when the proxy sends `X-Forwarded-Proto: https`. The default is unchanged: only `localhost` and `127.0.0.1` on the published port. `nylorun start` passes `NYLORUN_STUDIO_ALLOWED_HOSTS` from its environment to the Studio container.
+- c0b604e: **Trusted issuers (F9 I2).** The Tenant API accepts JWTs from the operator's own identity provider as bearers, configured in an identity file: `NYLORUN_IDENTITY_FILE` names a YAML file listing each issuer's `name`, `issuer`, `audience`, `jwks` URL or static PEM `keys`, a `subject` template over scalar claims (`u:{sub}`), `scopes` from a claim or a fixed list, `allowedScopes`, an optional `agents` allowlist, optional `sandboxes` grant templates (`{org_id}/*`) and `maxLifetime`. A malformed file stops the boot, naming the issuer and the field; a subject template without a claim is malformed. A bearer whose unverified `iss` names an issuer is verified with RS256, ES256 or EdDSA only, up to 16 KiB, `aud` matching, `exp` and `iat` required and `exp − iat` within `maxLifetime`, and becomes a token caller (`role: issuer:<name>`) with the issuer's scopes, agents and rendered sandbox grants; subject revocation does not reach it. JWKS keys are fetched only from the configured URL (no redirects), cached by `kid`, refetched at most once a minute for an unknown `kid`; while a JWKS is unreachable cached keys keep working and a new `kid` is `401 issuer_unavailable` (new error code). A browser request with an issuer token needs no publishable key (CORS comes from the operator's proxy). New: `GET /v1/me` reports the subject, scopes, agents, sandbox grants and `via` (`application:<id>`, `subject`, `token` or `issuer:<name>`) of any credential; the issuer-only scope `studio`; `ISSUER_SCOPES`, `CALLER_SCOPES` and `MeResponseSchema` in `@nylorun/core/contracts`; `parseIdentityFile` and `createTrustedIssuers` in `@nylorun/runtime`, and an `issuers` option on `startEphemeralRuntime`; Host feature `trusted-issuers` (additive, protocol unchanged). `nylorun start` sets `NYLORUN_IDENTITY_FILE=/nylorun/identity.yaml` on the runtime container when `<Host root>/identity.yaml` exists.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [8773586]
+- Updated dependencies [e1bfb4b]
+- Updated dependencies [5cfaed9]
+- Updated dependencies [bd478ee]
+- Updated dependencies [c0b604e]
+  - @nylorun/core@0.13.0-beta
+
 ## 0.8.0-beta
 
 ### Major Changes

package/README.md

@@ -46,6 +46,10 @@ nylorun ls [--json]                # the Tenants on this machine, with their sta
 nylorun delete <tenant> --yes      # remove a Tenant: containers, volumes, Host root and vault key
 nylorun sandbox ls [--tenant <name>] [--label <key=value>]... [--json]   # the running Tenant's sandboxes
 nylorun sandbox rm <id> [--tenant <name>]   # delete a sandbox and its files
+nylorun key put <id> [--tenant <name>]      # create or rotate the Tenant's operator key <id>; prints it once
+nylorun key list [--tenant <name>] [--json] # the Tenant's keys: id, role, when issued
+nylorun key rm <id> [--tenant <name>]       # delete a key: it stops working at once
+nylorun 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
 nylorun doctor [--json]            # prerequisites and the Tenant's health
 nylorun telemetry [status|enable|disable]   # Studio's anonymous usage analytics
 nylorun sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--no-pull]
@@ -137,8 +141,12 @@ its own `.gitignore` of `*`):
 - `link.json`: `{ "format": 3, "tenant", "tenantId", "hostUrl", "hostId" }`.
   `tenant` is the local Tenant's name; the Tenant id is information only:
   nothing in a request selects a Tenant.
-- `credentials.json` (mode 0600): the key of the derived principal `project`,
-  derived from the Tenant's admin key, and its id.
+- `credentials.json` (mode 0600): `{ "format": 1, "applicationKey",
+  "principalId" }`, the operator key `project`. A later `start` keeps the file
+  while its key still reaches the Tenant (one authenticated read); otherwise it
+  writes the Tenant's `project` key, which the Host root keeps in
+  `project-credentials.json` (mode 0600) so every checkout linked to the Tenant
+  shares one key, or puts a new one through the Admin API.
 
 Later starts reuse the Tenant and rewrite the link only when the Tenant's name,
 URL, Host or id changed (after `nylorun reset`, for example). When it writes a
@@ -154,9 +162,28 @@ both share it. `--no-link` starts a Tenant without linking the working
 directory (scripts). A link of an older nylorun (format 0 to 2) counts as no
 link: `start` replaces it.
 
-The Runtime registers the derived principals of `NYLORUN_DERIVED_PRINCIPALS`
-(comma-separated, from the environment of `nylorun start`, kept in the Tenant's
-`.env`) when it creates the Tenant; `project` is always among them.
+No key is derived from the admin key but Studio's. A project holds the operator
+key `project`; a key an older nylorun derived for it keeps working while it
+authenticates and is replaced by the operator key otherwise.
+
+## Operator keys
+
+`nylorun key put <id>` creates the running Tenant's key `<id>` (or rotates it:
+the previous key stops working at once) and prints it once on stdout.
+`nylorun key list [--json]` shows each key's id, role and when it was issued,
+never the keys; `nylorun key rm <id>` deletes one. Ids match
+`^[a-z][a-z0-9-]{0,31}$`; `studio` belongs to Studio and is refused. Give each
+app server its own key. `nylorun sandbox` and `nylorun mcp` use the linked
+project's key, or the key `cli` they put once and keep in
+`<Host root>/cli-credentials.json` (mode 0600).
+
+`nylorun mcp connect <url> --server <name>` signs the running Tenant in to a
+remote MCP server that uses OAuth: it opens the server's sign-in page in the
+browser and waits until the Runtime has stored the credential in the
+installation vault `mcp` (created if needed; `--vault <id>` picks another),
+which sessions attach with `vaultIds`. Pass `--client-id` when the server does
+not let clients register themselves. See
+[Connecting a remote MCP server with OAuth](../DEPLOYMENT.md#connecting-a-remote-mcp-server-with-oauth).
 
 ## The containers
 
@@ -212,14 +239,16 @@ out of another.
 
 ### Embedding Studio in a desktop app
 
-A desktop app such as Babai Desktop can show Studio inside its own window, in
-an iframe loaded from Studio's URL (`studio.url` in `nylorun status --json`).
-Only exact origins listed in `NYLORUN_STUDIO_FRAME_ANCESTORS` (in
-`~/.nylorun/tenants/<name>/docker/.env`) may frame it. The default is Babai's
-`nylorun://localhost http://nylorun.localhost`; `nylorun status` lists them
-under `Embeds`. While building such an app, add its dev server once with
-`nylorun start --studio-embed-origin http://localhost:1420`; the list is kept
-across starts until `--studio-embed-origin-reset`. Wildcards are refused.
+A desktop or web app can show Studio inside its own window, in an iframe loaded
+from Studio's URL (`studio.url` in `nylorun status --json`). Embedding is
+opt-in: only exact origins listed in `NYLORUN_STUDIO_FRAME_ANCESTORS` (in
+`~/.nylorun/tenants/<name>/docker/.env`) may frame it, and the list is empty by
+default. Add the app's origins once with `nylorun start --studio-embed-origin
+<origin>` (for example `app://localhost`, or a dev server's
+`http://localhost:1420`); the list is kept across starts until
+`--studio-embed-origin-reset`, and `nylorun status` shows it under `Embeds`.
+Wildcards are refused. A Tenant started by an older nylorun keeps the origins it
+had.
 
 The app's backend mints a single-use login token for the Tenant with
 `mintStudioLoginToken` from `@nylorun/admin` (it needs the admin key), and its
@@ -279,8 +308,9 @@ The **Host root** is `~/.nylorun/tenants/<name>/`, or `NYLORUN_HOME`. It is
 bind-mounted into the Runtime and Studio containers, and holds `tenant.json`
 (`{ "format": 1, "name", "project"? }`: the Tenant's name and the project it
 was created for), `host.json` (the client-facing host and port),
-`host-credentials.json` (the admin key, mode 0600), the Docker Compose files in
-`docker/`, the Tenant directory `tenant/` (homes, logs) and `keys/vault-kek`,
+`host-credentials.json` (the admin key, mode 0600), `project-credentials.json`
+and `cli-credentials.json` (the operator keys `project` and `cli`, mode 0600, when
+they were put), the Docker Compose files in `docker/`, the Tenant directory `tenant/` (homes, logs) and `keys/vault-kek`,
 the Tenant's vault key, which only the gateway container mounts. The Tenant's data lives in its Postgres, Restate and S2 volumes.
 
 `nylorun reset` deletes the selected Tenant's volumes, `tenant/` and `keys/`, and keeps

package/dist/cli.js

@@ -2,12 +2,14 @@
 import "./baseline.js";
 import { baselineEnv } from "./baseline.js";
 import { CliError } from "./errors.js";
-import { isStackCommand, sandboxCommand, sandboxUsage, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
-const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|sandbox|doctor|telemetry>
+import { isStackCommand, keyCommand, keyUsage, mcpCommand, mcpUsage, sandboxCommand, sandboxUsage, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
+const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|sandbox|key|mcp|doctor|telemetry>
 
 Local Tenants (Docker Compose), one per project:
 ${stackUsage}
 ${sandboxUsage}
+${keyUsage}
+${mcpUsage}
   doctor [--json]                     check Node, Docker and Compose v2, and the Tenant's health
   telemetry [status|enable|disable]   Studio's anonymous usage analytics (on unless disabled,
                                       NYLORUN_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 or CI)
@@ -50,6 +52,14 @@ async function main() {
         process.exitCode = await sandboxCommand(args, baselineEnv());
         return;
     }
+    if (command === "mcp") {
+        process.exitCode = await mcpCommand(args, baselineEnv());
+        return;
+    }
+    if (command === "key") {
+        process.exitCode = await keyCommand(args, baselineEnv());
+        return;
+    }
     if (isStackCommand(command)) {
         process.exitCode = await stackCommand(command, args, baselineEnv());
         return;

package/dist/project/link.d.ts

@@ -22,13 +22,19 @@ export declare function writeProjectLink(projectRoot: string, link: {
     hostId: string;
     tenantId: string;
 }): Promise<void>;
-/** The Project's application key and principal, or undefined when absent or unreadable. */
-export declare function readProjectCredentials(projectRoot: string): Promise<{
+/** An application key and its principal: `credentials.json`'s content (format 1). */
+export interface KeyCredentials {
     applicationKey: string;
     principalId: string;
-} | undefined>;
+}
+/** The Project's application key and principal, or undefined when absent or unreadable. */
+export declare function readProjectCredentials(projectRoot: string): Promise<KeyCredentials | undefined>;
+/**
+ * A credentials file (`{ format: 1, applicationKey, principalId }`): the Project's, or one the
+ * nylorun commands keep in the Host root. Undefined when absent or unreadable.
+ */
+export declare function readCredentialsFile(path: string): Promise<KeyCredentials | undefined>;
 /** `.nylorun/credentials.json` (format 1, mode 0600). */
-export declare function writeProjectCredentials(projectRoot: string, credentials: {
-    applicationKey: string;
-    principalId: string;
-}): Promise<void>;
+export declare function writeProjectCredentials(projectRoot: string, credentials: KeyCredentials): Promise<void>;
+/** A credentials file (format 1), written atomically with mode 0600. */
+export declare function writeCredentialsFile(path: string, credentials: KeyCredentials): Promise<void>;

package/dist/project/link.js

@@ -69,8 +69,15 @@ export async function writeProjectLink(projectRoot, link) {
 }
 /** The Project's application key and principal, or undefined when absent or unreadable. */
 export async function readProjectCredentials(projectRoot) {
+    return await readCredentialsFile(credentialsPath(projectRoot));
+}
+/**
+ * A credentials file (`{ format: 1, applicationKey, principalId }`): the Project's, or one the
+ * nylorun commands keep in the Host root. Undefined when absent or unreadable.
+ */
+export async function readCredentialsFile(path) {
     try {
-        const value = JSON.parse(await readFile(credentialsPath(projectRoot), "utf8"));
+        const value = JSON.parse(await readFile(path, "utf8"));
         return typeof value.applicationKey === "string" && typeof value.principalId === "string"
             ? { applicationKey: value.applicationKey, principalId: value.principalId }
             : undefined;
@@ -82,7 +89,11 @@ export async function readProjectCredentials(projectRoot) {
 /** `.nylorun/credentials.json` (format 1, mode 0600). */
 export async function writeProjectCredentials(projectRoot, credentials) {
     await ensureProjectDir(projectRoot);
-    await writePrivate(credentialsPath(projectRoot), {
+    await writeCredentialsFile(credentialsPath(projectRoot), credentials);
+}
+/** A credentials file (format 1), written atomically with mode 0600. */
+export async function writeCredentialsFile(path, credentials) {
+    await writePrivate(path, {
         format: 1,
         applicationKey: credentials.applicationKey,
         principalId: credentials.principalId,

package/dist/stack/commands.d.ts

@@ -4,6 +4,7 @@ import type { HarnessMode, SandboxStackEnv } from "./env-file.js";
 import { type StackPaths } from "./paths.js";
 import type { PortProbe } from "./ports.js";
 import { type FetchLike } from "./studio-login.js";
+import { type AdminEndpoint } from "./operator-keys.js";
 export declare const STACK_SERVICES: readonly ["postgres", "restate", "s2-lite", "rustfs", "gateway", "runtime", "harness", "studio"];
 export declare const stackUsage: string;
 export interface StackDeps {
@@ -128,14 +129,31 @@ export interface StackEndpoints {
     /** This call started the Runtime (it was not running before). */
     started: boolean;
 }
-/** The running Tenant's API, reached as the Project's derived principal (`nylorun sandbox`). */
+/** The running Tenant's API, reached with an operator key (`nylorun sandbox`). */
 export interface TenantApi {
     /** The Tenant's name. */
     name: string;
     runtimeUrl: string;
-    /** The `project` derived principal's key, derived from the admin key; never stored. */
+    /**
+     * The linked project's key (`.nylorun/credentials.json`) when it reaches the Tenant, else
+     * the operator key `cli` the Host root keeps (`cli-credentials.json`).
+     */
     applicationKey: string;
 }
+/** The selected Tenant's Admin API while it runs: `nylorun key` and `runningTenantApi`. */
+export interface RunningAdmin extends AdminEndpoint {
+    /** The Tenant's name. */
+    name: string;
+    runtimeUrl: string;
+    paths: StackPaths;
+}
+/**
+ * The selected Tenant's Admin API while it runs; exit 3 when it is not running, 7 when it is
+ * not open.
+ */
+export declare function runningAdmin(deps: StackDeps, options?: {
+    name?: string;
+}): Promise<RunningAdmin>;
 /**
  * The selected Tenant's API while it runs: commands that read or change the Tenant's data never
  * start it. Exit 3 when it is not running, 7 when it is not open.

package/dist/stack/commands.js

@@ -3,8 +3,7 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import { compareVersions, PROTOCOL_HEADER, PROTOCOL_VERSION, } from "@nylorun/core/compatibility";
 import { CliError } from "../errors.js";
-import { deriveTenantKey, PROJECT_PRINCIPAL_ID } from "../project/derived-key.js";
-import { readProjectCredentials, readProjectLink, writeProjectCredentials, writeProjectLink, } from "../project/link.js";
+import { credentialsPath, readCredentialsFile, readProjectCredentials, readProjectLink, writeProjectCredentials, writeProjectLink, } from "../project/link.js";
 import { findProjectRoot } from "../project/root.js";
 import { seedTenant } from "../project/seed.js";
 import { readTelemetry, STUDIO_ANALYTICS_ID, TELEMETRY_NOTICE, telemetryDecision, writeTelemetry, } from "../telemetry.js";
@@ -15,6 +14,7 @@ import { stackPaths } from "./paths.js";
 import { prepareStack, readStackEnv } from "./prepare.js";
 import { assertTenantName, chooseTenantName, DEFAULT_TENANT, defaultNylorunRoot, listTenants, moveStackRoots, readTenantRecord, removeOldProxy, sanitizeTenantName, tenantRoot, tenantsDir, writeTenantRecord, } from "./stacks.js";
 import { mintStudioLogin, studioOrigin } from "./studio-login.js";
+import { CLI_KEY_ID, hostKey, keyAuthenticates, PROJECT_KEY_ID, } from "./operator-keys.js";
 export const STACK_SERVICES = [
     "postgres",
     "restate",
@@ -392,9 +392,6 @@ async function bringUp(ctx, options) {
         runtimeVersion: overridden ? undefined : deps.runtimeVersion,
         ports: deps.ports,
         reserved: await reservedPorts(ctx),
-        ...(deps.env.NYLORUN_DERIVED_PRINCIPALS?.trim()
-            ? { derivedPrincipals: deps.env.NYLORUN_DERIVED_PRINCIPALS }
-            : {}),
         ...(options.studioEmbedOrigins ? { studioEmbedOrigins: options.studioEmbedOrigins } : {}),
         ...(analytics ? { studioAnalyticsId: STUDIO_ANALYTICS_ID } : {}),
         ...(options.sandboxes !== undefined ? { sandboxes: options.sandboxes } : {}),
@@ -487,13 +484,17 @@ async function openLogin(ctx, login) {
 }
 /**
  * Link the project to the Tenant: `.nylorun/link.json` (format 3) and
- * `.nylorun/credentials.json` with the key of the derived principal `project`. The link is
- * rewritten only when it is older, or the Tenant's name, URL, Host or id changed; a new link
- * seeds the Tenant from the project's `.env`.
+ * `.nylorun/credentials.json`. The link is rewritten only when it is older, or the Tenant's
+ * name, URL, Host or id changed; a new link seeds the Tenant from the project's `.env`.
+ *
+ * The credentials file is kept while its key still reaches the Tenant (one authenticated
+ * read). Otherwise it gets the operator key `project` (F9 I1): the one the Host root keeps for
+ * the projects linked to this Tenant (`project-credentials.json`), or a new one put through
+ * the Admin API. Every checkout linked to the Tenant shares it, so linking one never rotates
+ * another's key.
  */
 async function linkProject(ctx, started, tenantId) {
     const { deps, projectDir, link } = ctx;
-    const applicationKey = deriveTenantKey(started.adminKey, tenantId, PROJECT_PRINCIPAL_ID);
     const fresh = link?.format !== 3 ||
         link.tenant !== ctx.name ||
         link.hostUrl !== started.runtimeUrl ||
@@ -506,14 +507,37 @@ async function linkProject(ctx, started, tenantId) {
             hostId: started.hostId,
             tenantId,
         });
-    const credentials = await readProjectCredentials(projectDir);
-    if (fresh ||
-        credentials?.applicationKey !== applicationKey ||
-        credentials.principalId !== PROJECT_PRINCIPAL_ID)
+    const existing = await readProjectCredentials(projectDir);
+    const admin = {
+        fetch: deps.fetch,
+        adminUrl: started.adminUrl,
+        adminKey: started.adminKey,
+    };
+    const keyOptions = {
+        admin,
+        runtimeUrl: started.runtimeUrl,
+        id: PROJECT_KEY_ID,
+        file: ctx.paths.projectCredentials,
+        lock: ctx.paths.keysLock,
+    };
+    let applicationKey;
+    if (existing && (await keyAuthenticates(deps.fetch, started.runtimeUrl, existing.applicationKey))) {
+        applicationKey = existing.applicationKey;
+        // A project key from before operator keys becomes the one the Host root keeps.
+        if (existing.principalId === PROJECT_KEY_ID &&
+            (await readCredentialsFile(ctx.paths.projectCredentials))?.applicationKey !== applicationKey)
+            await hostKey({ ...keyOptions, adopt: existing });
+    }
+    else {
+        const key = await hostKey(keyOptions);
+        applicationKey = key.applicationKey;
         await writeProjectCredentials(projectDir, {
-            applicationKey,
-            principalId: PROJECT_PRINCIPAL_ID,
+            applicationKey: key.applicationKey,
+            principalId: key.principalId,
         });
+        if (existing && !fresh)
+            deps.err(`Replaced the project's key, which no longer reaches Tenant ${ctx.name} (.nylorun/credentials.json).`);
+    }
     if (!fresh)
         return;
     deps.err(`Linked ${projectDir} to Tenant ${ctx.name} (.nylorun/link.json, .nylorun/credentials.json).`);
@@ -971,11 +995,7 @@ async function ensureSelected(ctx, options) {
         started: !runtimeWasUp,
     };
 }
-/**
- * The selected Tenant's API while it runs: commands that read or change the Tenant's data never
- * start it. Exit 3 when it is not running, 7 when it is not open.
- */
-export async function runningTenantApi(deps, options = {}) {
+async function runningSelected(deps, options) {
     const ctx = await selectStack(deps, options);
     requireStackFiles(ctx);
     await dockerPreflight(deps.docker);
@@ -986,11 +1006,44 @@ export async function runningTenantApi(deps, options = {}) {
     if (!tenant?.id || tenant.state !== "open")
         throw new CliError(`Tenant ${ctx.name} is not open. See "nylorun status".`, 7);
     return {
-        name: ctx.name,
-        runtimeUrl: running.runtimeUrl,
-        applicationKey: deriveTenantKey(running.adminKey, tenant.id, PROJECT_PRINCIPAL_ID),
+        ctx,
+        admin: {
+            name: ctx.name,
+            runtimeUrl: running.runtimeUrl,
+            paths: ctx.paths,
+            fetch: deps.fetch,
+            adminUrl: running.adminUrl,
+            adminKey: running.adminKey,
+        },
     };
 }
+/**
+ * The selected Tenant's Admin API while it runs; exit 3 when it is not running, 7 when it is
+ * not open.
+ */
+export async function runningAdmin(deps, options = {}) {
+    return (await runningSelected(deps, options)).admin;
+}
+/**
+ * The selected Tenant's API while it runs: commands that read or change the Tenant's data never
+ * start it. Exit 3 when it is not running, 7 when it is not open.
+ */
+export async function runningTenantApi(deps, options = {}) {
+    const { ctx, admin } = await runningSelected(deps, options);
+    if (ctx.projectDir && ctx.link?.format === 3 && ctx.link.tenant === ctx.name) {
+        const project = await readCredentialsFile(credentialsPath(ctx.projectDir));
+        if (project && (await keyAuthenticates(deps.fetch, admin.runtimeUrl, project.applicationKey)))
+            return { name: ctx.name, runtimeUrl: admin.runtimeUrl, applicationKey: project.applicationKey };
+    }
+    const key = await hostKey({
+        admin,
+        runtimeUrl: admin.runtimeUrl,
+        id: CLI_KEY_ID,
+        file: ctx.paths.cliCredentials,
+        lock: ctx.paths.keysLock,
+    });
+    return { name: ctx.name, runtimeUrl: admin.runtimeUrl, applicationKey: key.applicationKey };
+}
 /**
  * Start the selected Tenant unless it is already running (`nylorun studio`): the
  * `start` code path without its output, its Tenant wait or the Project link. Compose

package/dist/stack/compose-file.d.ts

@@ -13,8 +13,7 @@
  * database with C collation (`--locale=C`) and runs with `wal_level=logical`: the stream
  * relay feeds s2-lite from the record over logical replication (Durable Streams), and
  * `max_slot_wal_keep_size` caps the WAL a stuck relay can hold. The Runtime creates the
- * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`) and the derived
- * principals of `NYLORUN_DERIVED_PRINCIPALS` (`project` for the Project link).
+ * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`).
  *
  * Restate signs requests to the Worker endpoint with the private key in
  * `docker/restate-identity.pem`, mounted read-only; the Runtime gets the public
@@ -68,9 +67,13 @@
  * `default` carries egress and the published ports (runtime, gateway, Studio, sandboxes).
  * Restate's admin port (its UI, unauthenticated) is published, and Restate joins `default`,
  * only with `restateUi` (`nylorun start --restate-ui`).
+ *
+ * With `identity` (when `<Host root>/identity.yaml` exists) the runtime reads its trusted issuers
+ * from it, through the Host root mount (NYLORUN_IDENTITY_FILE=/nylorun/identity.yaml).
  */
 export declare function renderComposeFile(project: string, name: string, options?: {
     sandboxes?: true;
     harness?: "remote" | "in-process";
     restateUi?: true;
+    identity?: true;
 }): string;

package/dist/stack/compose-file.js

@@ -14,8 +14,7 @@ import { PINNED_IMAGES } from "./images.js";
  * database with C collation (`--locale=C`) and runs with `wal_level=logical`: the stream
  * relay feeds s2-lite from the record over logical replication (Durable Streams), and
  * `max_slot_wal_keep_size` caps the WAL a stuck relay can hold. The Runtime creates the
- * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`) and the derived
- * principals of `NYLORUN_DERIVED_PRINCIPALS` (`project` for the Project link).
+ * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`).
  *
  * Restate signs requests to the Worker endpoint with the private key in
  * `docker/restate-identity.pem`, mounted read-only; the Runtime gets the public
@@ -69,9 +68,13 @@ import { PINNED_IMAGES } from "./images.js";
  * `default` carries egress and the published ports (runtime, gateway, Studio, sandboxes).
  * Restate's admin port (its UI, unauthenticated) is published, and Restate joins `default`,
  * only with `restateUi` (`nylorun start --restate-ui`).
+ *
+ * With `identity` (when `<Host root>/identity.yaml` exists) the runtime reads its trusted issuers
+ * from it, through the Host root mount (NYLORUN_IDENTITY_FILE=/nylorun/identity.yaml).
  */
 export function renderComposeFile(project, name, options = {}) {
     const sandboxes = options.sandboxes === true;
+    const identity = options.identity === true;
     const remote = (options.harness ?? "remote") === "remote";
     const restateUi = options.restateUi === true;
     return `# Written by \`nylorun start\`; rewritten on every start. Settings live in .env.
@@ -174,7 +177,11 @@ ${restateUi ? RESTATE_UI : RESTATE_CLOSED}    healthcheck:
       NYLORUN_OBJECT_STORE_ACCESS_KEY: nylorun
       NYLORUN_OBJECT_STORE_SECRET_KEY: \${NYLORUN_OBJECT_STORE_SECRET_KEY:?run nylorun start}
       # Action endpoints on this machine: \`localhost\` in a registered URL means the Docker host.
-      NYLORUN_ENDPOINT_LOOPBACK: docker-host${sandboxes ? SANDBOXES_GATEWAY_ENV : ""}
+      NYLORUN_ENDPOINT_LOOPBACK: docker-host
+      # Your credential resolver, for people's own MCP credentials (DEPLOYMENT.md, Credentials);
+      # unset by default. Set both in the shell that runs \`nylorun start\`.
+      NYLORUN_RESOLVER_URL: \${NYLORUN_RESOLVER_URL:-}
+      NYLORUN_RESOLVER_TOKEN: \${NYLORUN_RESOLVER_TOKEN:-}${sandboxes ? SANDBOXES_GATEWAY_ENV : ""}
     extra_hosts:
       host.docker.internal: host-gateway # model servers, MCP servers and Action endpoints on this machine
     volumes:
@@ -206,7 +213,6 @@ ${sandboxes ? SANDBOXES_GATES_PORT : ""}    # Egress and the stores; the harness
       NYLORUN_PACKING: combined
       # The Tenant the Runtime creates on its first start (later starts open it).
       NYLORUN_TENANT_NAME: \${NYLORUN_TENANT_NAME:?run nylorun start}
-      NYLORUN_DERIVED_PRINCIPALS: \${NYLORUN_DERIVED_PRINCIPALS:-project}
       # Model calls, remote MCP calls and deliveries go through the gateway, and vault writes
       # and token signing through its keys service: this container never reads a credential
       # or the vault key.
@@ -242,7 +248,7 @@ ${sandboxes ? SANDBOXES_GATES_PORT : ""}    # Egress and the stores; the harness
       NYLORUN_HARNESS: \${NYLORUN_HARNESS:-remote}
       NYLORUN_HARNESS_LISTEN_PORT: "4200"
       NYLORUN_HARNESS_ALLOWED_HOSTS: runtime:4200${sandboxes ? SANDBOXES_HARNESS_HOST : ""}
-      NYLORUN_HARNESS_TOKEN: \${NYLORUN_HARNESS_TOKEN:?run nylorun start}${sandboxes ? SANDBOXES_RUNTIME_ENV : ""}
+      NYLORUN_HARNESS_TOKEN: \${NYLORUN_HARNESS_TOKEN:?run nylorun start}${sandboxes ? SANDBOXES_RUNTIME_ENV : ""}${identity ? IDENTITY_RUNTIME_ENV : ""}
     extra_hosts:
       host.docker.internal: host-gateway # the Docker host, also on Linux Docker Engine
     volumes:
@@ -287,10 +293,13 @@ ${sandboxes ? SANDBOXES_GATES_PORT : ""}    # Egress and the stores; the harness
       # Browsers share cookies across ports of one host: a cookie per Tenant keeps the
       # sessions of two Studios on localhost apart.
       NYLORUN_STUDIO_SESSION_COOKIE: nylorun_studio_${name}
-      # Exact origins that may frame Studio (Babai Desktop); kept in .env.
+      # Exact origins that may frame Studio (none by default: embedding is opt-in); kept in .env.
       NYLORUN_STUDIO_FRAME_ANCESTORS: \${NYLORUN_STUDIO_FRAME_ANCESTORS:-}
       # Studio's anonymous usage analytics; empty when telemetry is off.
       NYLORUN_STUDIO_ANALYTICS_ID: \${NYLORUN_STUDIO_ANALYTICS_ID:-}
+      # Extra Host values Studio serves behind a sign-in proxy (studio.acme.dev),
+      # comma-separated; from the environment of nylorun start.
+      NYLORUN_STUDIO_ALLOWED_HOSTS: \${NYLORUN_STUDIO_ALLOWED_HOSTS:-}
     volumes:
       - \${NYLORUN_HOST_ROOT}/host-credentials.json:/run/nylorun/host-credentials.json:ro
     networks: [default]
@@ -373,6 +382,10 @@ function harnessService(project) {
  * The runtime reaches the sandboxes service on the Compose network with its token, and serves
  * the Harness API to sandbox pods (F7.2) on the Docker host's address.
  */
+/** The identity file (`<Host root>/identity.yaml`): the trusted issuers, read at boot. */
+const IDENTITY_RUNTIME_ENV = `
+      # Trusted issuers (<Host root>/identity.yaml): JWTs from the operator's identity provider.
+      NYLORUN_IDENTITY_FILE: /nylorun/identity.yaml`;
 const SANDBOXES_RUNTIME_ENV = `
       # The sandboxes service (nylorun sandbox enable): pods on the Tenant's cluster.
       NYLORUN_SANDBOXES_URL: http://sandboxes:4300

package/dist/stack/env-file.d.ts

@@ -1,8 +1,8 @@
 /**
- * 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 declare const DEFAULT_STUDIO_FRAME_ANCESTORS: readonly ["nylorun://localhost", "http://nylorun.localhost"];
+export declare const DEFAULT_STUDIO_FRAME_ANCESTORS: readonly string[];
 /**
  * Settings in `docker/.env` (mode 0600). Ports, the password and the gates token
  * persist; the Restate identity public key is derived from `restate-identity.pem`.
@@ -57,11 +57,6 @@ export interface StackEnv {
     studioAnalyticsId: string;
     /** The Tenant's name, which the Runtime gives the Tenant it creates. */
     tenantName: string;
-    /**
-     * Derived principals the Runtime registers on its Tenant, comma-separated (persists);
-     * always includes `project`, the Project link's principal.
-     */
-    derivedPrincipals: string;
     /** Present once `nylorun sandbox enable` ran for the Tenant (F7.2). */
     sandboxes?: SandboxStackEnv;
 }
@@ -84,11 +79,6 @@ export interface SandboxStackEnv {
 }
 export type HarnessMode = "remote" | "in-process";
 export declare function renderEnvFile(env: StackEnv): string;
-/**
- * `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 declare function parseDerivedPrincipals(raw: string, source: string): string[];
 /** Parse KEY=value lines; comments and blank lines are skipped. */
 export declare function parseEnvLines(text: string): Map<string, string>;
 /** The settings that persist across starts, from an existing .env. */
@@ -106,7 +96,6 @@ export interface PersistedStackEnv {
     objectStoreSecretKey?: string;
     /** Validated origins; absent when the line is missing (an older .env). */
     studioFrameAncestors?: string[];
-    derivedPrincipals?: string[];
     sandboxes?: SandboxStackEnv;
 }
 export declare function parsePersisted(text: string): PersistedStackEnv;