@nylorun/admin 0.2.0-beta → 0.4.0-beta

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.4.0-beta
+
+### Minor Changes
+
+- a322696: **Derived principals** (optional Host feature `derived-principals`): a client that holds the admin key no longer needs to store an application key.
+
+  - `admin.createTenant({ name, principals: ["babai"] })` registers each named principal by the hash of its derived key, and `admin.deriveTenantKey(tenantId, principalId)` (or `deriveTenantKey(adminKey, tenantId, principalId)`) recomputes the key when needed.
+  - `POST /v1/admin/tenants` accepts `derivedPrincipals: [{ id, credentialHash }]`. Ids match `^[a-z][a-z0-9-]{0,31}$` and `studio` is reserved; duplicate ids or credentials answer `400`. A retried create must name the same principals.
+  - `createTenant` with `principals` throws `incompatible_host` before sending anything to a Host without the feature.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [a322696]
+- Updated dependencies [844bff3]
+- Updated dependencies [a322696]
+  - @nylorun/core@0.7.0-beta
+
+## 0.3.0-beta
+
+### Minor Changes
+
+- bf1c2da: **Tenants can register a Studio principal.** `CreateTenantRequest` gains optional `studioCredentialHash` behind the new protocol feature `studio-principal`; the Runtime stores it as application principal `studio`, and idempotent create compares it too. `@nylorun/admin` exports `deriveStudioToken(adminKey, tenantId)` (HMAC-SHA256 over `nylorun/studio/v1`, NUL, Tenant id) and `createTenant` sends the hash of that key, so Studio can reach any Tenant's API with a key derived from the admin key. Clients require the new feature, so upgrade the Runtime with them.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [bf1c2da]
+- Updated dependencies [ba1b239]
+- Updated dependencies [bf1c2da]
+- Updated dependencies [bf1c2da]
+- Updated dependencies [bf1c2da]
+  - @nylorun/core@0.6.0-beta
+
 ## 0.2.0-beta
 
 ### Minor Changes

package/README.md

@@ -23,6 +23,31 @@ idempotency key locally; only the key's hash is sent. On network error or
 `5xx` it retries up to three times with identical values. Persist the returned
 `applicationKey` — the Host never sees it in cleartext again.
 
+`createTenant` also registers the Tenant's Studio principal (`studio`) by
+sending the hash of `deriveStudioToken(adminKey, tenantId)`. Studio derives the
+same key from the admin key to call that Tenant's API, so whoever holds the
+admin key can reach every Tenant created this way.
+
+A client on the Host's machine or server that holds the admin key can avoid
+storing an application key too. Name it as a **derived principal** when the
+Tenant is created, then recompute its key whenever it needs one:
+
+```ts
+const { tenant } = await admin.createTenant({
+  name: "my-app",
+  principals: ["babai"],
+});
+// Later, in any process that holds the admin key:
+const key = admin.deriveTenantKey(tenant.id, "babai");
+```
+
+Ids match `^[a-z][a-z0-9-]{0,31}$`; `studio` is reserved. Only each key's hash
+is sent. The key is `deriveTenantKey(adminKey, tenantId, principalId)`, so
+rotating the admin key rotates every derived key. Principals are named when the
+Tenant is created; an older Tenant keeps its application key. This needs the
+optional Host feature `derived-principals`: `createTenant` checks `/health` and
+throws `incompatible_host` before sending anything to a Host without it.
+
 Local Host resolution reads `host.json` and `host-credentials.json` under
 `NYLORUN_HOME` / `~/.nylorun` (or `options.home`). On POSIX the credentials
 file must be owned by the user and not group- or world-readable. First use
@@ -30,8 +55,7 @@ checks `/health` compatibility and throws `incompatible_host` on mismatch.
 
 Errors are `AdminError` with a registry `code` from `@nylorun/core`
 (`ERROR_CODES`). Re-exports: `PROTOCOL_FEATURES`, `ERROR_CODES`,
-`compareVersions`.
+`compareVersions`, `deriveStudioToken`, `deriveTenantKey`.
 
 Developer applications do **not** depend on this package — only managing
-clients (CLI, desktop Runtime panel, CI) do. See
-[building a desktop client](../docs/building-a-desktop-client.md).
+clients (CLI, desktop Runtime panel, CI) do.

package/dist/client.d.ts

