@nylorun/admin 0.9.0-beta → 0.11.1-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,97 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.11.1-beta
4
+
5
+ ### Patch Changes
6
+
7
+ - Pin core to the tested release.
8
+ - Updated dependencies [4bd2a0b]
9
+ - Updated dependencies [a64aaca]
10
+ - Updated dependencies [40b7648]
11
+ - Updated dependencies [713e676]
12
+ - Updated dependencies [c135267]
13
+ - Updated dependencies [d36f0d9]
14
+ - Updated dependencies [107b07d]
15
+ - @nylorun/core@0.15.0-beta
16
+
17
+ ## 0.11.0-beta
18
+
19
+ ### Major Changes
20
+
21
+ - 3b3bdc6: **The clients use management keys (Runtime and Management APIs, step A3).** The protocol stays at 7; every client keeps working against a protocol 7 Runtime's routes.
22
+
23
+ - `nylorun`: `nylorun start` keeps an application key (`project`) and a management key (`project-management`) for a Project, in `<Host root>/project-credentials.json` and the Project's `.nylorun/credentials.json` (still format 1, with new `managementKey` and `managementPrincipalId` fields). A credentials file holding only an application key gains a management key at the next start. Commands outside a project keep `cli` and `cli-management`. Keys are issued through `nylorun-operate` in the runtime container instead of the Admin API, and `nylorun key put <id> --management` puts a management key. Seeding the Tenant and `nylorun mcp connect` use the management key (`/v1/tenant/vaults`). Studio reaches the Runtime's public listener.
24
+ - `@nylorun/cli`: `status`, `reset`, `configure`, `doctor` and `access signing-keys` use the Management API through `@nylorun/admin` with the Project's management key, or `NYLORUN_MANAGEMENT_KEY`.
25
+ - `@nylorun/studio`: local Studio needs no login. A request on the published loopback address (`localhost` or `127.0.0.1` at Studio's port) acts as signed in; hosts behind a sign-in proxy and embedding keep their login, and state-changing requests still need Studio's own `Origin`. Studio learns its Tenant from `GET /v1/tenant` with its key instead of the Admin API, and its Connections page manages vaults through `@nylorun/admin/client` at `/v1/tenant/vaults`.
26
+ - **Breaking (`@nylorun/admin`, `@nylorun/runtime`): Studio's key is derived from the admin key alone.** `deriveStudioToken(adminKey)` takes no Tenant id (HMAC-SHA256 over `nylorun/studio/v2`). The Host registers the new key's hash at its next start, replacing the old one; an app that embeds Studio and derives its key must update.
27
+ - `@nylorun/core`: `ProjectCredentialsFileSchema` gains optional `managementKey` and `managementPrincipalId`.
28
+
29
+ - 7f763c3: **The Admin API and the operator listener are gone (Runtime and Management APIs, step A5).** Host work moves to the machine: `nylorun` runs `nylorun-operate` inside the runtime container, and every remote client uses the Runtime API or the Management API.
30
+
31
+ - **Breaking (`@nylorun/runtime`):** `/v1/admin/*` (status, host, shutdown, keys, openapi.json) is removed; it answers like any unknown route. The operator listener, `NYLORUN_ADMIN_LISTEN_PORT`, `NYLORUN_ADMIN_LISTEN_HOST`, `NYLORUN_ADMIN_ALLOWED_HOSTS` and `host.json`'s `adminPort` are gone, and so is the `admin-openapi.json` package file. Stop the Host with SIGTERM. `nylorun-operate status [--json]` reports the version, protocol and the Tenant's id, name, state and cause, exiting 2 when the Tenant is not open. `/ready` adds `harness: { mode, connected }` while the Tenant is open. `startEphemeralRuntime` loses `operatorListener` and `adminUrl`. The admin key stays: it derives Studio's key.
32
+ - **Breaking (`@nylorun/admin`):** `createAdmin()` is the Management API client (`tenant`, `keys`, `models`, `vaults`, `signingKeys`, `settings`) with a management key: explicit `{ url, key }`, else `NYLORUN_RUNTIME_URL` + `NYLORUN_MANAGEMENT_KEY`, else the Project link's or the local Host root's management key. `status()`, `adminUrl`, the Admin API keys, `NYLORUN_ADMIN_URL`/`NYLORUN_ADMIN_KEY` and `OPERATOR_KEYS_FEATURE` are removed; `deriveStudioToken` and `mintStudioLoginToken` stay.
33
+ - **Breaking (`@nylorun/core`):** `admin-status` leaves `PROTOCOL_FEATURES` (the Host still advertises it for protocol 5–7 clients) and `operator-keys` is removed; `AdminStatusSchema`, `AdminHostStatusSchema`, `HostAggregateSchema` and `HostShutdownResponseSchema` are removed.
34
+ - **Breaking (`nylorun`):** no admin port: `NYLORUN_ADMIN_PORT` is no longer written or published (an existing one is ignored). `nylorun start` waits for `/ready`, and `nylorun status` reads readiness from `/ready` and the Tenant from `nylorun-operate status`.
35
+ - `@nylorun/cli`: `nylo status` no longer falls back to the Admin API; when the Tenant does not answer it points to `npx nylorun status`.
36
+
37
+ ### Minor Changes
38
+
39
+ - a6108f4: **The Management API's routes and client (Runtime and Management APIs, step A2).** Additive; the protocol stays at 7.
40
+
41
+ - `@nylorun/runtime`: `GET /v1/tenant/keys`, `PUT /v1/tenant/keys/{keyId}` and `DELETE /v1/tenant/keys/{keyId}` manage the Tenant's application keys with a management key. A management key's name, `studio` and `bootstrap` are refused, so no API call creates, rotates or deletes a management key. Vaults (`/v1/tenant/vaults…`, including `…/oauth/start`) and signing keys (`/v1/tenant/signing-keys…`) are also served under `/v1/tenant`, for management keys only; the old `/v1/vaults…` and `/v1/access/signing-keys…` paths keep serving application keys until protocol 8. `GET /v1/oauth/callback` and `GET /v1/access/jwks` keep their paths.
42
+ - `@nylorun/admin`: `createManagementClient({ url, key })` is the Management API's client: `tenant` (status, seed, reset), `keys` (application keys), `models` (catalog, providers, get, put, select, usage, budgets), `vaults` (with credentials and `startOAuth`), `signingKeys` and `settings` (sandbox, artifacts). `@nylorun/admin/client` exports it with no Node module, for browser apps behind a proxy that adds the key.
43
+
44
+ - c66d8ed: Add optional session reads and a resumable model-ledger export: pinned manifests, usage totals, model calls, and opt-in session/history/sandbox pages (Host feature `session-reads`), and `GET /v1/tenant/calls/model` on the Management API (Host feature `calls-export`). Usage and model calls take an application key acting as itself; the export takes a management key. Runtime reads use a separate bounded, read-only Drizzle pool. The additive migration `0012_session_reads` preserves unknown legacy creation times and usage quality; the export uses safe transaction order without skipping committed rows. `@nylorun/agents` adds `client.sessions.page()`, `session.manifest()`, `session.usage()`, `session.modelCalls()`, `session.history({ limit })` and `client.sandboxes.page()`; `@nylorun/admin` adds `models.exportCalls()`. Legacy unpaged responses are unchanged.
45
+
46
+ ### Patch Changes
47
+
48
+ - Pin core to the tested release.
49
+ - Updated dependencies [3b3bdc6]
50
+ - Updated dependencies [6576e12]
51
+ - Updated dependencies [b28bdd7]
52
+ - Updated dependencies [cc107b1]
53
+ - Updated dependencies [7f763c3]
54
+ - Updated dependencies [98b0d37]
55
+ - Updated dependencies [c66d8ed]
56
+ - @nylorun/core@0.14.0-beta
57
+
58
+ ## 0.10.0-beta
59
+
60
+ ### Major Changes
61
+
62
+ - 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.
63
+
64
+ - **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`.
65
+ - **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`.
66
+ - **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`.
67
+ - **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.
68
+ - **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`.
69
+ - **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.
70
+ - **Breaking (`@nylorun/cli`):** `nylo access policy|keys|revoke|token` are removed and name what replaces them; `nylo access signing-keys list|rotate|revoke` stays.
71
+ - **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.
72
+ - **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`.
73
+ - `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.
74
+
75
+ ### Minor Changes
76
+
77
+ - 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.
78
+
79
+ - `@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`.
80
+ - `nylorun key put|list|rm <id>` manages a running local Tenant's keys; `put` prints the key once on stdout.
81
+ - `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.
82
+ - `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).
83
+ - 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.
84
+
85
+ ### Patch Changes
86
+
87
+ - Pin core to the tested release.
88
+ - Updated dependencies [8773586]
89
+ - Updated dependencies [e1bfb4b]
90
+ - Updated dependencies [5cfaed9]
91
+ - Updated dependencies [bd478ee]
92
+ - Updated dependencies [c0b604e]
93
+ - @nylorun/core@0.13.0-beta
94
+
3
95
  ## 0.9.0-beta
