nylorun 0.29.8-beta → 0.30.0-beta

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # nylorun
 
+## 0.30.0-beta
+
+### Minor Changes
+
+- c4758c0: Pods on Agent Substrate (preview): keys now reach commands through Substrate's own egress ([ADR-142](https://github.com/nylorun/factory/blob/main/decisions/platform/2026-11-13-substrate-egress-adds-keys.md)). A command sends its stand-in, with no proxy, and Substrate's egress replaces the header on each request to a host the Agent has a key for, so `curl`, `gh` and SDKs work against keyed hosts, over HTTP/2 too. A removed key now fails closed with 403 instead of sending the stand-in.
+
+  - Each host the Agent has an `environment_secret` or slot for, and each host its owner connected through the outside credential source, becomes an `https` rule in the actor's egress policy that names a reference, never a value.
+  - The keys provider (`sandboxes provider`, from the sandboxes image) runs beside Substrate's egress. For every keyed request it asks egress-gate's new decide route (`POST /nylorun/v1/egress/decide`, token `NYLORUN_EGRESS_KEYS_TOKEN`), which checks that the actor is the sandbox's current incarnation and returns the vault's header value. For a person's key it returns only who owns it, and the provider fetches the value from the outside source's new `/v1/fetch`.
+  - The outside credential source's `/v1/hosts` may name each host's header (`{ host, header }`); a plain host name still means `Authorization`.
+  - The engine on Substrate writes a trust bundle with Substrate's egress CA and names it in `SSL_CERT_FILE` and the other trust variables.
+  - `nylorun local sandbox enable --backend substrate` deploys the keys provider in `ate-system`, publishes the edge's keys port (8795 by default), and checks that Substrate's egress was installed asking it (`--credential-provider='[{"name":"keys.nylorun.dev","address":"nylorun-keys-provider.ate-system.svc:50051"}]'`). When it wasn't, keys stay off and `enable` says how to turn them on. `sandbox status` shows whether keys are on.
+
+### Patch Changes
+
+- Pin runtime to the tested release.
+
 ## 0.29.8-beta
 
 ### Patch Changes

package/README.md

@@ -467,8 +467,21 @@ owners (a 10-minute token for `ate-system/ate-client`, deleted after use), it ma
 atespace with the sandboxes service as its editor.
 
 Each Agent's network (preset, hosts, suffixes) becomes its actors' egress policy: only the edge
