@nylorun/admin 0.6.0-beta → 0.8.0-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,58 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.8.0-beta
4
+
5
+ ### Minor Changes
6
+
7
+ - 4b9906f: **Breaking: "Tenant" replaces "stack", and `nylorun start` works anywhere.** Each local installation holds one Tenant, and its name is the Tenant's name, so help, output, errors and docs say Tenant. See MIGRATION.md.
8
+
9
+ - **Breaking (`nylorun`): selection.** Every command acts on the Tenant `--tenant <name>` names (replaces `--name`, which is removed), else `NYLORUN_TENANT` (replaces `NYLORUN_STACK`), else the Project link's `tenant`; `start` in a project names a new one after the project directory. Outside a project, or with `start --no-link`, commands act on the Tenant `default`. In a project without a link, commands other than `start` exit 2 and list the machine's Tenants. A name starting with `tn_` (a Tenant id) is refused.
10
+ - **Breaking (`nylorun`): files.** Host roots are under `~/.nylorun/tenants/<name>/` (was `~/.nylorun/stacks/<name>/`) with `tenant.json` (was `stack.json`); the `.env` key is `NYLORUN_TENANT_NAME` (was `NYLORUN_STACK_NAME`); `NYLORUN_COMPOSE_PROJECT` replaces `NYLORUN_STACK_PROJECT`. Compose projects stay `nylorun-<name>`. Every command first moves 0.4 Host roots from `~/.nylorun/stacks/` to `~/.nylorun/tenants/` (renaming `stack.json` and the `.env` key), so they keep their volumes and keys. `nylorun ls` lists only directories with `tenant.json`.
11
+ - **Breaking (`nylorun`): removed.** `nylorun legacy` and all handling of the single stack of releases before 0.4; the hidden `nylorun stack <cmd>` alias; `nylorun doctor stack|runtime`. Output says Tenant: `ls` prints `TENANT` and JSON `{ "tenants": [...] }`, `status` prints the Tenant id on its own line, and `doctor`'s row is `tenant`.
12
+ - **Breaking: Project link format 3.** `.nylorun/link.json` is `{ "format": 3, "tenant", "tenantId", "hostUrl", "hostId" }`; `tenant` replaces `stack`. `@nylorun/agents`, `@nylorun/cli` and `@nylorun/admin` refuse an older link and name `npx nylorun start`, which rewrites it. `@nylorun/core`'s `ProjectLinkFileSchema` parses formats 0–3 with `tenant`.
13
+ - **Breaking (`@nylorun/admin`):** `createAdmin({ tenant })` replaces `{ stack }`, `tenantHostRoot(name)` replaces `stackHostRoot(name)`, and local resolution reads `NYLORUN_TENANT` and the link's `tenant`.
14
+ - `@nylorun/cli`: `status` and `endpoints` drop the `stack` line and JSON key; messages say Tenant. `@nylorun/agents`: a Runtime too old for the client says "update the Runtime (npx nylorun@latest start)". `@nylorun/studio`: setup hints say Tenant. `@nylorun/create-agent`: the next steps describe `npx nylorun@beta start` as this project's Tenant and its link.
15
+
16
+ ### Patch Changes
17
+
18
+ - Pin core to the tested release.
19
+ - Updated dependencies [4b9906f]
20
+ - @nylorun/core@0.11.0-beta
21
+
22
+ ## 0.7.0-beta
23
+
24
+ ### Major Changes
25
+
26
+ - 5ca1923: **Clients for one Tenant per installation: a stack per project, nothing selects a Tenant.** Upgrade these with the Runtime; they speak protocol 5. Existing stacks are left as they are: see MIGRATION.md.
27
+
28
+ - **Breaking (`nylorun`): one stack per project.** `nylorun start` in a project creates the project's stack (named after the project directory, or `--name`; Host root `~/.nylorun/stacks/<name>/`, Compose project `nylorun-<name>`, its own free ports and volumes), waits for its Runtime to create the stack's Tenant, writes the Project link (`.nylorun/link.json` format 2: `stack`, `hostUrl`, `hostId`, `tenantId`) and `.nylorun/credentials.json` (the key of the derived principal `project`, derived from the stack's admin key), and seeds the model provider from the project's `.env`. `nylorun ls` lists the machine's stacks and `nylorun delete <name>` removes one with its volumes and Host root. `nylorun status` shows the stack's Tenant; `nylorun studio` opens it. The old single stack under `~/.nylorun` is never touched: `start` notes it, and `nylorun legacy stop|delete` handles it. Every stack command takes `--name <stack>` (or `NYLORUN_STACK`, or the Project link's stack); `start --no-link` starts a stack without linking the directory; `nylorun reset` resets the selected stack only. The runtime container's healthcheck is now `/health`, so a Tenant that cannot open is reported by `start` from the Admin status at once instead of after a 300 s wait. `NYLORUN_HOME` still overrides the Host root. Stacks start and stop only when you say so.
29
+ - **Breaking (`@nylorun/cli`): no Tenant commands.** `nylo tenant create|use|list|current|delete` are removed; `nylo status`, `nylo reset` and `nylo endpoints` replace `nylo tenant status|reset|endpoints` on the linked installation. `nylo env` prints `NYLORUN_RUNTIME_URL` and `NYLORUN_SERVER_KEY` only. `nylo` no longer writes Project links.
30
+ - **Breaking (`@nylorun/agents`): no Tenant to name.** The `tenant` option (`createClient`, `Transport`, `resolveConnection`, `createActionHandler({ runtime })`, `JwksCache`) and `NYLORUN_TENANT` are gone, and no request sends `Nylorun-Tenant`; a connection is a URL and a key. A Project link of format 0 or 1 is refused with `connection_missing`, naming `npx nylorun start`. `verifyDeliveryToken`'s `tenantId` is optional: without it any Tenant issuer is accepted, since the installation's keys bind it. `TENANT_HEADER` is no longer re-exported.
31
+ - **Breaking (`@nylorun/admin`): status only.** `createTenant`, `listTenants`, `getTenant` and `deleteTenant` are removed; `status().tenant` names the Host's Tenant, and `deriveTenantKey` / `deriveStudioToken` derive its keys. Local Host resolution reads the stack's Host root (`stack` option, `NYLORUN_STACK`, or the Project link's `stack`); `NYLORUN_HOME` and `home` still override it. `stackHostRoot(name)` is exported.
32
+ - **Breaking (`@nylorun/studio`): Studio serves its installation's Tenant.** The Tenant picker, list and create are gone, with `/_studio/tenants`; `/` opens `/tenants/<id>`. The `/tenants/:tenant` routes and the login token's `tenant` claim stay for embedders and must name that Tenant. The proxy sends no `Nylorun-Tenant`.
33
+ - **`@nylorun/create-agent`:** the next steps are `npx nylorun start`, then `npm run dev`.
34
+ - `@nylorun/core`: `ProjectLinkFileSchema` accepts format 2 with `stack`, and `tenantId` is optional; `ERROR_CODES` loses `tenant_conflict` and `active_work`.
35
+
36
+ - 5ca1923: **One Tenant per installation: a database per Tenant, protocol 5.** A Runtime serves exactly one Tenant, the one its Postgres database holds. Two Tenants are two installations.
37
+
38
+ - **Breaking: fresh start.** The Tenant's state is in the fixed schema `nylorun` of its own database and its record in `nylorun_streams`, keyed by session (no `tenant_id`). A database written by an earlier Runtime (`tenant_<id>` schemas, or a record keyed by Tenant) is refused: the Host stays up but not ready, and `/v1/admin/status` names the cause `database-layout-old`. Point the Runtime at a new database (with the local stack, a new stack); the old one is never changed.
39
+ - **The Host creates its Tenant** on first start, in the migration transaction: `NYLORUN_TENANT_ID` (default a new id), `NYLORUN_TENANT_NAME` (default `default`), the Studio principal and the derived principals of `NYLORUN_DERIVED_PRINCIPALS` (comma-separated, default `project`), whose keys the admin key derives (`deriveTenantKey`). Later starts open the same Tenant and add derived principals configured since.
40
+ - **Breaking: no Tenant catalog.** `/v1/admin/tenants` and `/v1/admin/tenants/{tenantId}` are gone (404). `AdminStatus.tenants[]` is replaced by `AdminStatus.tenant` (`id`, `name`, `state: open | unavailable`, `envelope`, and `cause` when it could not be opened). `CreateTenantRequestSchema`, `AdminTenantSchema`, `AdminTenantStatusSchema`, `AdminTenantListSchema` and `QuarantineSchema` leave `@nylorun/core`; `HostTenantSchema` and `TenantCauseSchema` replace them. `@nylorun/admin`'s `listTenants`, `getTenant`, `deleteTenant` and `createTenant` are removed (see below).
41
+ - **Readiness instead of quarantine.** A Tenant that cannot be opened (`schema-too-new`, `kek-missing`, `migration-failed`, `envelope-invalid`, `database-layout-old`, …) fails `/ready` (check `tenant`, which replaces `discovery`) and is reported with its repair in `/v1/admin/status` and the log; every Tenant request gets the opaque 404. A failure outside it (Postgres unreachable) is retried.
42
+ - **Protocol 5.** `PROTOCOL_VERSION = 5`; the Host serves protocols 4 and 5 for one release. Clients no longer require `runtime-tenants`; the Host still advertises it. No request needs `Nylorun-Tenant`: a request without it reaches the Host's Tenant, and one naming another Tenant (or a malformed one), or a publishable key of another Tenant, gets the opaque 404. The OpenAPI documents drop the header parameter and the Admin Tenant routes.
43
+ - **Paths.** The Tenant directory is `<Host root>/tenant/` (was `tenants/<id>/`); `trash/` and the SQLite move to it are gone. The gates service serves its database's Tenant, and its `Nylorun-Tenant` header is optional (when sent, it must name that Tenant).
44
+ - **Breaking: `startEphemeralRuntime` needs a database; the in-memory Session Store is removed.** `StartEphemeralRuntimeOptions.database` is required: a Postgres URL, for which the Runtime opens a pool and ends it on `close()`, or a pool the caller ends. It creates its Tenant in that database through the same bootstrap as a Host, or serves the Tenant the database already holds; the data stays after `close()`, so give each test Tenant a database of its own. Durable Streams and scheduling stay in process. See `MIGRATION.md`.
45
+
46
+ ### Patch Changes
47
+
48
+ - Pin core to the tested release.
49
+ - Updated dependencies [fed780d]
50
+ - Updated dependencies [fed780d]
51
+ - Updated dependencies [7f4c3f1]
52
+ - Updated dependencies [5ca1923]
53
+ - Updated dependencies [5ca1923]
54
+ - @nylorun/core@0.10.0-beta
55
+
3
56
  ## 0.6.0-beta
4
57
 
5
58
  ### Minor Changes
package/README.md CHANGED
@@ -1,61 +1,59 @@
1
1
  # @nylorun/admin
2
2
 
3
- Admin API client for creating, listing, inspecting and deleting Tenants, and
4
- reading Host service status. Depends only on `@nylorun/core`. Requires Node
5
- 24+. Vocabulary: [runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
3
+ Admin API client for a Runtime installation: its status, with the one Tenant it
4
+ serves, and the keys the admin key derives. Depends only on `@nylorun/core`.
5
+ Requires Node 24+. Vocabulary: [runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
6
6
 
7
7
  ```ts
8
8
  import { createAdmin } from "@nylorun/admin";
9
9
 
10
10
  // Resolution: explicit options → NYLORUN_ADMIN_URL + NYLORUN_ADMIN_KEY → local Host
11
11
  const admin = createAdmin();
12
- // or: createAdmin({ url, key }) / createAdmin({ home: "/path/to/host-root" })
12
+ // or: createAdmin({ url, key }) / createAdmin({ tenant: "my-app" }) / createAdmin({ home })
13
13
 
14
- const status = await admin.status();
15
- const { tenant, applicationKey } = await admin.createTenant({ name: "my-app" });
16
- await admin.listTenants();
17
- await admin.getTenant(tenant.id);
18
- await admin.deleteTenant(tenant.id, { activeWork: "refuse" });
14
+ const { tenant } = await admin.status();
15
+ // tenant: { id, name, state: "open" | "unavailable", envelope, cause? }
19
16
  ```
20
17
 
21
- `createTenant` generates the Tenant id, principal, application key and
22
- idempotency key locally; only the key's hash is sent. On network error or
23
- `5xx` it retries up to three times with identical values. Persist the returned
24
- `applicationKey` — the Host never sees it in cleartext again.
18
+ An installation serves one Tenant, which its Host creates on first start. There
19
+ are no Tenant routes: `createTenant`, `listTenants`, `getTenant` and
20
+ `deleteTenant` are gone, and a Host answers `/v1/admin/tenants*` with `404`.
21
+ When the Tenant cannot be opened, `status.tenant.state` is `unavailable` and
22
+ `cause` names why (`schema-too-new`, `kek-missing`, `database-layout-old`, …).
25
23
 
26
- `createTenant` also registers the Tenant's Studio principal (`studio`) by
27
- sending the hash of `deriveStudioToken(adminKey, tenantId)`. Studio derives the
28
- same key from the admin key to call that Tenant's API, so whoever holds the
29
- admin key can reach every Tenant created this way.
30
-
31
- A client on the Host's machine or server that holds the admin key can avoid
32
- storing an application key too. Name it as a **derived principal** when the
33
- Tenant is created, then recompute its key whenever it needs one:
24
+ Whoever holds the admin key can derive the keys of the Tenant's derived
25
+ principals and of its Studio principal, so those clients store no key:
34
26
 
35
27
  ```ts
36
- const { tenant } = await admin.createTenant({
37
- name: "my-app",
38
- principals: ["babai"],
39
- });
40
- // Later, in any process that holds the admin key:
41
- const key = admin.deriveTenantKey(tenant.id, "babai");
28
+ const key = admin.deriveTenantKey(tenant.id!, "project");
29
+ // deriveTenantKey(adminKey, tenantId, principalId) and
30
+ // deriveStudioToken(adminKey, tenantId) are exported too.
42
31
  ```
43
32
 
44
- Ids match `^[a-z][a-z0-9-]{0,31}$`; `studio` is reserved. Only each key's hash
45
- is sent. The key is `deriveTenantKey(adminKey, tenantId, principalId)`, so
46
- rotating the admin key rotates every derived key. Principals are named when the
47
- Tenant is created; an older Tenant keeps its application key. This needs the
48
- optional Host feature `derived-principals`: `createTenant` checks `/health` and
49
- throws `incompatible_host` before sending anything to a Host without it.
50
-
51
- Local Host resolution reads `host.json` and `host-credentials.json` under
52
- `NYLORUN_HOME` / `~/.nylorun` (or `options.home`). On POSIX the credentials
53
- file must be owned by the user and not group- or world-readable. First use
54
- checks `/health` compatibility and throws `incompatible_host` on mismatch.
33
+ The Host registers the derived principals it is configured with
34
+ (`NYLORUN_DERIVED_PRINCIPALS`, default `project`; Babai uses `project,babai`)
35
+ when it creates its Tenant, and `studio` always. Ids match
36
+ `^[a-z][a-z0-9-]{0,31}$`; `studio` is reserved. Only each key's hash is stored,
37
+ so rotating the admin key rotates every derived key. `nylorun start` writes the
38
+ `project` key into a Project's `.nylorun/credentials.json`.
39
+
40
+ Local Host resolution reads `host.json` and `host-credentials.json` from the
41
+ Host root: `options.home`, else `NYLORUN_HOME`, else the Tenant's Host root
42
+ `~/.nylorun/tenants/<tenant>/` for the local Tenant named by `options.tenant`,
43
+ `NYLORUN_TENANT` or the Project link (`tenant` in `.nylorun/link.json`, format
44
+ 3, found from `options.cwd` upwards; a link from an older nylorun throws
45
+ `connection_missing`). On POSIX the credentials file must be owned by the
46
+ user and not group- or world-readable. First use checks `/health`
47
+ compatibility and throws `incompatible_host` on mismatch.
48
+
49
+ `mintStudioLoginToken({ studioUrl, adminKey })` mints a single-use Studio login
50
+ token for an app that embeds Studio; its optional `tenant` must name the Host's
51
+ Tenant.
55
52
 
56
53
  Errors are `AdminError` with a registry `code` from `@nylorun/core`
57
54
  (`ERROR_CODES`). Re-exports: `PROTOCOL_FEATURES`, `ERROR_CODES`,
58
- `compareVersions`, `deriveStudioToken`, `deriveTenantKey`.
55
+ `compareVersions`, `deriveStudioToken`, `deriveTenantKey`, `tenantHostRoot`,
56
+ `PROJECT_PRINCIPAL_ID`.
59
57
 
60
58
  Developer applications do **not** depend on this package — only managing
61
59
  clients (CLI, desktop Runtime panel, CI) do.
package/dist/client.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type AdminStatus, type AdminTenant, type AdminTenantStatus, type TenantEnvelope } from "@nylorun/core/contracts";
1
+ import { type AdminStatus } from "@nylorun/core/contracts";
2
2
  export type AdminSource = "options" | "environment" | "local-host";
3
3
  export interface ResolvedAdmin {
4
4
  /** The Host's Tenant API URL (what a Project link names). */
@@ -10,16 +10,25 @@ export interface ResolvedAdmin {
10
10
  adminUrl?: string;
11
11
  key: string;
12
12
  source: AdminSource;
13
- home: string;
13
+ /** The Host root read for local Host settings, when one was found. */
14
+ home?: string;
14
15
  }
15
- /**
16
- * Resolve Admin API connection once: options → environment → local Host.
17
- */
18
- export declare function resolveAdminConnection(options?: {
16
+ export interface AdminConnectionOptions {
19
17
  url?: string;
20
18
  key?: string;
19
+ /** The Host root itself (overrides `NYLORUN_HOME` and the Tenant). */
21
20
  home?: string;
22
- }): ResolvedAdmin;
21
+ /** The local Tenant whose Host root (`~/.nylorun/tenants/<tenant>/`) to read. */
22
+ tenant?: string;
23
+ /** Where to look for a Project link naming the Tenant; defaults to the working directory. */
24
+ cwd?: string;
25
+ }
26
+ /** A local Tenant's Host root: `~/.nylorun/tenants/<name>/`. */
27
+ export declare function tenantHostRoot(name: string): string;
28
+ /**
29
+ * Resolve Admin API connection once: options → environment → local Host.
30
+ */
31
+ export declare function resolveAdminConnection(options?: AdminConnectionOptions): ResolvedAdmin;
23
32
  export declare class AdminClient {
24
33
  /** The Host's Tenant API URL. */
25
34
  readonly url: string;
@@ -28,8 +37,6 @@ export declare class AdminClient {
28
37
  readonly source: AdminSource;
29
38
  private readonly key;
30
39
  private compatible;
31
- /** Features the Host advertised at the last compatibility check. */
32
- private features;
33
40
  constructor(resolved: ResolvedAdmin);
34
41
  private clearCompatibilityCache;
35
42
  private adminHeaders;
@@ -37,21 +44,10 @@ export declare class AdminClient {
37
44
  private request;
38
45
  private json;
39
46
  status(): Promise<AdminStatus>;
40
- listTenants(): Promise<AdminTenant[]>;
41
- getTenant(id: string): Promise<AdminTenantStatus>;
42
- deleteTenant(id: string, options?: {
43
- activeWork?: "refuse" | "drain" | "cancel";
44
- }): Promise<void>;
45
47
  /**
46
48
  * The key of derived principal `principalId` on `tenantId`, from this client's admin key.
47
- * Valid once the Tenant was created with that principal in `principals`.
49
+ * Valid when the Host registered that principal (`NYLORUN_DERIVED_PRINCIPALS`, default
50
+ * `project`) on its Tenant.
48
51
  */
49
52
  deriveTenantKey(tenantId: string, principalId: string): string;
50
- createTenant(options: {
51
- name: string;
52
- principals?: readonly string[];
53
- }): Promise<{
54
- tenant: TenantEnvelope;
55
- applicationKey: string;
56
- }>;
57
53
  }
package/dist/client.js CHANGED
@@ -1,29 +1,87 @@
1
- import { createHash, randomBytes, randomUUID } from "node:crypto";
2
- import { readFileSync, statSync } from "node:fs";
1
+ import { readFileSync, realpathSync, statSync } from "node:fs";
3
2
  import { homedir } from "node:os";
4
- import { join, resolve } from "node:path";
5
- import { AdminStatusSchema, AdminTenantSchema, AdminTenantStatusSchema, RejectedResponseSchema, TenantEnvelopeSchema, } from "@nylorun/core/contracts";
6
- import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, checkCompatibility, DERIVED_PRINCIPAL_ID_PATTERN, newPrincipalId, newTenantId, } from "@nylorun/core/compatibility";
7
- import { deriveStudioToken, deriveTenantKey } from "./derived-credentials.js";
3
+ import { dirname, join, parse, resolve } from "node:path";
4
+ import { AdminStatusSchema, ProjectLinkFileSchema, RejectedResponseSchema, } from "@nylorun/core/contracts";
5
+ import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, checkCompatibility, } from "@nylorun/core/compatibility";
6
+ import { deriveTenantKey } from "./derived-credentials.js";
8
7
  import { AdminError } from "./errors.js";
9
8
  function env(name) {
10
9
  const value = process.env[name];
11
10
  return value === undefined || value.trim() === "" ? undefined : value;
12
11
  }
13
- function resolveHome(home) {
14
- if (home !== undefined && home.trim() !== "")
15
- return resolve(home);
12
+ /** A local Tenant's Host root: `~/.nylorun/tenants/<name>/`. */
13
+ export function tenantHostRoot(name) {
14
+ return resolve(join(homedir(), ".nylorun", "tenants", name));
15
+ }
16
+ /**
17
+ * The Tenant a Project link names (`.nylorun/link.json`, format 3), from `cwd` upwards, or the
18
+ * path of a link from an older nylorun. The walk stops at the home directory, which holds the
19
+ * Tenants and is never a Project.
20
+ */
21
+ function linkedTenant(cwd) {
22
+ const real = (path) => {
23
+ try {
24
+ return realpathSync(path);
25
+ }
26
+ catch {
27
+ return path;
28
+ }
29
+ };
30
+ const stop = real(homedir());
31
+ let directory = real(resolve(cwd));
32
+ const root = parse(directory).root;
33
+ while (directory !== stop) {
34
+ const path = join(directory, ".nylorun", "link.json");
35
+ let raw;
36
+ try {
37
+ raw = readFileSync(path, "utf8");
38
+ }
39
+ catch {
40
+ /* no link here */
41
+ }
42
+ if (raw !== undefined) {
43
+ try {
44
+ const link = ProjectLinkFileSchema.parse(JSON.parse(raw));
45
+ return link.format < 3 ? { olderLink: path } : { tenant: link.tenant };
46
+ }
47
+ catch {
48
+ return {};
49
+ }
50
+ }
51
+ if (directory === root)
52
+ return {};
53
+ directory = dirname(directory);
54
+ }
55
+ return {};
56
+ }
57
+ /**
58
+ * The Host root of the local Host: `options.home`, `NYLORUN_HOME`, or the Host root of the
59
+ * Tenant named by `options.tenant`, `NYLORUN_TENANT` or the Project link. No `home` when none
60
+ * names one; `olderLink` when the Project link is from an older nylorun.
61
+ */
62
+ function resolveHome(options) {
63
+ if (options?.home !== undefined && options.home.trim() !== "")
64
+ return { home: resolve(options.home) };
16
65
  const fromEnv = env("NYLORUN_HOME");
17
66
  if (fromEnv)
18
- return resolve(fromEnv);
19
- return resolve(join(homedir(), ".nylorun"));
67
+ return { home: resolve(fromEnv) };
68
+ const named = options?.tenant?.trim() || env("NYLORUN_TENANT")?.trim();
69
+ if (named)
70
+ return { home: tenantHostRoot(named) };
71
+ const linked = linkedTenant(options?.cwd ?? process.cwd());
72
+ return linked.tenant
73
+ ? { home: tenantHostRoot(linked.tenant) }
74
+ : { olderLink: linked.olderLink };
20
75
  }
21
76
  function connectionMissing(message) {
22
77
  throw new AdminError("connection_missing", message);
23
78
  }
24
79
  function sourcesTriedMessage(home) {
25
80
  return (`Tried options (url + key), environment (NYLORUN_ADMIN_URL + NYLORUN_ADMIN_KEY), ` +
26
- `and local Host settings (host.json + host-credentials.json under ${home}).`);
81
+ (home
82
+ ? `and local Host settings (host.json + host-credentials.json under ${home}).`
83
+ : "and local Host settings (no Tenant named: pass `tenant`, set NYLORUN_TENANT or " +
84
+ "NYLORUN_HOME, or run in a Project that `npx nylorun start` linked)."));
27
85
  }
28
86
  function assertCredentialsSafe(path) {
29
87
  if (process.platform === "win32")
@@ -91,7 +149,7 @@ function readLocalHost(home) {
91
149
  * Resolve Admin API connection once: options → environment → local Host.
92
150
  */
93
151
  export function resolveAdminConnection(options) {
94
- const home = resolveHome(options?.home);
152
+ const { home, olderLink } = resolveHome(options);
95
153
  const optionUrl = options?.url?.trim() || undefined;
96
154
  const optionKey = options?.key?.trim() || undefined;
97
155
  if (optionUrl || optionKey) {
@@ -102,7 +160,7 @@ export function resolveAdminConnection(options) {
102
160
  url: optionUrl.replace(/\/$/, ""),
103
161
  key: optionKey,
104
162
  source: "options",
105
- home,
163
+ ...(home ? { home } : {}),
106
164
  };
107
165
  }
108
166
  const envUrl = env("NYLORUN_ADMIN_URL");
@@ -115,10 +173,13 @@ export function resolveAdminConnection(options) {
115
173
  url: envUrl.replace(/\/$/, ""),
116
174
  key: envKey,
117
175
  source: "environment",
118
- home,
176
+ ...(home ? { home } : {}),
119
177
  };
120
178
  }
121
- const local = readLocalHost(home);
179
+ if (olderLink) {
180
+ connectionMissing(`The Project link at ${olderLink} is from an older nylorun. Run "npx nylorun start" in this project to link it again.`);
181
+ }
182
+ const local = home === undefined ? undefined : readLocalHost(home);
122
183
  if (local) {
123
184
  return {
124
185
  url: local.url.replace(/\/$/, ""),
@@ -147,12 +208,6 @@ function parseProtocolRange(value) {
147
208
  features: record.features,
148
209
  };
149
210
  }
150
- function hashCredential(token) {
151
- return createHash("sha256").update(token, "utf8").digest("hex");
152
- }
153
- function mintApplicationKey() {
154
- return randomBytes(32).toString("hex");
155
- }
156
211
  function throwFromResponse(status, body) {
157
212
  const parsed = RejectedResponseSchema.safeParse(body);
158
213
  if (parsed.success) {
@@ -161,9 +216,6 @@ function throwFromResponse(status, body) {
161
216
  details: parsed.data.details,
162
217
  });
163
218
  }
164
- if (status === 409) {
165
- throw new AdminError("tenant_conflict", `Admin request conflict (${status})`, { status, details: body });
166
- }
167
219
  if (status === 404) {
168
220
  throw new AdminError("not_found", `Admin request not found (${status})`, {
169
221
  status,
@@ -194,8 +246,6 @@ export class AdminClient {
194
246
  source;
195
247
  key;
196
248
  compatible = false;
197
- /** Features the Host advertised at the last compatibility check. */
198
- features = [];
199
249
  constructor(resolved) {
200
250
  this.url = resolved.url;
201
251
  this.adminUrl = resolved.adminUrl ?? resolved.url;
@@ -239,7 +289,6 @@ export class AdminClient {
239
289
  : `Host is missing required features: ${result.missing.join(", ")}`;
240
290
  throw new AdminError("incompatible_host", `Incompatible Host: ${detail}`, { details: result });
241
291
  }
242
- this.features = [...protocol.features];
243
292
  this.compatible = true;
244
293
  }
245
294
  async request(path, init = {}, options = {}) {
@@ -286,104 +335,12 @@ export class AdminClient {
286
335
  const body = await this.json("/v1/admin/status");
287
336
  return AdminStatusSchema.parse(body);
288
337
  }
289
- async listTenants() {
290
- const body = await this.json("/v1/admin/tenants");
291
- if (!Array.isArray(body)) {
292
- throw new AdminError("not_found", "Admin list tenants response was not an array.", { details: body });
293
- }
294
- return body.map((item) => AdminTenantSchema.parse(item));
295
- }
296
- async getTenant(id) {
297
- const body = await this.json(`/v1/admin/tenants/${encodeURIComponent(id)}`);
298
- return AdminTenantStatusSchema.parse(body);
299
- }
300
- async deleteTenant(id, options) {
301
- const activeWork = options?.activeWork ?? "refuse";
302
- await this.json(`/v1/admin/tenants/${encodeURIComponent(id)}?activeWork=${activeWork}`, "DELETE");
303
- }
304
338
  /**
305
339
  * The key of derived principal `principalId` on `tenantId`, from this client's admin key.
306
- * Valid once the Tenant was created with that principal in `principals`.
340
+ * Valid when the Host registered that principal (`NYLORUN_DERIVED_PRINCIPALS`, default
341
+ * `project`) on its Tenant.
307
342
  */
308
343
  deriveTenantKey(tenantId, principalId) {
309
344
  return deriveTenantKey(this.key, tenantId, principalId);
310
345
  }
311
- async createTenant(options) {
312
- const principals = options.principals ?? [];
313
- for (const id of principals)
314
- if (!DERIVED_PRINCIPAL_ID_PATTERN.test(id) || id === "studio")
315
- throw new TypeError(`Principal id '${id}' must match ${DERIVED_PRINCIPAL_ID_PATTERN} and not be 'studio'.`);
316
- if (new Set(principals).size !== principals.length)
317
- throw new TypeError("Principal ids must be unique.");
318
- if (principals.length) {
319
- await this.ensureCompatible();
320
- if (!this.features.includes("derived-principals"))
321
- throw new AdminError("incompatible_host", "Host does not support derived principals (feature derived-principals); upgrade it with `nylorun up`.");
322
- }
323
- const applicationKey = mintApplicationKey();
324
- const tenantId = newTenantId();
325
- const body = {
326
- tenantId,
327
- name: options.name,
328
- principalId: newPrincipalId(),
329
- credentialHash: hashCredential(applicationKey),
330
- idempotencyKey: randomUUID(),
331
- studioCredentialHash: hashCredential(deriveStudioToken(this.key, tenantId)),
332
- ...(principals.length
333
- ? {
334
- derivedPrincipals: principals.map((id) => ({
335
- id,
336
- credentialHash: hashCredential(deriveTenantKey(this.key, tenantId, id)),
337
- })),
338
- }
339
- : {}),
340
- };
341
- let lastError;
342
- for (let attempt = 0; attempt < 3; attempt += 1) {
343
- let response;
344
- try {
345
- response = await this.request("/v1/admin/tenants", {
346
- method: "POST",
347
- body: JSON.stringify(body),
348
- signal: AbortSignal.timeout(15_000),
349
- });
350
- }
351
- catch (error) {
352
- if (error instanceof AdminError)
353
- throw error;
354
- lastError = error;
355
- if (attempt === 2) {
356
- throw new AdminError("not_found", `Could not create Tenant after network errors: ${error instanceof Error ? error.message : String(error)}`, { details: error });
357
- }
358
- continue;
359
- }
360
- if (response.status === 409) {
361
- const parsed = await readBody(response);
362
- throw new AdminError("tenant_conflict", "Tenant id conflict.", {
363
- status: 409,
364
- details: parsed,
365
- });
366
- }
367
- if (response.status >= 500) {
368
- lastError = await readBody(response);
369
- if (attempt === 2) {
370
- throwFromResponse(response.status, lastError);
371
- }
372
- continue;
373
- }
374
- const parsed = await readBody(response);
375
- if (response.status !== 201 && response.status !== 200) {
376
- throwFromResponse(response.status, parsed);
377
- }
378
- return {
379
- tenant: TenantEnvelopeSchema.parse(parsed),
380
- applicationKey,
381
- };
382
- }
383
- throw lastError instanceof AdminError
384
- ? lastError
385
- : new AdminError("not_found", "Could not create Tenant after retries.", {
386
- details: lastError,
387
- });
388
- }
389
346
  }
@@ -5,15 +5,16 @@
5
5
  */
6
6
  export declare function deriveStudioToken(adminKey: string, tenantId: string): string;
7
7
  /**
8
- * The derived principal that Projects on this machine use. A Tenant created
9
- * with it (Studio creates every Tenant this way) can be linked to a Project by
10
- * `nylo tenant use`, which derives the key from the local admin key.
8
+ * The derived principal that Projects use. The Host registers it on its Tenant by default
9
+ * (`NYLORUN_DERIVED_PRINCIPALS`), and `nylorun start` derives its key from the Tenant's admin
10
+ * key into the Project's `.nylorun/credentials.json`.
11
11
  */
12
12
  export declare const PROJECT_PRINCIPAL_ID = "project";
13
13
  /**
14
14
  * Deterministic key of a derived principal (`principalId`, e.g. `babai`) on one Tenant,
15
- * derived from the admin key. The Tenant stores only its hash, registered when the Tenant
16
- * is created with `principals` (feature `derived-principals`); the client recomputes the
17
- * key when it needs it and stores nothing. Rotating the admin key rotates every derived key.
15
+ * derived from the admin key. The Tenant stores only its hash, registered when the Host creates
16
+ * its Tenant with the principals it is configured with (`NYLORUN_DERIVED_PRINCIPALS`, feature
17
+ * `derived-principals`); the client recomputes the key when it needs it and stores nothing.
18
+ * Rotating the admin key rotates every derived key.
18
19
  */
19
20
  export declare function deriveTenantKey(adminKey: string, tenantId: string, principalId: string): string;
@@ -15,16 +15,17 @@ export function deriveStudioToken(adminKey, tenantId) {
15
15
  .digest("hex");
16
16
  }
17
17
  /**
18
- * The derived principal that Projects on this machine use. A Tenant created
19
- * with it (Studio creates every Tenant this way) can be linked to a Project by
20
- * `nylo tenant use`, which derives the key from the local admin key.
18
+ * The derived principal that Projects use. The Host registers it on its Tenant by default
19
+ * (`NYLORUN_DERIVED_PRINCIPALS`), and `nylorun start` derives its key from the Tenant's admin
20
+ * key into the Project's `.nylorun/credentials.json`.
21
21
  */
22
22
  export const PROJECT_PRINCIPAL_ID = "project";
23
23
  /**
24
24
  * Deterministic key of a derived principal (`principalId`, e.g. `babai`) on one Tenant,
25
- * derived from the admin key. The Tenant stores only its hash, registered when the Tenant
26
- * is created with `principals` (feature `derived-principals`); the client recomputes the
27
- * key when it needs it and stores nothing. Rotating the admin key rotates every derived key.
25
+ * derived from the admin key. The Tenant stores only its hash, registered when the Host creates
26
+ * its Tenant with the principals it is configured with (`NYLORUN_DERIVED_PRINCIPALS`, feature
27
+ * `derived-principals`); the client recomputes the key when it needs it and stores nothing.
28
+ * Rotating the admin key rotates every derived key.
28
29
  */
29
30
  export function deriveTenantKey(adminKey, tenantId, principalId) {
30
31
  const message = Buffer.concat([
package/dist/index.d.ts CHANGED
@@ -1,11 +1,12 @@
1
- import type { AdminStatus, AdminTenant, AdminTenantStatus, TenantEnvelope } from "@nylorun/core/contracts";
1
+ import type { AdminStatus, HostTenant, TenantEnvelope } from "@nylorun/core/contracts";
2
2
  import { ERROR_CODES, PROTOCOL_FEATURES, compareVersions, type ErrorCode } from "@nylorun/core/compatibility";
3
+ import { tenantHostRoot, type AdminConnectionOptions } from "./client.js";
3
4
  import { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey } from "./derived-credentials.js";
4
5
  import { AdminError } from "./errors.js";
5
6
  export { ERROR_CODES, PROTOCOL_FEATURES, compareVersions };
6
7
  export type { ErrorCode };
7
8
  export { AdminError };
8
- export { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey };
9
+ export { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey, tenantHostRoot };
9
10
  export { mintStudioLoginToken } from "./studio-login.js";
10
11
  export interface Admin {
11
12
  /** The Host's Tenant API URL. */
@@ -13,30 +14,19 @@ export interface Admin {
13
14
  /** Where Admin API requests go: the operator listener, or `url` on a single-port Host. */
14
15
  readonly adminUrl: string;
15
16
  readonly source: "options" | "environment" | "local-host";
17
+ /** The Host's status, with the one Tenant it serves (`status.tenant`). */
16
18
  status(): Promise<AdminStatus>;
17
- listTenants(): Promise<AdminTenant[]>;
18
- getTenant(id: string): Promise<AdminTenantStatus>;
19
- deleteTenant(id: string, options?: {
20
- activeWork?: "refuse" | "drain" | "cancel";
21
- }): Promise<void>;
22
19
  /**
23
- * Creates a Tenant. `principals` names derived principals (e.g. `["babai"]`): their keys
24
- * come from `deriveTenantKey`, so their clients store none. Needs Host feature
25
- * `derived-principals`.
20
+ * The key of a derived principal on the Host's Tenant, from this client's admin key. The
21
+ * Host registers the principals it is configured with (`NYLORUN_DERIVED_PRINCIPALS`, default
22
+ * `project`) when it creates its Tenant.
26
23
  */
27
- createTenant(options: {
28
- name: string;
29
- principals?: readonly string[];
30
- }): Promise<{
31
- tenant: TenantEnvelope;
32
- applicationKey: string;
33
- }>;
34
- /** The key of a derived principal on a Tenant, from this client's admin key. */
35
24
  deriveTenantKey(tenantId: string, principalId: string): string;
36
25
  }
37
- export declare function createAdmin(options?: {
38
- url?: string;
39
- key?: string;
40
- home?: string;
41
- }): Admin;
42
- export type { AdminStatus, AdminTenant, AdminTenantStatus, TenantEnvelope };
26
+ /**
27
+ * Resolution: explicit `url` + `key` → `NYLORUN_ADMIN_URL` + `NYLORUN_ADMIN_KEY` → the local
28
+ * Host's settings in its Host root (`home`, `NYLORUN_HOME`, or the Tenant named by `tenant`,
29
+ * `NYLORUN_TENANT` or the Project link under `cwd`: `~/.nylorun/tenants/<tenant>/`).
30
+ */
31
+ export declare function createAdmin(options?: AdminConnectionOptions): Admin;
32
+ export type { AdminConnectionOptions, AdminStatus, HostTenant, TenantEnvelope };
package/dist/index.js CHANGED
@@ -1,11 +1,16 @@
1
1
  import { ERROR_CODES, PROTOCOL_FEATURES, compareVersions, } from "@nylorun/core/compatibility";
2
- import { AdminClient, resolveAdminConnection } from "./client.js";
2
+ import { AdminClient, resolveAdminConnection, tenantHostRoot, } from "./client.js";
3
3
  import { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey, } from "./derived-credentials.js";
4
4
  import { AdminError } from "./errors.js";
5
5
  export { ERROR_CODES, PROTOCOL_FEATURES, compareVersions };
6
6
  export { AdminError };
7
- export { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey };
7
+ export { PROJECT_PRINCIPAL_ID, deriveStudioToken, deriveTenantKey, tenantHostRoot };
8
8
  export { mintStudioLoginToken } from "./studio-login.js";
9
+ /**
10
+ * Resolution: explicit `url` + `key` → `NYLORUN_ADMIN_URL` + `NYLORUN_ADMIN_KEY` → the local
11
+ * Host's settings in its Host root (`home`, `NYLORUN_HOME`, or the Tenant named by `tenant`,
12
+ * `NYLORUN_TENANT` or the Project link under `cwd`: `~/.nylorun/tenants/<tenant>/`).
13
+ */
9
14
  export function createAdmin(options) {
10
15
  return new AdminClient(resolveAdminConnection(options));
11
16
  }
@@ -5,8 +5,8 @@ import { type StudioLoginTokenResponse } from "@nylorun/core/contracts";
5
5
  * Babai, calls this from its backend and hands only the token to its page,
6
6
  * which passes it to the framed Studio in `init`.
7
7
  *
8
- * - `tenant` limits the session the token leads to to one Tenant; omit it for
9
- * a Host-wide token (what `nylorun studio` uses).
8
+ * - `tenant` names the Host's one Tenant, for embedders that pass it (the embed
9
+ * contract keeps it); Studio refuses any other. Omit it, as `nylorun studio` does.
10
10
  * - `subject` names the person, for Studio's logs.
11
11
  */
12
12
  export declare function mintStudioLoginToken(options: {
@@ -6,8 +6,8 @@ import { AdminError } from "./errors.js";
6
6
  * Babai, calls this from its backend and hands only the token to its page,
7
7
  * which passes it to the framed Studio in `init`.
8
8
  *
9
- * - `tenant` limits the session the token leads to to one Tenant; omit it for
10
- * a Host-wide token (what `nylorun studio` uses).
9
+ * - `tenant` names the Host's one Tenant, for embedders that pass it (the embed
10
+ * contract keeps it); Studio refuses any other. Omit it, as `nylorun studio` does.
11
11
  * - `subject` names the person, for Studio's logs.
12
12
  */
13
13
  export async function mintStudioLoginToken(options) {
@@ -51,6 +51,6 @@ export async function mintStudioLoginToken(options) {
51
51
  }
52
52
  const parsed = StudioLoginTokenResponseSchema.safeParse(JSON.parse(text));
53
53
  if (!parsed.success)
54
- throw new AdminError("incompatible_host", "This Studio does not support login tokens limited to a Tenant; update the stack.");
54
+ throw new AdminError("incompatible_host", "This Studio does not support login tokens limited to a Tenant; update Studio (npx nylorun@latest start).");
55
55
  return parsed.data;
56
56
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nylorun/admin",
3
- "version": "0.6.0-beta",
3
+ "version": "0.8.0-beta",
4
4
  "description": "Nylorun Admin API client for Tenants and Host status",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -24,7 +24,7 @@
24
24
  "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\""
25
25
  },
26
26
  "dependencies": {
27
- "@nylorun/core": "0.9.0-beta"
27
+ "@nylorun/core": "0.11.0-beta"
28
28
  },
29
29
  "peerDependencies": {
30
30
  "zod": "^4.6.5"