4
96
 
5
97
  ### Major Changes
package/README.md CHANGED
@@ -1,59 +1,134 @@
1
1
  # @nylorun/admin
2
2
 
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`.
3
+ The Management API client (protocol 8): the Tenant's status, seed and reset, its
4
+ models, vaults, signing keys, settings and application keys, through
5
+ `/v1/tenant/*` with a **management key**. It also holds the two helpers over the
6
+ admin key that Studio needs. Depends only on `@nylorun/core`.
5
7
  Requires Node 24+. Vocabulary: [runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
6
8
 
9
+ Developer applications do **not** depend on this package: they use the Runtime
10
+ API through `@nylorun/agents`. Operators' clients do: the CLI, Studio, CI and
11
+ your own tools.
12
+
7
13
  ```ts
8
14
  import { createAdmin } from "@nylorun/admin";
9
15
 
10
- // Resolution: explicit options → NYLORUN_ADMIN_URL + NYLORUN_ADMIN_KEY → local Host
11
16
  const admin = createAdmin();
12
17
  // or: createAdmin({ url, key }) / createAdmin({ tenant: "my-app" }) / createAdmin({ home })
13
18
 
14
- const { tenant } = await admin.status();
15
- // tenant: { id, name, state: "open" | "unavailable", envelope, cause? }
19
+ const status = await admin.tenant.status(); // GET /v1/tenant
20
+ const model = await admin.models.get(); // the Tenant's model, never its secret
21
+ const { key } = await admin.keys.put("backend"); // a new application key, shown once
22
+ ```
23
+
24
+ ## Connecting
25
+
26
+ `createAdmin(options?)` resolves the URL and the management key once, in this
27
+ order, and `admin.source` says which one it used (`options`, `environment` or
28
+ `local-host`):
29
+
30
+ 1. `options`: `url` and `key` (a management key), both or neither.
31
+ 2. The environment: `NYLORUN_RUNTIME_URL` and `NYLORUN_MANAGEMENT_KEY`. Only the
32
+ key selects this: `NYLORUN_RUNTIME_URL` alone is an app's, with
33
+ `NYLORUN_SERVER_KEY`.
34
+ 3. The local Host. The URL comes from `host.json` in the Host root:
35
+ `options.home`, else `NYLORUN_HOME`, else `~/.nylorun/tenants/<tenant>/` for
36
+ the local Tenant named by `options.tenant`, `NYLORUN_TENANT` or the Project
37
+ link (`.nylorun/link.json`, format 3, found from `options.cwd` upwards). The
38
+ key is the `managementKey` of the linked Project's `.nylorun/credentials.json`,
39
+ else of the Host root's `project-credentials.json`, else of its
40
+ `cli-credentials.json`. `nylorun start` writes them (the keys
41
+ `project-management` and `cli-management`). On POSIX a credentials file must
42
+ be the user's and not group- or world-readable.
43
+
44
+ When none resolves, or the Project link is from an older nylorun, it throws
45
+ `connection_missing` and lists what it tried. The first request checks the
46
+ Host's `/health` and throws `incompatible_host` unless the Host serves protocol
47
+ 8 with the feature `management-api`.
48
+
49
+ Management keys are issued on the Tenant's machine only:
50
+ `npx nylorun key put <id> --management` on a local Tenant, or
51
+ `nylorun-operate keys put <id> --role management` inside the runtime container
52
+ ([SELF_HOSTING.md](../SELF_HOSTING.md#keys)). No API call creates one.
53
+
54
+ ## The groups
55
+
56
+ | Group | Methods | Routes |
57
+ | --- | --- | --- |
58
+ | `admin.tenant` | `status()`, `seed(request)`, `reset(request)` | `GET /v1/tenant`, `PUT /v1/tenant/config/seed`, `POST /v1/tenant/reset` |
59
+ | `admin.keys` | `list()`, `put(id)`, `delete(id)` | `/v1/tenant/keys…` |
60
+ | `admin.models` | `catalog()`, `providers()`, `get()`, `put(request)`, `select(request)`, `usage(query)`, `budgets.get()`, `budgets.put(request)` | `/v1/tenant/models`, `/providers`, `/model`, `/model/selection`, `/usage`, `/budgets` |
61
+ | `admin.vaults` | `create`, `list(ownerUserId?)`, `get`, `delete`, `credentials.create`, `.list`, `.get`, `.rotate`, `.delete`, `startOAuth(vaultId, { url, server, clientId? })` | `/v1/tenant/vaults…` |
62
+ | `admin.signingKeys` | `list()`, `rotate({ force? })`, `revoke(kid)` | `/v1/tenant/signing-keys…` |
63
+ | `admin.settings` | `sandbox.get()`, `sandbox.put(request)`, `artifacts.get()`, `artifacts.put(request)` | `/v1/tenant/sandbox`, `/v1/tenant/artifacts` |
64
+
65
+ A request body's `requestId` is optional: the client makes one.
66
+
67
+ `admin.keys` manages the Tenant's **application keys**, the keys app servers
68
+ use on the Runtime API. `put` creates a key or rotates it and returns it once;
69
+ a rotated or deleted key stops authenticating on its next request. `list`
70
+ shows every key's id, role and when it was issued, never the keys. Ids match
71
+ `^[a-z][a-z0-9-]{0,31}$`. `studio`, `bootstrap` and the id of a management key
72
+ are refused, so a management key can never mint another.
73
+
74
+ ```ts
75
+ const { key } = await admin.keys.put("backend"); // { id, role, createdAt, key, rotated }
76
+ await admin.keys.list(); // [{ id, role, createdAt }]
77
+ await admin.keys.delete("backend"); // true when it existed
78
+ ```
79
+
80
+ Installation vaults hold the installation's shared credentials. A session
81
+ attaches them by id (`vaultIds`) through the Runtime API:
82
+
83
+ ```ts
84
+ const vault = await admin.vaults.create({ scope: "installation", name: "tools", idempotencyKey: "tools" });
85
+ await admin.vaults.credentials.create(vault.id, {
86
+ name: "linear",
87
+ idempotencyKey: "linear",
88
+ auth: { type: "bearer", url: "https://mcp.linear.app/mcp", token: process.env.LINEAR_TOKEN! },
89
+ });
16
90
  ```
17
91
 
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`, …).
92
+ ## In a browser
23
93
 
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:
94
+ `@nylorun/admin/client` exports `createManagementClient({ url, key?, fetch?,
95
+ headers? })` and `ManagementClient`, with the same groups and no Node module.
96
+ It is for a browser app behind its own server that adds the management key, as
97
+ Studio's Connections page is: omit `key`, and point `url` at that server. Never
98
+ send a management key from a browser: the Runtime refuses any key sent with an
99
+ `Origin` (`403 origin_rejected`).
26
100
 
27
101
  ```ts
28
- const key = admin.deriveTenantKey(tenant.id!, "project");
29
- // deriveTenantKey(adminKey, tenantId, principalId) and
30
- // deriveStudioToken(adminKey, tenantId) are exported too.
102
+ import { createManagementClient } from "@nylorun/admin/client";
103
+
104
+ const admin = createManagementClient({ url: "/my-proxy" });
31
105
  ```
32
106
 
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.
107
+ The main entry exports `createManagementClient` too, for a server that already
108
+ has its URL and key.
109
+
110
+ ## Studio's key and login tokens
111
+
112
+ The admin key in `host-credentials.json` is the installation's root secret, and
113
+ no request accepts it. Two helpers use it locally:
114
+
115
+ - `deriveStudioToken(adminKey)` returns Studio's key: HMAC-SHA256 with the admin
116
+ key over `nylorun/studio/v2`. It names no Tenant. The Host registers its hash
117
+ as principal `studio` (role `studio`, which reaches both APIs) at every start,
118
+ so Studio stores no key and rotating the admin key rotates it. It is the only
119
+ key derived from the admin key.
120
+ - `mintStudioLoginToken({ studioUrl, adminKey, tenant?, subject? })` asks Studio
121
+ (`POST /_studio/login-tokens`) for a single-use login token, for an app that
122
+ embeds Studio. Its optional `tenant` must name the Host's Tenant; `subject`
123
+ names the person in Studio's log.
124
+
125
+ ## Errors and exports
52
126
 
53
127
  Errors are `AdminError` with a registry `code` from `@nylorun/core`
54
- (`ERROR_CODES`). Re-exports: `PROTOCOL_FEATURES`, `ERROR_CODES`,
55
- `compareVersions`, `deriveStudioToken`, `deriveTenantKey`, `tenantHostRoot`,
56
- `PROJECT_PRINCIPAL_ID`.
128
+ (`ERROR_CODES`) and the HTTP `status`. An application key here is
129
+ `403 key_role_mismatch`; a management key sent with `Nylorun-Subject` or
130
+ `Nylorun-Scopes` is `403 subject_invalid`.
57
131
 
58
- Developer applications do **not** depend on this package — only managing
59
- clients (CLI, desktop Runtime panel, CI) do.
132
+ Exports: `createAdmin`, `createManagementClient`, `ManagementClient`,
133
+ `AdminError`, `deriveStudioToken`, `mintStudioLoginToken`, `tenantHostRoot`,
134
+ `PROTOCOL_FEATURES`, `ERROR_CODES` and `compareVersions`.
package/dist/client.d.ts CHANGED
@@ -1,13 +1,9 @@
1
- import { type AdminStatus } from "@nylorun/core/contracts";
1
+ import { ManagementClient } from "./management.js";
2
2
  export type AdminSource = "options" | "environment" | "local-host";
3
3
  export interface ResolvedAdmin {
4
- /** The Host's Tenant API URL (what a Project link names). */
4
+ /** The Tenant's URL. */
5
5
  url: string;