@@ -19,6 +19,8 @@ export declare class AdminClient {
     readonly source: AdminSource;
     private readonly key;
     private compatible;
+    /** Features the Host advertised at the last compatibility check. */
+    private features;
     constructor(resolved: ResolvedAdmin);
     private clearCompatibilityCache;
     private adminHeaders;
@@ -31,8 +33,14 @@ export declare class AdminClient {
     deleteTenant(id: string, options?: {
         activeWork?: "refuse" | "drain" | "cancel";
     }): Promise<void>;
+    /**
+     * The key of derived principal `principalId` on `tenantId`, from this client's admin key.
+     * Valid once the Tenant was created with that principal in `principals`.
+     */
+    deriveTenantKey(tenantId: string, principalId: string): string;
     createTenant(options: {
         name: string;
+        principals?: readonly string[];
     }): Promise<{
         tenant: TenantEnvelope;
         applicationKey: string;

package/dist/client.js

@@ -3,7 +3,8 @@ import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { AdminStatusSchema, AdminTenantSchema, AdminTenantStatusSchema, RejectedResponseSchema, TenantEnvelopeSchema, } from "@nylorun/core/contracts";
-import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, checkCompatibility, newPrincipalId, newTenantId, } from "@nylorun/core/compatibility";
+import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, checkCompatibility, DERIVED_PRINCIPAL_ID_PATTERN, newPrincipalId, newTenantId, } from "@nylorun/core/compatibility";
+import { deriveStudioToken, deriveTenantKey } from "./derived-credentials.js";
 import { AdminError } from "./errors.js";
 function env(name) {
     const value = process.env[name];
@@ -183,6 +184,8 @@ export class AdminClient {
     source;
     key;
     compatible = false;
+    /** Features the Host advertised at the last compatibility check. */
+    features = [];
     constructor(resolved) {
         this.url = resolved.url;
         this.source = resolved.source;
@@ -225,6 +228,7 @@ export class AdminClient {
                 : `Host is missing required features: ${result.missing.join(", ")}`;
             throw new AdminError("incompatible_host", `Incompatible Host: ${detail}`, { details: result });
         }
+        this.features = [...protocol.features];
         this.compatible = true;
     }
     async request(path, init = {}, options = {}) {
@@ -286,14 +290,42 @@ export class AdminClient {
         const activeWork = options?.activeWork ?? "refuse";
         await this.json(`/v1/admin/tenants/${encodeURIComponent(id)}?activeWork=${activeWork}`, "DELETE");
     }
+    /**
+     * The key of derived principal `principalId` on `tenantId`, from this client's admin key.
+     * Valid once the Tenant was created with that principal in `principals`.
+     */
+    deriveTenantKey(tenantId, principalId) {
+        return deriveTenantKey(this.key, tenantId, principalId);
+    }
     async createTenant(options) {
+        const principals = options.principals ?? [];
+        for (const id of principals)
+            if (!DERIVED_PRINCIPAL_ID_PATTERN.test(id) || id === "studio")
+                throw new TypeError(`Principal id '${id}' must match ${DERIVED_PRINCIPAL_ID_PATTERN} and not be 'studio'.`);
+        if (new Set(principals).size !== principals.length)
+            throw new TypeError("Principal ids must be unique.");
+        if (principals.length) {
+            await this.ensureCompatible();
+            if (!this.features.includes("derived-principals"))
+                throw new AdminError("incompatible_host", "Host does not support derived principals (feature derived-principals); upgrade it with `nylorun up`.");
+        }
         const applicationKey = mintApplicationKey();
+        const tenantId = newTenantId();
         const body = {
-            tenantId: newTenantId(),
+            tenantId,
             name: options.name,
             principalId: newPrincipalId(),
             credentialHash: hashCredential(applicationKey),
             idempotencyKey: randomUUID(),
+            studioCredentialHash: hashCredential(deriveStudioToken(this.key, tenantId)),
+            ...(principals.length
+                ? {
+                    derivedPrincipals: principals.map((id) => ({
+                        id,
+                        credentialHash: hashCredential(deriveTenantKey(this.key, tenantId, id)),
+                    })),
+                }
+                : {}),
         };
         let lastError;
         for (let attempt = 0; attempt < 3; attempt += 1) {

package/dist/derived-credentials.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Deterministic Studio key for one Tenant, derived from the admin key.
+ * Same admin key and Tenant always produce the same key. Studio derives it in
+ * memory; the Tenant stores only its hash, as principal `studio`.
+ */
+export declare function deriveStudioToken(adminKey: string, tenantId: string): string;
+/**
+ * Deterministic key of a derived principal (`principalId`, e.g. `babai`) on one Tenant,
+ * derived from the admin key. The Tenant stores only its hash, registered when the Tenant
+ * is created with `principals` (feature `derived-principals`); the client recomputes the
+ * key when it needs it and stores nothing. Rotating the admin key rotates every derived key.
+ */
+export declare function deriveTenantKey(adminKey: string, tenantId: string, principalId: string): string;

package/dist/derived-credentials.js

@@ -0,0 +1,34 @@
+import { createHmac } from "node:crypto";
+/**
+ * Deterministic Studio key for one Tenant, derived from the admin key.
+ * Same admin key and Tenant always produce the same key. Studio derives it in
+ * memory; the Tenant stores only its hash, as principal `studio`.
+ */
+export function deriveStudioToken(adminKey, tenantId) {
+    const message = Buffer.concat([
+        Buffer.from("nylorun/studio/v1", "utf8"),
+        Buffer.from([0]),
+        Buffer.from(tenantId, "utf8"),
+    ]);
+    return createHmac("sha256", Buffer.from(adminKey, "utf8"))
+        .update(message)
+        .digest("hex");
+}
+/**
+ * Deterministic key of a derived principal (`principalId`, e.g. `babai`) on one Tenant,
+ * derived from the admin key. The Tenant stores only its hash, registered when the Tenant
+ * is created with `principals` (feature `derived-principals`); the client recomputes the
+ * key when it needs it and stores nothing. Rotating the admin key rotates every derived key.
+ */
+export function deriveTenantKey(adminKey, tenantId, principalId) {
+    const message = Buffer.concat([
+        Buffer.from("nylorun/principal/v1", "utf8"),
+        Buffer.from([0]),
+        Buffer.from(principalId, "utf8"),
+        Buffer.from([0]),
+        Buffer.from(tenantId, "utf8"),
+    ]);
+    return createHmac("sha256", Buffer.from(adminKey, "utf8"))
+        .update(message)
+        .digest("hex");
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import type { AdminStatus, AdminTenant, AdminTenantStatus, TenantEnvelope } from "@nylorun/core/contracts";
 import { ERROR_CODES, PROTOCOL_FEATURES, compareVersions, type ErrorCode } from "@nylorun/core/compatibility";
+import { deriveStudioToken, deriveTenantKey } from "./derived-credentials.js";
 import { AdminError } from "./errors.js";
 export { ERROR_CODES, PROTOCOL_FEATURES, compareVersions };
 export type { ErrorCode };
 export { AdminError };
+export { deriveStudioToken, deriveTenantKey };
 export interface Admin {
     readonly url: string;
     readonly source: "options" | "environment" | "local-host";
@@ -13,12 +15,20 @@ export interface Admin {
     deleteTenant(id: string, options?: {
         activeWork?: "refuse" | "drain" | "cancel";
     }): Promise<void>;
+    /**
+     * Creates a Tenant. `principals` names derived principals (e.g. `["babai"]`): their keys
+     * come from `deriveTenantKey`, so their clients store none. Needs Host feature
+     * `derived-principals`.
+     */
     createTenant(options: {
         name: string;
+        principals?: readonly string[];
     }): Promise<{
         tenant: TenantEnvelope;
         applicationKey: string;
     }>;
+    /** The key of a derived principal on a Tenant, from this client's admin key. */
+    deriveTenantKey(tenantId: string, principalId: string): string;
 }
 export declare function createAdmin(options?: {
     url?: string;

package/dist/index.js

@@ -1,8 +1,10 @@
 import { ERROR_CODES, PROTOCOL_FEATURES, compareVersions, } from "@nylorun/core/compatibility";
 import { AdminClient, resolveAdminConnection } from "./client.js";
+import { deriveStudioToken, deriveTenantKey } from "./derived-credentials.js";
 import { AdminError } from "./errors.js";
 export { ERROR_CODES, PROTOCOL_FEATURES, compareVersions };
 export { AdminError };
+export { deriveStudioToken, deriveTenantKey };
 export function createAdmin(options) {
     return new AdminClient(resolveAdminConnection(options));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/admin",
-  "version": "0.2.0-beta",
+  "version": "0.4.0-beta",
   "description": "Nylorun Admin API client for Tenants and Host status",
   "type": "module",
   "license": "Apache-2.0",
@@ -24,7 +24,7 @@
     "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\""
   },
   "dependencies": {
-    "@nylorun/core": "0.5.0-beta"
+    "@nylorun/core": "0.7.0-beta"
   },
   "peerDependencies": {
     "zod": "^4.6.5"
@@ -39,7 +39,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nylorun/harness.git",
+    "url": "git+https://github.com/nylorun/agents.git",
     "directory": "admin"
   },
   "publishConfig": {