-and the allowed hosts resolve and connect. Keys injected at egress, builds and tags are not on
-Substrate yet. `nylorun local sandbox status` names the backend, the atespace and the edge.
+and the allowed hosts resolve and connect.
+
+Keys reach commands through Substrate's own egress
+([ADR-142](https://github.com/nylorun/factory/blob/main/decisions/platform/2026-11-13-substrate-egress-adds-keys.md)):
+a command sends its stand-in (`Authorization: Bearer nylorun_managed`) with no proxy, and
+Substrate's egress replaces the header on each request to a host the Agent has a key for, asking
+the keys provider, which asks the Tenant. `enable` deploys the keys provider in `ate-system`
+(`nylorun-keys-provider`, from the sandboxes image), publishes a third edge port (8795 by
+default) for it, and keeps its token in `docker/.env` (`NYLORUN_EGRESS_KEYS_TOKEN`). Substrate's
+egress must be installed asking it:
+`ate-setup deploy ate-system` and `deploy atenet` with
+`--credential-provider='[{"name":"keys.nylorun.dev","address":"nylorun-keys-provider.ate-system.svc:50051"}]'`.
+Without that, `enable` says so and keys stay off. A person's connected keys come from the outside
+credential source the shell names (`NYLORUN_CREDENTIAL_PROVIDER_URL` and `_TOKEN`), which must
+answer `/v1/fetch` and be reachable from the cluster. Builds and tags are not on Substrate yet. `nylorun local sandbox status` names the backend, the atespace, the edge and whether keys are on.
 `disable` works as for agent-sandbox; the atespace stays until you delete it with Substrate's
 tools.
 

package/dist/sandbox/cluster-file.d.ts

@@ -38,12 +38,16 @@ export interface ClusterFile {
         serviceAccount: string;
         endpoint?: string;
         version?: string;
+        /** keysPort: where the keys provider reaches the egress service's decide route (ADR-142). */
         edge: {
             host: string;
             harnessPort: number;
             gatesPort: number;
+            keysPort?: number;
         };
         workerSelector?: Record<string, string>;
+        /** The keys provider's name, once it is deployed and registered with Substrate's egress. */
+        keysProvider?: string;
     };
 }
 export declare function sandboxesDir(root: string): string;

package/dist/sandbox/commands.d.ts

@@ -71,5 +71,20 @@ export declare function installSubstrate(deps: SandboxDeps, input: {
     cluster: ClusterFile;
     token: string;
 }>;
+/**
+ * Keys at Substrate's egress (ADR-142): deploys the keys provider with this Tenant's entry (the
+ * edge's keys port, its token and CA, and the Host's outside credential source when the shell
+ * names one), keeping other Tenants' entries, and checks Substrate's egress asks it. Returns
+ * whether it does: when not, keys stay off and `enable` says how to turn them on.
+ */
+export declare function deployKeysProvider(deps: SandboxDeps, root: string, cluster: ClusterFile, input: {
+    image: string;
+    port: number;
+    token: string;
+    outside?: {
+        url: string;
+        token: string;
+    };
+}): Promise<boolean>;
 /** `nylorun local sandbox <enable|disable|status>`. */
 export declare function runSandboxCommand(args: readonly string[], deps: SandboxDeps): Promise<number>;

package/dist/sandbox/commands.js

@@ -10,7 +10,7 @@ import { apiRoute, readClusterFile, removeClusterFiles, writeClusterFiles, } fro
 import { contexts, kube } from "./kubectl.js";
 import { CONTROLLER_DEPLOYMENT, CONTROLLER_NAMESPACE, CONTROLLER_SHA256, CONTROLLER_URL, CONTROLLER_VERSION, networkPolicy, SANDBOX_API_VERSION, SANDBOX_CRD, tenantLabel, tenantManifests, tenantNamespace, TOKEN_SECRET, } from "./manifests.js";
 import { assertIPv4, defaultBind, parseNslookup, parseProbePorts, runProbe } from "./probe.js";
-import { corefileWithEdge, edgeHost, PREFERRED_EDGE_PORTS, SUBSTRATE_API_SERVICE, SUBSTRATE_AUDIENCE, SUBSTRATE_NAMESPACE, SUBSTRATE_OWNER_ACCOUNT, substrateManifests, } from "./substrate.js";
+import { corefileWithEdge, edgeHost, KEYS_PROVIDER, KEYS_PROVIDER_FLAG, KEYS_PROVIDER_NAME, keysProviderManifests, keysProviderRegistered, PREFERRED_EDGE_PORTS, SUBSTRATE_API_SERVICE, SUBSTRATE_AUDIENCE, SUBSTRATE_NAMESPACE, SUBSTRATE_OWNER_ACCOUNT, substrateManifests, } from "./substrate.js";
 import { PROBE_IMAGE, SERVICE_ACCOUNT } from "./manifests.js";
 import { join } from "node:path";
 import { rm, writeFile } from "node:fs/promises";
@@ -268,6 +268,40 @@ async function prepareSubstrate(deps, root, cluster, image) {
         await rm(tokenFile, { force: true });
     }
 }
+/**
+ * Keys at Substrate's egress (ADR-142): deploys the keys provider with this Tenant's entry (the
+ * edge's keys port, its token and CA, and the Host's outside credential source when the shell
+ * names one), keeping other Tenants' entries, and checks Substrate's egress asks it. Returns
+ * whether it does: when not, keys stay off and `enable` says how to turn them on.
+ */
+export async function deployKeysProvider(deps, root, cluster, input) {
+    const k = kube(deps.kubectl, cluster.context);
+    const substrate = cluster.substrate;
+    const edgeCa = await readFile(join(sandboxesDir(root), "edge-ca.pem"), "utf8");
+    const existing = await k.getJson(["secret", KEYS_PROVIDER, "-n", SUBSTRATE_NAMESPACE]);
+    let tenants = {};
+    const raw = existing?.data?.["config.json"];
+    if (raw) {
+        try {
+            tenants = JSON.parse(Buffer.from(raw, "base64").toString("utf8")).tenants ?? {};
+        }
+        catch {
+            tenants = {};
+        }
+    }
+    tenants[substrate.atespace] = {
+        decideUrl: `https://${substrate.edge.host}:${input.port}/nylorun/v1/egress/decide`,
+        token: input.token,
+        edgeCa,
+        ...(input.outside ? { outside: input.outside } : {}),
+    };
+    await k.apply("Deploying the keys provider", keysProviderManifests(input.image, tenants));
+    const egress = await k.getJson(["deployment", "atenet-egress", "-n", SUBSTRATE_NAMESPACE]);
+    const registered = keysProviderRegistered(egress);
+    if (!registered)
+        deps.stack.err(`Keys at Substrate's egress are off: Substrate's egress does not ask ${KEYS_PROVIDER_NAME}. Install Substrate with ${KEYS_PROVIDER_FLAG} (ate-setup deploy ate-system and deploy atenet), then run enable again. Until then keyed hosts are passed through with their stand-ins.`);
+    return registered;
+}
 async function enable(deps, args) {
     const { stack } = deps;
     const flags = parseStackFlags(args, { booleans: ["--no-pull"], values: ["--context", "--tenant", "--backend", "--host-address", "--bind-address", "--probe-ports"] }, ENABLE_USAGE);
@@ -310,7 +344,9 @@ async function enable(deps, args) {
         const edgePorts = {
             harness: await pick(PREFERRED_EDGE_PORTS.harness, persisted?.edgeHarnessPort),
             gates: await pick(PREFERRED_EDGE_PORTS.gates, persisted?.edgeGatesPort),
+            keys: await pick(PREFERRED_EDGE_PORTS.keys, persisted?.edgeKeysPort),
         };
+        const keysToken = persisted?.keysToken ?? randomBytes(32).toString("hex");
         const images = stackImages(stack.env, { runtime: stack.runtimeVersion, studio: stack.studioVersion });
         const installed = await installSubstrate(deps, {
             context,
@@ -322,6 +358,18 @@ async function enable(deps, args) {
         });
         await writeClusterFiles(tenant.paths.root, installed.cluster, installed.token);
         await prepareSubstrate(deps, tenant.paths.root, installed.cluster, images.sandboxes);
+        const outsideUrl = stack.env.NYLORUN_CREDENTIAL_PROVIDER_URL?.trim();
+        const outsideToken = stack.env.NYLORUN_CREDENTIAL_PROVIDER_TOKEN?.trim();
+        const keysOn = await deployKeysProvider(deps, tenant.paths.root, installed.cluster, {
+            image: images.sandboxes,
+            port: edgePorts.keys,
+            token: keysToken,
+            ...(outsideUrl && outsideToken ? { outside: { url: outsideUrl, token: outsideToken } } : {}),
+        });
+        installed.cluster.substrate.edge.keysPort = edgePorts.keys;
+        if (keysOn)
+            installed.cluster.substrate.keysProvider = KEYS_PROVIDER_NAME;
+        await writeClusterFiles(tenant.paths.root, installed.cluster, installed.token);
         const settings = {
             token: persisted?.token ?? randomBytes(32).toString("hex"),
             image: images.sandboxes,
@@ -332,6 +380,8 @@ async function enable(deps, args) {
             bind: installed.cluster.bindAddress,
             edgeHarnessPort: edgePorts.harness,
             edgeGatesPort: edgePorts.gates,
+            edgeKeysPort: edgePorts.keys,
+            keysToken,
         };
         await restartTenant(stack, { name: tenant.name, sandboxes: settings });
         const ready = await stack.docker.stream(tenant.compose("up", "--detach", "--wait", "--wait-timeout", String(cliTuning().sandbox.composeWaitSeconds), "sandboxes"));
@@ -340,6 +390,9 @@ async function enable(deps, args) {
         const c = installed.cluster;
         stack.out(`Sandboxes ${tenant.name}  enabled on ${c.context} (backend substrate, atespace ${c.substrate.atespace}; preview)`);
         stack.out(`Actors reach the edge ${c.substrate.edge.host} (${c.hostAddress}) on ports ${edgePorts.harness} and ${edgePorts.gates}`);
+        stack.out(keysOn
+            ? `Keys at Substrate's egress: on (${KEYS_PROVIDER_NAME}, edge port ${edgePorts.keys})`
+            : `Keys at Substrate's egress: off (see above)`);
         return 0;
     }
     if (probePorts && [probePorts.allowed, probePorts.denied].some((port) => taken.has(port)))
@@ -440,6 +493,7 @@ async function status(deps, args) {
         if (cluster.backend === "substrate" && cluster.substrate) {
             stack.out(`Namespace   ${cluster.namespace}  backend substrate (preview), atespace ${cluster.substrate.atespace}`);
             stack.out(`Edge        ${cluster.substrate.edge.host} ports ${cluster.substrate.edge.harnessPort}, ${cluster.substrate.edge.gatesPort} (bound on ${cluster.bindAddress}, actors reach ${cluster.hostAddress})`);
+            stack.out(`Keys        ${cluster.substrate.keysProvider ? `on: ${cluster.substrate.keysProvider}, edge port ${cluster.substrate.edge.keysPort}` : "off: Substrate's egress does not ask the keys provider (see enable's output)"}`);
         }
         else {
             stack.out(`Namespace   ${cluster.namespace}  agent-sandbox ${cluster.controllerVersion}`);

package/dist/sandbox/substrate.d.ts

@@ -8,6 +8,7 @@ export declare const SUBSTRATE_AUDIENCE = "api.ate-system.svc";
 export declare const PREFERRED_EDGE_PORTS: {
     readonly harness: 8793;
     readonly gates: 8794;
+    readonly keys: 8795;
 };
 /** The name actors dial for the edge, unique to the Tenant's namespace. */
 export declare function edgeHost(namespace: string): string;
@@ -23,3 +24,35 @@ export declare function substrateManifests(namespace: string): object[];
  * no `.:53` block or already has a `hosts` plugin of its own.
  */
 export declare function corefileWithEdge(corefile: string, host: string, address: string): string | undefined;
+/**
+ * Keys at Substrate's egress (ADR-142): the keys provider, `sandboxes provider` from the sandboxes
+ * image, runs beside Substrate's egress in its namespace. One per cluster: its config Secret holds
+ * an entry per Tenant, by atespace. Substrate learns it at its own install
+ * (`--credential-provider`); `enable` deploys it and checks that registration, never changing
+ * Substrate's install.
+ */
+export declare const KEYS_PROVIDER_NAME = "keys.nylorun.dev";
+export declare const KEYS_PROVIDER = "nylorun-keys-provider";
+export declare const KEYS_PROVIDER_PORT = 50051;
+/** The address Substrate's egress dials, as `ate-setup`'s `--credential-provider` names it. */
+export declare const KEYS_PROVIDER_ADDRESS = "nylorun-keys-provider.ate-system.svc:50051";
+/** The flag to install Substrate with, so its egress asks the keys provider. */
+export declare const KEYS_PROVIDER_FLAG = "--credential-provider='[{\"name\":\"keys.nylorun.dev\",\"address\":\"nylorun-keys-provider.ate-system.svc:50051\"}]'";
+/** One Tenant's entry in the keys provider's config. */
+export interface KeysProviderTenant {
+    readonly decideUrl: string;
+    readonly token: string;
+    readonly edgeCa: string;
+    readonly outside?: {
+        readonly url: string;
+        readonly token: string;
+    };
+}
+/** Whether Substrate's egress was installed with the keys provider among its providers. */
+export declare function keysProviderRegistered(deployment: unknown): boolean;
+/**
+ * The keys provider: its ServiceAccount, Deployment, Service, a NetworkPolicy that admits only
+ * Substrate's egress, and its config Secret. Mutual TLS as Substrate's reference provider serves
+ * it: its servicedns pod certificate, callers' podidentity certificates.
+ */
+export declare function keysProviderManifests(image: string, tenants: Record<string, KeysProviderTenant>): object[];

package/dist/sandbox/substrate.js

@@ -12,7 +12,7 @@ export const SUBSTRATE_OWNER_ACCOUNT = "ate-client";
 /** The audience ate-api-server accepts: its Service's DNS name. */
 export const SUBSTRATE_AUDIENCE = `${SUBSTRATE_API_SERVICE}.${SUBSTRATE_NAMESPACE}.svc`;
 /** Preferred host ports for the edge: the Harness API's and the gates' TLS fronts. */
-export const PREFERRED_EDGE_PORTS = { harness: 8793, gates: 8794 };
+export const PREFERRED_EDGE_PORTS = { harness: 8793, gates: 8794, keys: 8795 };
 /** The name actors dial for the edge, unique to the Tenant's namespace. */
 export function edgeHost(namespace) {
     return `${namespace}.edge.nylorun.internal`;
@@ -113,3 +113,112 @@ function block(entries) {
         END,
     ];
 }
+/**
+ * Keys at Substrate's egress (ADR-142): the keys provider, `sandboxes provider` from the sandboxes
+ * image, runs beside Substrate's egress in its namespace. One per cluster: its config Secret holds
+ * an entry per Tenant, by atespace. Substrate learns it at its own install
+ * (`--credential-provider`); `enable` deploys it and checks that registration, never changing
+ * Substrate's install.
+ */
+export const KEYS_PROVIDER_NAME = "keys.nylorun.dev";
+export const KEYS_PROVIDER = "nylorun-keys-provider";
+export const KEYS_PROVIDER_PORT = 50051;
+/** The address Substrate's egress dials, as `ate-setup`'s `--credential-provider` names it. */
+export const KEYS_PROVIDER_ADDRESS = `${KEYS_PROVIDER}.${SUBSTRATE_NAMESPACE}.svc:${KEYS_PROVIDER_PORT}`;
+/** The flag to install Substrate with, so its egress asks the keys provider. */
+export const KEYS_PROVIDER_FLAG = `--credential-provider='[{"name":"${KEYS_PROVIDER_NAME}","address":"${KEYS_PROVIDER_ADDRESS}"}]'`;
+/** Whether Substrate's egress was installed with the keys provider among its providers. */
+export function keysProviderRegistered(deployment) {
+    const containers = deployment?.spec?.template?.spec
+        ?.containers ?? [];
+    return containers.some((c) => Array.isArray(c.args) && c.args.some((arg) => arg === `--credential-provider-name=${KEYS_PROVIDER_NAME}`));
+}
+const PODCERT = (name, signer) => ({
+    name,
+    projected: {
+        sources: [
+            { podCertificate: { signerName: `${signer}/identity`, keyType: "ECDSAP256", credentialBundlePath: "credential-bundle.pem" } },
+            {
+                clusterTrustBundle: {
+                    signerName: `${signer}/identity`,
+                    labelSelector: { matchLabels: { "podcert.ate.dev/canarying": "live" } },
+                    path: "trust-bundle.pem",
+                },
+            },
+        ],
+    },
+});
+/**
+ * The keys provider: its ServiceAccount, Deployment, Service, a NetworkPolicy that admits only
+ * Substrate's egress, and its config Secret. Mutual TLS as Substrate's reference provider serves
+ * it: its servicedns pod certificate, callers' podidentity certificates.
+ */
+export function keysProviderManifests(image, tenants) {
+    const labels = { app: KEYS_PROVIDER, ...MANAGED };
+    const ns = SUBSTRATE_NAMESPACE;
+    return [
+        { apiVersion: "v1", kind: "ServiceAccount", metadata: { name: KEYS_PROVIDER, namespace: ns, labels: MANAGED } },
+        {
+            apiVersion: "v1",
+            kind: "Secret",
+            metadata: { name: KEYS_PROVIDER, namespace: ns, labels: MANAGED },
+            type: "Opaque",
+            stringData: { "config.json": JSON.stringify({ tenants }) },
+        },
+        {
+            apiVersion: "apps/v1",
+            kind: "Deployment",
+            metadata: { name: KEYS_PROVIDER, namespace: ns, labels },
+            spec: {
+                replicas: 1,
+                selector: { matchLabels: { app: KEYS_PROVIDER } },
+                template: {
+                    metadata: { labels },
+                    spec: {
+                        serviceAccountName: KEYS_PROVIDER,
+                        securityContext: { runAsUser: 65532, runAsGroup: 65532, runAsNonRoot: true },
+                        containers: [
+                            {
+                                name: "provider",
+                                image,
+                                args: ["provider", "--name", KEYS_PROVIDER_NAME, "--listen", `:${KEYS_PROVIDER_PORT}`, "--config", "/etc/nylorun-keys/config.json"],
+                                ports: [
+                                    { name: "grpc", containerPort: KEYS_PROVIDER_PORT },
+                                    { name: "health", containerPort: 9091 },
+                                ],
+                                readinessProbe: { httpGet: { path: "/readyz", port: "health" }, periodSeconds: 10 },
+                                securityContext: { allowPrivilegeEscalation: false, readOnlyRootFilesystem: true, capabilities: { drop: ["ALL"] } },
+                                volumeMounts: [
+                                    { name: "config", mountPath: "/etc/nylorun-keys", readOnly: true },
+                                    { name: "servicedns", mountPath: "/run/servicedns.podcert.ate.dev", readOnly: true },
+                                    { name: "podidentity", mountPath: "/run/podidentity.podcert.ate.dev", readOnly: true },
+                                ],
+                            },
+                        ],
+                        volumes: [
+                            { name: "config", secret: { secretName: KEYS_PROVIDER } },
+                            PODCERT("servicedns", "servicedns.podcert.ate.dev"),
+                            PODCERT("podidentity", "podidentity.podcert.ate.dev"),
+                        ],
+                    },
+                },
+            },
+        },
+        {
+            apiVersion: "v1",
+            kind: "Service",
+            metadata: { name: KEYS_PROVIDER, namespace: ns, labels: MANAGED },
+            spec: { type: "ClusterIP", selector: { app: KEYS_PROVIDER }, ports: [{ name: "grpc", port: KEYS_PROVIDER_PORT, targetPort: "grpc", protocol: "TCP" }] },
+        },
+        {
+            apiVersion: "networking.k8s.io/v1",
+            kind: "NetworkPolicy",
+            metadata: { name: KEYS_PROVIDER, namespace: ns, labels: MANAGED },
+            spec: {
+                podSelector: { matchLabels: { app: KEYS_PROVIDER } },
+                policyTypes: ["Ingress"],
+                ingress: [{ from: [{ podSelector: { matchLabels: { app: "atenet-egress" } } }], ports: [{ protocol: "TCP", port: KEYS_PROVIDER_PORT }] }],
+            },
+        },
+    ];
+}

package/dist/stack/compose-file.d.ts

@@ -76,6 +76,8 @@ export declare function renderComposeFile(project: string, name: string, options
     sandboxes?: true;
     /** The sandboxes container serves the edge (backend substrate, ADR-138). */
     sandboxEdge?: true;
+    /** The edge also serves the keys provider's port (ADR-142). */
+    sandboxKeys?: true;
     harness?: "remote" | "in-process";
     restateUi?: true;
     identity?: true;

package/dist/stack/compose-file.js

@@ -327,7 +327,7 @@ ${healthcheck("runtime")}    restart: unless-stopped
     healthcheck: # /healthz needs no session; Host studio:3000 is accepted
       test: ["CMD", "node", "-e", "require('http').get({port:3000,path:'/healthz',headers:{host:'studio:3000'}},r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
 ${healthcheck("studio")}    restart: unless-stopped
-${remote ? harnessService(project) : ""}${sandboxes ? sandboxesService(project, options.sandboxEdge === true) : ""}
+${remote ? harnessService(project) : ""}${sandboxes ? sandboxesService(project, options.sandboxEdge === true, options.sandboxKeys === true) : ""}
 networks:
   default:
     name: ${project}
@@ -421,10 +421,19 @@ const SANDBOXES_EDGE_PORTS = `
     ports:
       - "\${NYLORUN_SANDBOX_BIND:?run nylorun local sandbox enable}:\${NYLORUN_SANDBOX_EDGE_HARNESS_PORT:?run nylorun local sandbox enable}:8443" # the edge: the Harness API, for actors
       - "\${NYLORUN_SANDBOX_BIND:?run nylorun local sandbox enable}:\${NYLORUN_SANDBOX_EDGE_GATES_PORT:?run nylorun local sandbox enable}:8444" # the edge: the gates, for actors`;
+/**
+ * The edge's keys port (ADR-142): Substrate's keys provider reaches egress-gate's decide route on
+ * gateway:4200 through it. No actor's egress policy allows it.
+ */
+const SANDBOXES_EDGE_KEYS_PORT = `
+      - "\${NYLORUN_SANDBOX_BIND:?run nylorun local sandbox enable}:\${NYLORUN_SANDBOX_EDGE_KEYS_PORT:?run nylorun local sandbox enable}:8445" # the edge: egress-gate's decide route, for the keys provider`;
 /** egress-gate (F7.2): pods' CONNECT proxy in the gateway. */
 const SANDBOXES_GATEWAY_ENV = `
       # egress-gate: the only way out of a sandbox pod, to the hosts its spec allows.
-      NYLORUN_EGRESS_LISTEN_PORT: "4200"`;
+      NYLORUN_EGRESS_LISTEN_PORT: "4200"
+      # On Agent Substrate, the keys provider's token for egress-gate's decide route (ADR-142).
+      # Empty: the route is off.
+      NYLORUN_EGRESS_KEYS_TOKEN: \${NYLORUN_EGRESS_KEYS_TOKEN:-}`;
 /** Empty and read-only over the cluster credentials: only the sandboxes service reads them. */
 const SANDBOXES_RUNTIME_MOUNT = `
       - type: tmpfs
@@ -436,7 +445,7 @@ const SANDBOXES_RUNTIME_MOUNT = `
  * (NYLORUN_SANDBOX_*_PORT in .env), the Harness API's, the gates' and egress-gate's, are
  * published by the runtime and the gateway (above).
  */
-function sandboxesService(project, edge) {
+function sandboxesService(project, edge, keys) {
     return `
   sandboxes: # the sandboxes driver; the only holder of the cluster credentials; not published${edge ? ", but for its edge" : ""}
     image: \${NYLORUN_SANDBOXES_IMAGE:?run nylorun local sandbox enable}
@@ -452,7 +461,7 @@ function sandboxesService(project, edge) {
     volumes:
       # cluster.json (API server, CA, namespace) and the ServiceAccount token, read-only.
       - \${NYLORUN_HOST_ROOT:?run nylorun start}/sandboxes:/run/nylorun/sandboxes:ro
-    networks: [default] # the cluster's API server, through host.docker.internal${edge ? SANDBOXES_EDGE_PORTS : ""}
+    networks: [default] # the cluster's API server, through host.docker.internal${edge ? SANDBOXES_EDGE_PORTS : ""}${edge && keys ? SANDBOXES_EDGE_KEYS_PORT : ""}
     healthcheck: # /ready: informers synced and the API server answers
       test: ["CMD", "/sandboxes", "healthcheck"]
 ${healthcheck("sandboxes")}    restart: unless-stopped

package/dist/stack/env-file.d.ts

@@ -80,6 +80,13 @@ export interface SandboxStackEnv {
      */
     edgeHarnessPort?: number;
     edgeGatesPort?: number;
+    /**
+     * With the Substrate backend: the edge's keys port, where the keys provider reaches
+     * egress-gate's decide route, and the token it presents there (ADR-142).
+     */
+    edgeKeysPort?: number;
+    /** NYLORUN_EGRESS_KEYS_TOKEN, 32 bytes as hex. */
+    keysToken?: string;
 }
 export type HarnessMode = "remote" | "in-process";
 export declare function renderEnvFile(env: StackEnv): string;

package/dist/stack/env-file.js

@@ -15,6 +15,8 @@ const SANDBOX_KEYS = {
     bind: "NYLORUN_SANDBOX_BIND",
     edgeHarnessPort: "NYLORUN_SANDBOX_EDGE_HARNESS_PORT",
     edgeGatesPort: "NYLORUN_SANDBOX_EDGE_GATES_PORT",
+    edgeKeysPort: "NYLORUN_SANDBOX_EDGE_KEYS_PORT",
+    keysToken: "NYLORUN_EGRESS_KEYS_TOKEN",
 };
 const KEYS = {
     runtimePort: "NYLORUN_PORT",
@@ -129,6 +131,14 @@ export function renderEnvFile(env) {
                         sandboxLine("edgeGatesPort"),
                     ]
                     : []),
+                ...(sandboxes.edgeKeysPort && sandboxes.keysToken
+                    ? [
+                        "# Keys at Substrate's egress (ADR-142): the edge's port for the keys provider,",
+                        "# and the token it presents to egress-gate's decide route.",
+                        sandboxLine("edgeKeysPort"),
+                        sandboxLine("keysToken"),
+                    ]
+                    : []),
                 "",
             ]
             : []),
@@ -172,9 +182,12 @@ function parseSandboxes(values) {
         return undefined;
     const edgeHarnessPort = port(values.get(SANDBOX_KEYS.edgeHarnessPort));
     const edgeGatesPort = port(values.get(SANDBOX_KEYS.edgeGatesPort));
+    const edgeKeysPort = port(values.get(SANDBOX_KEYS.edgeKeysPort));
+    const keysToken = values.get(SANDBOX_KEYS.keysToken);
     return {
         token, image, harnessPort, gatesPort, egressPort, hostAddress, bind,
         ...(edgeHarnessPort && edgeGatesPort ? { edgeHarnessPort, edgeGatesPort } : {}),
+        ...(edgeKeysPort && keysToken && /^[0-9a-f]{64,}$/i.test(keysToken) ? { edgeKeysPort, keysToken } : {}),
     };
 }
 export function parsePersisted(text) {

package/dist/stack/prepare.js

@@ -103,6 +103,7 @@ export async function prepareStack(input) {
         harness: env.harness,
         ...(env.sandboxes ? { sandboxes: true } : {}),
         ...(env.sandboxes?.edgeHarnessPort ? { sandboxEdge: true } : {}),
+        ...(env.sandboxes?.edgeHarnessPort && env.sandboxes.edgeKeysPort ? { sandboxKeys: true } : {}),
         ...(env.restateUi ? { restateUi: true } : {}),
         // The trusted issuers, when the operator wrote an identity file; a change takes a restart.
         ...(existsSync(paths.identity) ? { identity: true } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.29.8-beta",
+  "version": "0.30.0-beta",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Set up and run local Nylorun Tenants (Runtime and Studio) with Docker Compose, and act on a Tenant through its Runtime and Management APIs",
@@ -46,7 +46,7 @@
     "nylo": "dist/nylo.js"
   },
   "nylorun": {
-    "runtime": "0.48.1-beta",
+    "runtime": "0.49.0-beta",
     "studio": "0.35.11-beta"
   }
 }