@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 +34 -0
- package/README.md +36 -39
- package/dist/client.d.ts +18 -22
- package/dist/client.js +68 -121
- package/dist/derived-credentials.d.ts +7 -6
- package/dist/derived-credentials.js +7 -6
- package/dist/index.d.ts +14 -24
- package/dist/index.js +7 -2
- package/dist/studio-login.d.ts +2 -2
- package/dist/studio-login.js +2 -2
- package/package.json +2 -2
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
|
|
4
|
-
|
|
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({
|
|
12
|
+
// or: createAdmin({ url, key }) / createAdmin({ stack: "my-app" }) / createAdmin({ home })
|
|
13
13
|
|
|
14
|
-
const
|
|
15
|
-
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
`
|
|
24
|
-
|
|
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
|
-
|
|
27
|
-
|
|
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
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
Local Host resolution reads `host.json` and `host-credentials.json`
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 {
|
|
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,
|
|
6
|
-
import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, checkCompatibility,
|
|
7
|
-
import {
|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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
|
|
16
|
-
*
|
|
17
|
-
* key when it needs it and stores nothing.
|
|
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
|
|
19
|
-
*
|
|
20
|
-
*
|
|
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
|
|
26
|
-
*
|
|
27
|
-
* key when it needs it and stores nothing.
|
|
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,
|
|
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
|
-
*
|
|
24
|
-
*
|
|
25
|
-
* `
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
export
|
|
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
|
}
|
package/dist/studio-login.d.ts
CHANGED
|
@@ -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`
|
|
9
|
-
*
|
|
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: {
|
package/dist/studio-login.js
CHANGED
|
@@ -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`
|
|
10
|
-
*
|
|
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.
|
|
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.
|
|
27
|
+
"@nylorun/core": "0.10.0-beta"
|
|
28
28
|
},
|
|
29
29
|
"peerDependencies": {
|
|
30
30
|
"zod": "^4.6.5"
|