@wardby/cli 0.5.3 → 0.7.0

package/dist/native-worker/kubernetes-isolation.js

@@ -0,0 +1,218 @@
+/**
+ * Kubernetes objects for one sandbox-mode native run (docs/native-sandbox.md), as pure builders —
+ * the launcher creates exactly these and attests what the API server stored against them. One pod
+ * per run, with no service-account token, a read-only non-root container holding no credentials,
+ * its WorkerInput (capability included) mounted read-only from a per-run Secret, and a
+ * NetworkPolicy whose only egress is the native gateway's port. Names carry a hash of the run id,
+ * never the id itself.
+ */
+import { createHash } from "node:crypto";
+import { isRepositoryDigest } from "../providers/jobs/docker-isolation.js";
+import { CLOUD_METADATA_PROBES } from "../providers/jobs/metadata-probes.js";
+import { conformResources, GVISOR_RUNTIME_CLASS, platformProfile, } from "../providers/jobs/kubernetes-platform.js";
+import { NATIVE_GATEWAY_DENY_PORT, NATIVE_GATEWAY_PORT, NATIVE_WORKER_TMP_MB, NATIVE_WORKER_UID, nativeWarmWorkerName, } from "./docker-isolation.js";
+export { nativeWarmWorkerName };
+import { WARM_INPUT_FILE } from "./warm-delivery.js";
+export const NATIVE_RUN_COMPONENT_LABEL = { "wardby.io/component": "native-run" };
+export const NATIVE_GATEWAY_POD_LABEL = { "app.kubernetes.io/name": "wardby-native-gateway" };
+const MANAGED_BY_LABEL = { "app.kubernetes.io/managed-by": "wardby" };
+export const NATIVE_RUN_SHA_LABEL = "wardby.io/run-sha256";
+/** The label selector listing every native run pod (the janitor's listing). */
+export const NATIVE_RUN_SELECTOR = "wardby.io/component=native-run";
+export const NATIVE_WORKER_CONTAINER = "worker";
+export const NATIVE_INPUT_MOUNT = "/run/wardby/input";
+export const NATIVE_INPUT_KEY = "input.json";
+export const NATIVE_INPUT_FILE = `${NATIVE_INPUT_MOUNT}/${NATIVE_INPUT_KEY}`;
+/** Room for node's own writes besides /tmp; the root filesystem is read-only. */
+const EPHEMERAL_STORAGE_MI = 128;
+export function nativeKubernetesNames(runId) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,199}$/.test(runId))
+        throw new Error("native_sandbox_invalid_run_id");
+    const digest = createHash("sha256").update(runId).digest("hex");
+    const base = `wardby-native-${digest.slice(0, 20)}`;
+    return { runSha: digest.slice(0, 40), pod: base, policy: base, secret: `${base}-input` };
+}
+export function nativeRunLabels(runId) {
+    return {
+        ...MANAGED_BY_LABEL,
+        ...NATIVE_RUN_COMPONENT_LABEL,
+        [NATIVE_RUN_SHA_LABEL]: nativeKubernetesNames(runId).runSha,
+    };
+}
+export function buildNativeInputSecret(input, namespace) {
+    const names = nativeKubernetesNames(input.runId);
+    return {
+        apiVersion: "v1",
+        kind: "Secret",
+        metadata: { name: names.secret, namespace, labels: nativeRunLabels(input.runId) },
+        type: "Opaque",
+        immutable: true,
+        stringData: { [NATIVE_INPUT_KEY]: JSON.stringify(input) },
+    };
+}
+export const NATIVE_SANDBOX_PLATFORM_ERROR = "native_sandbox_platform_unsupported";
+export function buildNativeRunPod(options) {
+    const names = nativeKubernetesNames(options.runId);
+    return buildNativePod(options, {
+        name: names.pod,
+        labels: nativeRunLabels(options.runId),
+        env: [{ name: "NATIVE_WORKER_INPUT_FILE", value: NATIVE_INPUT_FILE }],
+        input: { secretName: names.secret },
+    });
+}
+/** The labels of every warm pool pod: still a native-run pod (the gateway admits it), never a run's. */
+export const NATIVE_WARM_POOL_LABEL = { "wardby.io/pool": "warm" };
+export const NATIVE_WARM_TOKEN_LABEL = "wardby.io/warm-worker";
+/** The label selector listing every warm pool pod. */
+export const NATIVE_WARM_SELECTOR = "wardby.io/component=native-run,wardby.io/pool=warm";
+export function nativeWarmLabels(token) {
+    return {
+        ...MANAGED_BY_LABEL,
+        ...NATIVE_RUN_COMPONENT_LABEL,
+        ...NATIVE_WARM_POOL_LABEL,
+        [NATIVE_WARM_TOKEN_LABEL]: token,
+    };
+}
+/** A warm pool pod (native sandbox phase 6): no input yet; it waits for one delivered by exec. */
+export function buildNativeWarmPod(options) {
+    return buildNativePod(options, {
+        name: nativeWarmWorkerName(options.token),
+        labels: nativeWarmLabels(options.token),
+        env: [
+            { name: "NATIVE_WORKER_INPUT_FILE", value: WARM_INPUT_FILE },
+            { name: "NATIVE_WORKER_INPUT_WAIT_MS", value: String(Math.floor(options.waitMs)) },
+        ],
+    });
+}
+function buildNativePod(options, identity) {
+    const { namespace, image, limits } = options;
+    if (!isRepositoryDigest(image)) {
+        throw new Error("native_sandbox_image_not_pinned: a cluster pulls by registry digest (repo@sha256:...).");
+    }
+    const profile = platformProfile(options.platform ?? "generic");
+    if (profile.requiresGvisor && options.runtimeClassName !== GVISOR_RUNTIME_CLASS) {
+        throw new Error(`${NATIVE_SANDBOX_PLATFORM_ERROR}: platform ${profile.name} runs native workers only under the ${GVISOR_RUNTIME_CLASS} RuntimeClass.`);
+    }
+    // Already legal on the platform, so admission rewrites nothing (attestation compares resources).
+    // Native pods always declare ephemeral storage, which a generic profile would otherwise drop.
+    const conformed = conformResources(profile, {
+        cpuMillicores: Math.round(limits.cpus * 1000),
+        memoryMib: limits.memoryMb,
+        ephemeralStorageMib: EPHEMERAL_STORAGE_MI,
+    });
+    const resources = { ...conformed.requests, "ephemeral-storage": `${EPHEMERAL_STORAGE_MI}Mi` };
+    return {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: { name: identity.name, namespace, labels: identity.labels },
+        spec: {
+            restartPolicy: "Never",
+            activeDeadlineSeconds: Math.max(1, Math.floor(options.activeDeadlineSeconds)),
+            automountServiceAccountToken: false,
+            enableServiceLinks: false,
+            hostNetwork: false,
+            hostPID: false,
+            hostIPC: false,
+            terminationGracePeriodSeconds: 5,
+            ...(options.runtimeClassName ? { runtimeClassName: options.runtimeClassName } : {}),
+            ...(options.priorityClassName ? { priorityClassName: options.priorityClassName } : {}),
+            securityContext: {
+                runAsNonRoot: true,
+                runAsUser: NATIVE_WORKER_UID,
+                runAsGroup: NATIVE_WORKER_UID,
+                // Secret files mount root-owned: group ownership lets the non-root worker read its input.
+                fsGroup: NATIVE_WORKER_UID,
+                seccompProfile: { type: "RuntimeDefault" },
+            },
+            containers: [
+                {
+                    name: NATIVE_WORKER_CONTAINER,
+                    image,
+                    imagePullPolicy: "IfNotPresent",
+                    env: identity.env,
+                    resources: { requests: { ...resources }, limits: { ...resources } },
+                    securityContext: {
+                        allowPrivilegeEscalation: false,
+                        privileged: false,
+                        readOnlyRootFilesystem: true,
+                        runAsNonRoot: true,
+                        capabilities: { drop: ["ALL"] },
+                    },
+                    volumeMounts: [
+                        ...(identity.input ? [{ name: "input", mountPath: NATIVE_INPUT_MOUNT, readOnly: true }] : []),
+                        { name: "tmp", mountPath: "/tmp" },
+                    ],
+                },
+            ],
+            volumes: [
+                ...(identity.input
+                    ? [{ name: "input", secret: { secretName: identity.input.secretName, defaultMode: 0o440 } }]
+                    : []),
+                { name: "tmp", emptyDir: { sizeLimit: `${NATIVE_WORKER_TMP_MB}Mi` } },
+            ],
+        },
+    };
+}
+/** Ingress: none. Egress: the native gateway's pods, on the gateway port only. */
+export function buildNativeRunNetworkPolicy(runId, namespace) {
+    return buildNativePolicy(nativeKubernetesNames(runId).policy, namespace, nativeRunLabels(runId));
+}
+/** A warm pool pod's policy: the same egress, selecting the pod by its token. */
+export function buildNativeWarmNetworkPolicy(token, namespace) {
+    return buildNativePolicy(nativeWarmWorkerName(token), namespace, nativeWarmLabels(token));
+}
+function buildNativePolicy(name, namespace, labels) {
+    return {
+        apiVersion: "networking.k8s.io/v1",
+        kind: "NetworkPolicy",
+        metadata: { name, namespace, labels },
+        spec: {
+            podSelector: { matchLabels: labels },
+            policyTypes: ["Ingress", "Egress"],
+            ingress: [],
+            egress: [
+                {
+                    to: [{ podSelector: { matchLabels: { ...NATIVE_GATEWAY_POD_LABEL } } }],
+                    ports: [{ protocol: "TCP", port: NATIVE_GATEWAY_PORT }],
+                },
+            ],
+        },
+    };
+}
+/** Exit codes of the in-pod enforcement probe. */
+export const NATIVE_PROBE = { proven: 0, gatewayUnreachable: 3, denyReachable: 4, outsideReachable: 5 };
+/** Addresses a worker must not reach: the internet, and the cloud metadata endpoints (node and workload credentials). */
+export const NATIVE_PROBE_OUTSIDE = [
+    { host: "1.1.1.1", port: 443 },
+    ...CLOUD_METADATA_PROBES,
+];
+/**
+ * Run inside the worker container (exec): proves the pod's egress is the gateway port and nothing
+ * else — the gateway answers, while its deny port (same address, another port) and every outside
+ * address do not. A connection that is refused or times out both count as unreachable.
+ */
+export function nativeEnforcementProbe(gatewayHost, outside = NATIVE_PROBE_OUTSIDE) {
+    const script = [
+        'const net = require("node:net");',
+        "const reach = (host, port) => new Promise((done) => {",
+        "  const s = net.connect({ host, port, timeout: 3000 });",
+        "  s.once('connect', () => { s.destroy(); done(true); });",
+        "  s.once('error', () => done(false));",
+        "  s.once('timeout', () => { s.destroy(); done(false); });",
+        "});",
+        "(async () => {",
+        `  if (!(await reach(${JSON.stringify(gatewayHost)}, ${NATIVE_GATEWAY_PORT}))) process.exit(${NATIVE_PROBE.gatewayUnreachable});`,
+        // The deny port and every outside address run concurrently (each dropped connect waits the full
+        // timeout, so serial probing would eat the exec budget); the verdicts are still read in a fixed
+        // order, so when several fail the exit code is deterministic: deny port first, then outside.
+        `  const deny = reach(${JSON.stringify(gatewayHost)}, ${NATIVE_GATEWAY_DENY_PORT});`,
+        "  const outside = Promise.all([",
+        ...outside.map((o) => `    reach(${JSON.stringify(o.host)}, ${o.port}),`),
+        "  ]);",
+        `  if (await deny) process.exit(${NATIVE_PROBE.denyReachable});`,
+        `  if ((await outside).some(Boolean)) process.exit(${NATIVE_PROBE.outsideReachable});`,
+        `  process.exit(${NATIVE_PROBE.proven});`,
+        "})();",
+    ].join("\n");
+    return ["node", "-e", script];
+}

