@nylorun/admin 0.6.0-beta → 0.7.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,39 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.0-beta
4
+
5
+ ### Major Changes
6
+
7
+ - 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.
8
+
9
+ - **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.
10
+ - **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.
11
+ - **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.
12
+ - **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.
13
+ - **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`.
14
+ - **`@nylorun/create-agent`:** the next steps are `npx nylorun start`, then `npm run dev`.
15
+ - `@nylorun/core`: `ProjectLinkFileSchema` accepts format 2 with `stack`, and `tenantId` is optional; `ERROR_CODES` loses `tenant_conflict` and `active_work`.
16
+
17
+ - 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.
18
+
19
+ - **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.
20
+ - **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.
21
+ - **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).
22
+ - **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.
23
+ - **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.
24
+ - **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).
25
+ - **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`.
26
+
27
+ ### Patch Changes
28
+
29
+ - Pin core to the tested release.
30
+ - Updated dependencies [fed780d]
31
+ - Updated dependencies [fed780d]
32
+ - Updated dependencies [7f4c3f1]
33
+ - Updated dependencies [5ca1923]
34
+ - Updated dependencies [5ca1923]
35
+ - @nylorun/core@0.10.0-beta
36
+
3
37
  ## 0.6.0-beta
4
38
 
5
39
  ### Minor Changes
package/README.md CHANGED
@@ -1,61 +1,58 @@
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({ stack: "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 stack's Host root
42
+ `~/.nylorun/stacks/<stack>/` for the stack named by `options.stack`,
43
+ `NYLORUN_STACK` or the Project link (`stack` in `.nylorun/link.json`, found
44
+ from `options.cwd` upwards). On POSIX the credentials file must be owned by the
45
+ user and not group- or world-readable. First use checks `/health`
46
+ compatibility and throws `incompatible_host` on mismatch.
47
+
48
+ `mintStudioLoginToken({ studioUrl, adminKey })` mints a single-use Studio login
49
+ token for an app that embeds Studio; its optional `tenant` must name the Host's
50
+ Tenant.
55
51
 
56
52
  Errors are `AdminError` with a registry `code` from `@nylorun/core`
57
53
  (`ERROR_CODES`). Re-exports: `PROTOCOL_FEATURES`, `ERROR_CODES`,
58
- `compareVersions`, `deriveStudioToken`, `deriveTenantKey`.
54
+ `compareVersions`, `deriveStudioToken`, `deriveTenantKey`, `stackHostRoot`,
55
+ `PROJECT_PRINCIPAL_ID`.
59
56
 
60
57
  Developer applications do **not** depend on this package — only managing
61
58
  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 stack). */
21
20
  home?: string;
22
- }): ResolvedAdmin;
21
+ /** The local stack whose Host root (`~/.nylorun/stacks/<stack>/`) to read. */
22
+ stack?: string;
23
+ /** Where to look for a Project link naming the stack; defaults to the working directory. */
24
+ cwd?: string;
25
+ }
26
+ /** A local stack's Host root: `~/.nylorun/stacks/<name>/`. */
27
+ export declare function stackHostRoot(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,80 @@
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 stack's Host root: `~/.nylorun/stacks/<name>/`. */
13
+ export function stackHostRoot(name) {
14
+ return resolve(join(homedir(), ".nylorun", "stacks", name));
15
+ }
16
+ /**
17
+ * The stack a Project link names (`.nylorun/link.json`, format 2), from `cwd` upwards. The walk
18
+ * stops at the home directory, which holds the stacks and is never a Project.
19
+ */
20
+ function linkedStack(cwd) {
21
+ const real = (path) => {
22
+ try {
23
+ return realpathSync(path);
24
+ }
25
+ catch {
26
+ return path;
27
+ }
28
+ };
29
+ const stop = real(homedir());
30
+ let directory = real(resolve(cwd));
31
+ const root = parse(directory).root;
32
+ while (directory !== stop) {
33
+ let raw;
34
+ try {
35
+ raw = readFileSync(join(directory, ".nylorun", "link.json"), "utf8");
36
+ }
37
+ catch {
38
+ /* no link here */
39
+ }
40
+ if (raw !== undefined) {
41
+ try {
42
+ return ProjectLinkFileSchema.parse(JSON.parse(raw)).stack;
43
+ }
44
+ catch {
45
+ return undefined;
46
+ }
47
+ }
48
+ if (directory === root)
49
+ return undefined;
50
+ directory = dirname(directory);
51
+ }
52
+ return undefined;
53
+ }
54
+ /**
55
+ * The Host root of the local Host: `options.home`, `NYLORUN_HOME`, or the Host root of the stack
56
+ * named by `options.stack`, `NYLORUN_STACK` or the Project link. Undefined when none names one.
57
+ */
58
+ function resolveHome(options) {
59
+ if (options?.home !== undefined && options.home.trim() !== "")
60
+ return resolve(options.home);
16
61
  const fromEnv = env("NYLORUN_HOME");
17
62
  if (fromEnv)
18
63
  return resolve(fromEnv);
19
- return resolve(join(homedir(), ".nylorun"));
64
+ const stack = options?.stack?.trim() ||
65
+ env("NYLORUN_STACK")?.trim() ||
66
+ linkedStack(options?.cwd ?? process.cwd());
67
+ return stack ? stackHostRoot(stack) : undefined;
20
68
  }
21
69
  function connectionMissing(message) {
22
70
  throw new AdminError("connection_missing", message);
23
71
  }
24
72
  function sourcesTriedMessage(home) {
25
73
  return (`Tried options (url + key), environment (NYLORUN_ADMIN_URL + NYLORUN_ADMIN_KEY), ` +
26
- `and local Host settings (host.json + host-credentials.json under ${home}).`);
74
+ (home
75
+ ? `and local Host settings (host.json + host-credentials.json under ${home}).`
76
+ : "and local Host settings (no stack named: pass `stack`, set NYLORUN_STACK or " +
77
+ "NYLORUN_HOME, or run in a Project that `npx nylorun start` linked)."));
27
78
  }