6
- /**
7
- * Where the Admin API answers when the Host serves it on its own operator listener
8
- * (`adminPort` in host.json). Defaults to `url`.
9
- */
10
- adminUrl?: string;
6
+ /** A management key. */
11
7
  key: string;
12
8
  source: AdminSource;
13
9
  /** The Host root read for local Host settings, when one was found. */
@@ -15,6 +11,7 @@ export interface ResolvedAdmin {
15
11
  }
16
12
  export interface AdminConnectionOptions {
17
13
  url?: string;
14
+ /** A management key. */
18
15
  key?: string;
19
16
  /** The Host root itself (overrides `NYLORUN_HOME` and the Tenant). */
20
17
  home?: string;
@@ -25,29 +22,10 @@ export interface AdminConnectionOptions {
25
22
  }
26
23
  /** A local Tenant's Host root: `~/.nylorun/tenants/<name>/`. */
27
24
  export declare function tenantHostRoot(name: string): string;
28
- /**
29
- * Resolve Admin API connection once: options → environment → local Host.
30
- */
25
+ /** Resolve the Management API connection once: options → environment → local Host. */
31
26
  export declare function resolveAdminConnection(options?: AdminConnectionOptions): ResolvedAdmin;
32
- export declare class AdminClient {
33
- /** The Host's Tenant API URL. */
34
- readonly url: string;
35
- /** Where Admin API requests go: the operator listener, or `url` on a single-port Host. */
36
- readonly adminUrl: string;
27
+ /** What `createAdmin` returns: the Management API client, and where its connection came from. */
28
+ export declare class AdminClient extends ManagementClient {
37
29
  readonly source: AdminSource;
38
- private readonly key;
39
- private compatible;
40
30
  constructor(resolved: ResolvedAdmin);
41
- private clearCompatibilityCache;
42
- private adminHeaders;
43
- private ensureCompatible;
44
- private request;
45
- private json;
46
- status(): Promise<AdminStatus>;
47
- /**
48
- * The key of derived principal `principalId` on `tenantId`, from this client's admin key.
49
- * Valid when the Host registered that principal (`NYLORUN_DERIVED_PRINCIPALS`, default
50
- * `project`) on its Tenant.
51
- */
52
- deriveTenantKey(tenantId: string, principalId: string): string;
53
31
  }