package/dist/native-worker/kubernetes-launcher.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Launches, watches, stops, and removes native sandbox workers as Kubernetes pods
+ * (docs/native-sandbox.md), from the builders in kubernetes-isolation.ts. Like the Docker
+ * launcher it keeps no state of its own: names derive from the run id, state comes from the pod,
+ * and sessions live in Postgres, so any replica can act on any run.
+ *
+ * A pod's NetworkPolicy takes effect a few seconds after the pod starts (the CNI programs it), so
+ * the session is created not ready (`networkReadyAtLaunch = false`): the gateway refuses the
+ * worker until this launcher has read back the pod and policy it created, then proven from inside
+ * the pod that the gateway port answers while the gateway's deny port and an outside address do
+ * not — and only then marks the session ready.
+ */
+import { type Power } from "../core/power.js";
+import { type KubernetesApi } from "../providers/jobs/kubernetes-api.js";
+import type { KubernetesPlatform } from "../providers/jobs/kubernetes-platform.js";
+import { type NativeWorkerLimits } from "./docker-isolation.js";
+import { type NativeWorkerState } from "./docker-launcher.js";
+import { type WorkerHandle, type WorkerLaunchOptions } from "./launch.js";
+import type { WorkerInput } from "./protocol.js";
+import type { ManagedWorkerLauncher } from "./sandbox-executor.js";
+import { type WarmWorkerLauncher } from "./warm-pool.js";
+export declare const NATIVE_SANDBOX_NETWORK_UNENFORCED = "native_sandbox_network_unenforced";
+export declare const NATIVE_SANDBOX_ISOLATION_MISMATCH = "native_sandbox_isolation_mismatch";
+export declare const NATIVE_SANDBOX_CAPACITY = "native_sandbox_capacity";
+/** The API server's refusal of a pod the namespace's ResourceQuota has no room for (403 "exceeded quota"). */
+export declare function isQuotaRejection(err: unknown): boolean;
+export interface KubernetesNativeWorkerLauncherOptions {
+    api: KubernetesApi;
+    namespace: string;
+    image: string;
+    limits: NativeWorkerLimits;
+    /** The native gateway's Service, in the same namespace (NetworkPolicy selects its pods there). */
+    gatewayService: string;
+    runtimeClassName?: string;
+    /** KUBERNETES_PLATFORM: the admission rules native pods are conformed to. */
+    platform?: KubernetesPlatform;
+    /** KUBERNETES_RUN_PRIORITY_CLASS. */
+    priorityClassName?: string;
+    /** NATIVE_GATEWAY_URL: dial this instead of the Service's ClusterIP (its host is also what the probe checks). */
+    gatewayUrl?: string;
+    /** Called once a pod's isolation is proven; the executor marks the run's session ready. */
+    onNetworkProven: (runId: string) => Promise<void>;
+    /** The pod's hard lifetime (its session's deadline). */
+    deadlineSeconds: number;
+    readyTimeoutMs?: number;
+    enforcementTimeoutMs?: number;
+    pollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Low-power mode: wakes the (possibly scaled-to-zero) native gateway before a launch. Default `DISABLED_POWER`. */
+    power?: Power;
+    /** The bound on a failed worker's diagnostic (log and secret reads) before its exit is reported. Default WORKER_TAIL_TIMEOUT_MS. */
+    diagnosticTimeoutMs?: number;
+}
+/**
+ * An object as the API server would store it, for comparison: keys sorted, and missing, undefined,
+ * and empty arrays alike (it drops an empty `ingress: []`, which `policyTypes` already makes deny-all).
+ */
+export declare function canonical(value: unknown): unknown;
+export declare class KubernetesNativeWorkerLauncher implements ManagedWorkerLauncher, WarmWorkerLauncher {
+    private readonly options;
+    readonly networkReadyAtLaunch = false;
+    private gatewayHost;
+    private readonly power;
+    constructor(options: KubernetesNativeWorkerLauncherOptions);
+    private get api();
+    private get ns();
+    private sleep;
+    /** The gateway Service's ClusterIP: workers dial an address, so they need no DNS egress. */
+    private resolveGatewayHost;
+    resolveGatewayUrl(): Promise<string>;
+    private createIfMissing;
+    launch(input: WorkerInput, launchOptions?: WorkerLaunchOptions): Promise<WorkerHandle>;
+    /** A non-zero exit, with the tail of the worker's log (bounded and redacted: workerTailFields), as the Docker launcher logs it. */
+    private logFailedExit;
+    /**
+     * Policy first, so the pod never exists without it; then the pod; then attest and prove it. A
+     * quota rejection becomes native_sandbox_capacity. Any failure removes what was made.
+     */
+    private createIsolated;
+    /** What the API server stored must still be what was built: an admission change voids the run. */
+    private attest;
+    private matches;
+    /** Waits for the pod to run, then proves its egress from inside it (bounded). */
+    private proveIsolation;
+    handle(runId: string): WorkerHandle;
+    private handleByName;
+    inspect(runId: string): Promise<NativeWorkerState>;
+    private inspectByName;
+    kill(runId: string): Promise<void>;
+    remove(runId: string): Promise<void>;
+    listWorkers(): Promise<{
+        name: string;
+        runHash: string;
+    }[]>;
+    removeByWorkerName(name: string): Promise<void>;
+    private warmPod;
+    warmSpecHash(waitMs: number): string;
+    startWarm(token: string, waitMs: number): Promise<void>;
+    reattestWarm(token: string, waitMs: number): Promise<boolean>;
+    deliver(token: string, input: WorkerInput): Promise<void>;
+    warmHandle(token: string): WorkerHandle;
+    inspectWarm(token: string): Promise<NativeWorkerState>;
+    killWarm(token: string): Promise<void>;
+    removeWarm(token: string): Promise<void>;
+    listWarm(): Promise<string[]>;
+}