28
79
  function assertCredentialsSafe(path) {
29
80
  if (process.platform === "win32")
@@ -91,7 +142,7 @@ function readLocalHost(home) {
91
142
  * Resolve Admin API connection once: options → environment → local Host.
92
143
  */
93
144
  export function resolveAdminConnection(options) {
94
- const home = resolveHome(options?.home);
145
+ const home = resolveHome(options);
95
146
  const optionUrl = options?.url?.trim() || undefined;
96
147
  const optionKey = options?.key?.trim() || undefined;
97
148
  if (optionUrl || optionKey) {
@@ -102,7 +153,7 @@ export function resolveAdminConnection(options) {
102
153
  url: optionUrl.replace(/\/$/, ""),
103
154
  key: optionKey,
104
155
  source: "options",
105
- home,
156
+ ...(home ? { home } : {}),
106
157
  };
107
158
  }
108
159
  const envUrl = env("NYLORUN_ADMIN_URL");
@@ -115,10 +166,10 @@ export function resolveAdminConnection(options) {
115
166
  url: envUrl.replace(/\/$/, ""),
116
167
  key: envKey,
117
168
  source: "environment",
118
- home,
169
+ ...(home ? { home } : {}),
119
170
  };
120
171
  }
121
- const local = readLocalHost(home);
172
+ const local = home === undefined ? undefined : readLocalHost(home);
122
173
  if (local) {
123
174
  return {
124
175
  url: local.url.replace(/\/$/, ""),
@@ -147,12 +198,6 @@ function parseProtocolRange(value) {
147
198
  features: record.features,
148
199
  };
149
200
  }
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
201
  function throwFromResponse(status, body) {
157
202
  const parsed = RejectedResponseSchema.safeParse(body);
158
203
  if (parsed.success) {
@@ -161,9 +206,6 @@ function throwFromResponse(status, body) {
161
206
  details: parsed.data.details,
162
207
  });
163
208
  }
164
- if (status === 409) {
165
- throw new AdminError("tenant_conflict", `Admin request conflict (${status})`, { status, details: body });
166
- }
167
209
  if (status === 404) {
168
210
  throw new AdminError("not_found", `Admin request not found (${status})`, {
169
211
  status,
@@ -194,8 +236,6 @@ export class AdminClient {
194
236
  source;
195
237
  key;
196
238
  compatible = false;
197
- /** Features the Host advertised at the last compatibility check. */
198
- features = [];
199
239
  constructor(resolved) {
200
240
  this.url = resolved.url;
201
241
  this.adminUrl = resolved.adminUrl ?? resolved.url;
@@ -239,7 +279,6 @@ export class AdminClient {
239
279
  : `Host is missing required features: ${result.missing.join(", ")}`;
240
280
  throw new AdminError("incompatible_host", `Incompatible Host: ${detail}`, { details: result });
241
281
  }
242
- this.features = [...protocol.features];
243
282
  this.compatible = true;
244
283
  }
245
284
  async request(path, init = {}, options = {}) {
@@ -286,104 +325,12 @@ export class AdminClient {
286
325
  const body = await this.json("/v1/admin/status");
287
326
  return AdminStatusSchema.parse(body);
288
327
  }
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
328
  /**
305
329
  * 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`.
330
+ * Valid when the Host registered that principal (`NYLORUN_DERIVED_PRINCIPALS`, default
331
+ * `project`) on its Tenant.
307
332
  */
308
333
  deriveTenantKey(tenantId, principalId) {
309
334
  return deriveTenantKey(this.key, tenantId, principalId);
310
335
  }
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
336
  }
@@ -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 stack'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 stack'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 { stackHostRoot, 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, stackHostRoot };
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 stack named by `stack`,
29
+ * `NYLORUN_STACK` or the Project link under `cwd`: `~/.nylorun/stacks/<stack>/`).
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, stackHostRoot, } 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, stackHostRoot };
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 stack named by `stack`,
12
+ * `NYLORUN_STACK` or the Project link under `cwd`: `~/.nylorun/stacks/<stack>/`).
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) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nylorun/admin",
3
- "version": "0.6.0-beta",
3
+ "version": "0.7.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.10.0-beta"
28
28
  },
29
29
  "peerDependencies": {
30
30
  "zod": "^4.6.5"