@nosana/node 1.1.63-rc → 1.1.64-rc

package/dist/src/NodeManager/provider/containerOrchestration/docker/createDockerRunOptions.js

@@ -10,7 +10,7 @@ function parseRestartPolicy(restart_policy) {
     }
     return undefined;
 }
-export function createDockerRunOptions(image, { name, cmd, gpu, volumes, env, work_dir, entrypoint, aliases, restart_policy, runtime, bind_network_to_container }, gpuOption) {
+export function createDockerRunOptions(image, { name, cmd, gpu, volumes, env, work_dir, entrypoint, aliases, restart_policy, runtime, bind_network_to_container, labels, security, }, gpuOption) {
     const devices = [];
     if (gpu) {
         devices.push({
@@ -37,6 +37,7 @@ export function createDockerRunOptions(image, { name, cmd, gpu, volumes, env, wo
         Image: image,
         WorkingDir: work_dir,
         Entrypoint: entrypoint,
+        Labels: labels,
         ...(!bind_network_to_container ? {
             NetworkingConfig: {
                 EndpointsConfig: {
@@ -51,10 +52,10 @@ export function createDockerRunOptions(image, { name, cmd, gpu, volumes, env, wo
                     'host.containers.internal:8.8.8.8',
                 ]
             } : {}),
-            Mounts: volumes?.map(({ dest, name, readonly }) => ({
+            Mounts: volumes?.map(({ dest, name, readonly, type }) => ({
                 Target: dest,
                 Source: name,
-                Type: 'volume',
+                Type: type ?? 'volume',
                 ReadOnly: readonly || false,
             })),
             NetworkMode: bind_network_to_container ? bind_network_to_container : 'bridge',
@@ -70,6 +71,8 @@ export function createDockerRunOptions(image, { name, cmd, gpu, volumes, env, wo
             } : {}),
             RestartPolicy: parseRestartPolicy(restart_policy),
             ...(runtime === 'SEV-SNP' ? { Runtime: runtime } : {}),
+            ...(security?.capDrop ? { CapDrop: security.capDrop } : {}),
+            ...(security?.pidsLimit ? { PidsLimit: security.pidsLimit } : {}),
         },
     };
 }

package/dist/src/NodeManager/provider/containerOrchestration/docker/index.d.ts

@@ -16,8 +16,12 @@ export declare class DockerContainerOrchestration implements ContainerOrchestrat
     checkCustomRuntimeAvailability(runtime: string): Promise<boolean>;
     getContainerByName(name: string): Promise<Container | undefined>;
     getContainersByName(names: string[]): Promise<Container[]>;
+    getContainersByLabels(labels: string[], options?: {
+        all?: boolean;
+    }): Promise<Container[]>;
+    resolveHostPath(path: string): Promise<string>;
     getConnection(): DockerExtended;
-    pullImage(image: string, authorisation?: DockerAuth, controller?: AbortController): Promise<void>;
+    pullImage(image: string, authorisation?: DockerAuth, controller?: AbortController, force?: boolean): Promise<void>;
     hasImage(image: string): Promise<boolean>;
     getImage(image: string): Promise<Image>;
     listImages(): Promise<ImageInfo[]>;

package/dist/src/NodeManager/provider/containerOrchestration/docker/index.js

@@ -73,14 +73,50 @@ export class DockerContainerOrchestration {
             throw new Error('could not get containers');
         }
     }
+    async getContainersByLabels(labels, options = {}) {
+        try {
+            const containers = await this.docker.listContainers({
+                all: options.all ?? false,
+                filters: {
+                    label: labels,
+                    ...(options.all ? {} : { status: ['running'] }),
+                },
+            });
+            return containers.map((info) => this.docker.getContainer(info.Id));
+        }
+        catch (_) {
+            throw new Error('could not get containers');
+        }
+    }
+    async resolveHostPath(path) {
+        try {
+            // A container's hostname is its id unless overridden, so this finds the
+            // node's own container; on a bare host the lookup fails and the path is
+            // already a host path.
+            const self = await this.docker.getContainer(os.hostname()).inspect();
+            const mount = self.Mounts?.find((m) => path === m.Destination || path.startsWith(`${m.Destination}/`));
+            if (!mount?.Source)
+                return path;
+            return mount.Source + path.slice(mount.Destination.length);
+        }
+        catch (_) {
+            return path;
+        }
+    }
     getConnection() {
         return this.docker;
     }
-    async pullImage(image, authorisation, controller) {
+    async pullImage(image, authorisation, controller, force = false) {
         try {
             if (controller?.signal.aborted)
                 throw controller.signal.reason;
-            if (await this.docker.hasImage(image))
+            // A cached image is reused unless the caller forces a pull. `force` is set
+            // for a private image a different project owns: the pull then re-verifies
+            // this project's credentials against the registry (reusing cached layers)
+            // and fails a job that cannot authenticate, rather than handing it a copy
+            // another project pulled. The owning project and public images reuse the
+            // cache with no registry round-trip, so a cached node stays usable offline.
+            if (!force && (await this.docker.hasImage(image)))
                 return;
             await this.docker.promisePull(image, controller ?? new AbortController(), authorisation);
         }
@@ -236,6 +272,8 @@ export class DockerContainerOrchestration {
                 ...createDockerRunOptions(image, args, this.gpu),
             });
             try {
+                if (args.beforeStart)
+                    await args.beforeStart(container);
                 await container.start();
             }
             catch (error) {

package/dist/src/NodeManager/provider/containerOrchestration/interface.d.ts

@@ -13,7 +13,9 @@ export type RunContainerArgs = {
         dest: string;
         name: string;
         readonly?: boolean;
+        type?: 'volume' | 'bind';
     }>;
+    labels?: Record<string, string>;
     env?: {
         [key: string]: string;
     };
@@ -23,11 +25,23 @@ export type RunContainerArgs = {
     aliases?: string[] | undefined;
     runtime?: string;
     bind_network_to_container?: string;
+    security?: {
+        capDrop?: string[];
+        pidsLimit?: number;
+    };
+    /**
+     * Runs between create and start with the container handle, so files can be
+     * put in place before the entrypoint runs. A failure removes the created
+     * container and fails the run.
+     */
+    beforeStart?: (container: Container) => Promise<void>;
 };
 export interface ContainerOrchestrationInterface {
     teeRuntime?: string;
+    name: string;
+    host: string;
     getConnection(): any;
-    pullImage(image: string, auth?: DockerAuth, controller?: AbortController): Promise<void>;
+    pullImage(image: string, auth?: DockerAuth, controller?: AbortController, force?: boolean): Promise<void>;
     hasImage(image: string): Promise<boolean>;
     getImage(image: string): Promise<Image>;
     listImages(): Promise<ImageInfo[]>;
@@ -43,6 +57,19 @@ export interface ContainerOrchestrationInterface {
     deleteVolume(name: string, controller?: AbortController): Promise<void>;
     getContainerByName(name: string): Promise<Container | undefined>;
     getContainersByName(names: string[]): Promise<Container[]>;
+    /**
+     * Containers matching every filter, each `key=value` or a bare `key` that
+     * only has to be present. Running ones unless `all` is set.
+     */
+    getContainersByLabels(labels: string[], options?: {
+        all?: boolean;
+    }): Promise<Container[]>;
+    /**
+     * The host-side path behind a path the node sees. The node may run in a
+     * container with the runtime socket mounted elsewhere, and the daemon
+     * resolves bind sources on the host.
+     */
+    resolveHostPath(path: string): Promise<string>;
     runContainer(args: ContainerCreateOptions, controller?: AbortController): Promise<Container>;
     runFlowContainer(image: string, args: RunContainerArgs): Promise<Container>;
     stopContainer(id: string, controller?: AbortController): Promise<void>;

package/dist/src/NodeManager/provider/containerOrchestration/labels.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Labels the node stamps on the containers it runs, so they can be found
+ * again through the runtime instead of by name.
+ */
+export declare const JOB_LABEL = "com.nosana.job";
+export declare const OP_LABEL = "com.nosana.op";
+export declare const OP_INDEX_LABEL = "com.nosana.opIndex";
+export declare const SERVICE_LABEL = "com.nosana.service";
+/** Job and operation ids become container names and label values. */
+export declare function isSafeIdentifier(value: string): boolean;

package/dist/src/NodeManager/provider/containerOrchestration/labels.js

@@ -0,0 +1,12 @@
+/**
+ * Labels the node stamps on the containers it runs, so they can be found
+ * again through the runtime instead of by name.
+ */
+export const JOB_LABEL = 'com.nosana.job';
+export const OP_LABEL = 'com.nosana.op';
+export const OP_INDEX_LABEL = 'com.nosana.opIndex';
+export const SERVICE_LABEL = 'com.nosana.service';
+/** Job and operation ids become container names and label values. */
+export function isSafeIdentifier(value) {
+    return /^[A-Za-z0-9._:-]+$/.test(value);
+}

package/dist/src/NodeManager/provider/containerOrchestration/podman/index.js

@@ -59,20 +59,25 @@ export class PodmanContainerOrchestration extends DockerContainerOrchestration {
                 });
                 if (create.status === 201) {
                     const createResult = await create.json();
-                    const start = await this.libPodAPICall(`/containers/${createResult.Id}/start`, {
-                        method: 'POST',
-                    });
-                    if (start.status === 204) {
-                        const container = this.docker.getContainer(createResult.Id);
-                        return container;
+                    const container = this.docker.getContainer(createResult.Id);
+                    try {
+                        if (args.beforeStart)
+                            await args.beforeStart(container);
+                        const start = await this.libPodAPICall(`/containers/${createResult.Id}/start`, {
+                            method: 'POST',
+                        });
+                        if (start.status !== 204) {
+                            const message = (await start.json()).message;
+                            throw new Error('Cannot start container: ' + message);
+                        }
                     }
-                    else {
-                        const message = (await start.json()).message;
+                    catch (error) {
                         // A created container holds its name whether it ran or not, and
                         // nothing else can take that name until it is gone.
                         await this.stopAndDeleteContainer(createResult.Id);
-                        throw new Error('Cannot start container: ' + message);
+                        throw error;
                     }
+                    return container;
                 }
                 error = await create.json();
                 if (error.message !== `${image}: image not known`)

package/dist/src/NodeManager/provider/containerOrchestration/podman/utils/createPodmanRunOptions.d.ts

@@ -7,6 +7,12 @@ import type { RunContainerArgs } from '../../interface.js';
  * @returns
  */
 export declare function createPodmanRunOptions(image: string, args: RunContainerArgs, gpuOption: string): {
+    resource_limits?: {
+        pids: {
+            limit: number;
+        };
+    } | undefined;
+    cap_drop?: string[] | undefined;
     hostadd: string[];
     netns: {
         nsmode: string;
@@ -32,12 +38,25 @@ export declare function createPodmanRunOptions(image: string, args: RunContainer
     image: string;
     name: string | undefined;
     command: string[] | undefined;
+    labels: Record<string, string> | undefined;
     volumes: {
         dest: string;
         name: string;
         Options: string[];
     }[] | undefined;
+    mounts: {
+        type: string;
+        source: string;
+        destination: string;
+        options: string[];
+    }[] | undefined;
 } | {
+    resource_limits?: {
+        pids: {
+            limit: number;
+        };
+    } | undefined;
+    cap_drop?: string[] | undefined;
     hostadd: string[];
     netns: {
         nsmode: string;
@@ -64,12 +83,25 @@ export declare function createPodmanRunOptions(image: string, args: RunContainer
     image: string;
     name: string | undefined;
     command: string[] | undefined;
+    labels: Record<string, string> | undefined;
     volumes: {
         dest: string;
         name: string;
         Options: string[];
     }[] | undefined;
+    mounts: {
+        type: string;
+        source: string;
+        destination: string;
+        options: string[];
+    }[] | undefined;
 } | {
+    resource_limits?: {
+        pids: {
+            limit: number;
+        };
+    } | undefined;
+    cap_drop?: string[] | undefined;
     hostadd: string[];
     netns: {
         nsmode: string;
@@ -95,9 +127,16 @@ export declare function createPodmanRunOptions(image: string, args: RunContainer
     image: string;
     name: string | undefined;
     command: string[] | undefined;
+    labels: Record<string, string> | undefined;
     volumes: {
         dest: string;
         name: string;
         Options: string[];
     }[] | undefined;
+    mounts: {
+        type: string;
+        source: string;
+        destination: string;
+        options: string[];
+    }[] | undefined;
 };

package/dist/src/NodeManager/provider/containerOrchestration/podman/utils/createPodmanRunOptions.js

@@ -24,7 +24,7 @@ function parseRestartPolicy(restart_policy) {
  * @returns
  */
 export function createPodmanRunOptions(image, args, gpuOption) {
-    const { name, cmd, gpu, volumes, env, aliases, work_dir, entrypoint, restart_policy, runtime, } = args;
+    const { name, cmd, gpu, volumes, env, aliases, work_dir, entrypoint, restart_policy, labels, security, runtime, } = args;
     const devices = gpu
         ? gpuOption === 'all'
             ? [
@@ -41,13 +41,22 @@ export function createPodmanRunOptions(image, args, gpuOption) {
         image,
         name,
         command: cmd,
-        volumes: volumes?.map((v) => {
+        labels,
+        volumes: volumes?.filter((v) => v.type !== 'bind').map((v) => {
             return {
                 dest: v.dest,
                 name: v.name,
                 Options: v.readonly ? ['ro'] : [],
             };
         }),
+        mounts: volumes?.filter((v) => v.type === 'bind').map((v) => {
+            return {
+                type: 'bind',
+                source: v.name,
+                destination: v.dest,
+                options: v.readonly ? ['ro'] : [],
+            };
+        }),
         ...(entrypoint
             ? { entrypoint: ifStringCastToArray(entrypoint) }
             : undefined),
@@ -65,5 +74,10 @@ export function createPodmanRunOptions(image, args, gpuOption) {
         create_working_dir: true,
         cgroups_mode: 'enabled',
         work_dir,
+        ...(security?.capDrop ? { cap_drop: security.capDrop } : {}),
+        // libpod takes limits under resource_limits; a top-level key is ignored.
+        ...(security?.pidsLimit
+            ? { resource_limits: { pids: { limit: security.pidsLimit } } }
+            : {}),
     };
 }

package/dist/src/NodeManager/provider/sshSidecar.d.ts

@@ -0,0 +1,66 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { JobDefinition } from '@nosana/sdk';
+import type { Container } from 'dockerode';
+import type { SshKeyGrant } from '../db/index.js';
+import type { RunContainerArgs } from './containerOrchestration/interface.js';
+/** Marks an operation's frpc sidecar that also runs sshgw. */
+export declare const SSH_SIDECAR_SERVICE = "ssh-sidecar";
+/** The only user name sshgw accepts; the hostname identifies the job. Shared with the client through @nosana/ssh. */
+export declare const SSH_SIDECAR_USER = "nosana";
+export declare const SSH_SIDECAR_KEYS_DIR = "/nosana-ssh";
+/** Runtime label filters that select the running SSH sidecars of a job. */
+export declare function sshSidecarFilters(jobId: string): string[];
+/**
+ * Turns an operation's frpc sidecar config into its SSH sidecar. sshgw runs
+ * next to frpc and needs the runtime socket to exec into the workload; the
+ * image's entrypoint publishes the SSH proxy from the job and operation, keeps
+ * frpc off the socket and exits when either process stops so the runtime
+ * restarts the pair. `prepare` seeds the host key and authorized keys between
+ * create and start, so sshgw never answers with a fresh identity or an empty
+ * key file.
+ */
+export declare function withSshSidecar(config: RunContainerArgs, sidecar: {
+    jobId: string;
+    opIndex: number;
+    /** Runtime name and the socket path as the daemon sees it on the host. */
+    runtime: {
+        name: string;
+        host: string;
+    };
+    prepare: (container: Container) => Promise<void>;
+}): RunContainerArgs;
+/**
+ * The keys a job definition grants at start: deduplicated by identity and
+ * dropped as a set if they break the shared limits. The SDK validator only
+ * lets `ssh.public_keys` through, so that is the only field read.
+ */
+export declare function extractSshPublicKeys(jobDefinition: Pick<JobDefinition, 'ssh'>): string[];
+/** An ed25519 host key as PKCS#8 PEM, which sshgw reads as it is. */
+export declare function generateSshHostKey(): string;
+/**
+ * Seeds a created, not yet started sidecar with the job's host key and its
+ * current authorized_keys, so sshgw finds both on its first start and never
+ * answers with a fresh identity or an empty key file.
+ */
+export declare function seedSshSidecar(container: Container, seed: {
+    hostKey: string;
+    keys: SshKeyGrant[];
+}): Promise<void>;
+/**
+ * Rewrites a sidecar's authorized_keys, whether the sidecar is running or
+ * still only created. sshgw re-reads the file on every attempt and enforces
+ * expiry-time itself, so no reload or timer is needed; a torn read can only
+ * hide a key for an instant, never add one.
+ */
+export declare function replaceSshAuthorizedKeys(container: Container, keys: SshKeyGrant[]): Promise<void>;
+/**
+ * Builds an in-memory POSIX ustar archive of small regular files. Used to
+ * ship the key files into the sidecar container via the runtime's putArchive
+ * endpoint without pulling in a tar dependency.
+ */
+export declare function createTar(files: Array<{
+    name: string;
+    content: Buffer;
+    mode: number;
+}>): Buffer;

package/dist/src/NodeManager/provider/sshSidecar.js

@@ -0,0 +1,176 @@
+import { Readable } from 'stream';
+import { generateKeyPairSync } from 'crypto';
+import { JOB_LABEL, OP_INDEX_LABEL, SERVICE_LABEL, } from './containerOrchestration/labels.js';
+import { getSshKeyIdentity, isValidSshPublicKey, MAX_SSH_PUBLIC_KEYS, MAX_SSH_PUBLIC_KEYS_BYTES, SSH_USERNAME, } from '@nosana/ssh';
+/** Marks an operation's frpc sidecar that also runs sshgw. */
+export const SSH_SIDECAR_SERVICE = 'ssh-sidecar';
+/** The only user name sshgw accepts; the hostname identifies the job. Shared with the client through @nosana/ssh. */
+export const SSH_SIDECAR_USER = SSH_USERNAME;
+export const SSH_SIDECAR_KEYS_DIR = '/nosana-ssh';
+const SSH_SIDECAR_KEYS_FILE = 'authorized_keys';
+const SSH_SIDECAR_HOST_KEY_FILE = 'host_key';
+const SSH_AUTHORIZED_KEY_OPTIONS = 'restrict,pty';
+/** Runtime label filters that select the running SSH sidecars of a job. */
+export function sshSidecarFilters(jobId) {
+    return [`${JOB_LABEL}=${jobId}`, `${SERVICE_LABEL}=${SSH_SIDECAR_SERVICE}`];
+}
+/**
+ * Turns an operation's frpc sidecar config into its SSH sidecar. sshgw runs
+ * next to frpc and needs the runtime socket to exec into the workload; the
+ * image's entrypoint publishes the SSH proxy from the job and operation, keeps
+ * frpc off the socket and exits when either process stops so the runtime
+ * restarts the pair. `prepare` seeds the host key and authorized keys between
+ * create and start, so sshgw never answers with a fresh identity or an empty
+ * key file.
+ */
+export function withSshSidecar(config, sidecar) {
+    const socketDest = sidecar.runtime.name === 'podman'
+        ? '/run/podman/podman.sock'
+        : '/var/run/docker.sock';
+    return {
+        ...config,
+        restart_policy: 'on-failure',
+        env: {
+            ...config.env,
+            SSH_GATEWAY_ENABLED: '1',
+            SSHGW_JOB_ID: sidecar.jobId,
+            SSHGW_OP_INDEX: sidecar.opIndex.toString(),
+            DOCKER_HOST: `unix://${socketDest}`,
+        },
+        volumes: [
+            ...(config.volumes ?? []),
+            {
+                type: 'bind',
+                name: sidecar.runtime.host,
+                dest: socketDest,
+                readonly: true,
+            },
+        ],
+        labels: {
+            ...config.labels,
+            [JOB_LABEL]: sidecar.jobId,
+            [OP_INDEX_LABEL]: sidecar.opIndex.toString(),
+            [SERVICE_LABEL]: SSH_SIDECAR_SERVICE,
+        },
+        security: {
+            capDrop: ['AUDIT_WRITE', 'MKNOD', 'NET_RAW'],
+            pidsLimit: 128,
+        },
+        beforeStart: sidecar.prepare,
+    };
+}
+/**
+ * The keys a job definition grants at start: deduplicated by identity and
+ * dropped as a set if they break the shared limits. The SDK validator only
+ * lets `ssh.public_keys` through, so that is the only field read.
+ */
+export function extractSshPublicKeys(jobDefinition) {
+    const byIdentity = new Map();
+    for (const value of jobDefinition.ssh?.public_keys ?? []) {
+        const key = typeof value === 'string' ? value.trim() : '';
+        if (!isValidSshPublicKey(key))
+            continue;
+        const identity = getSshKeyIdentity(key);
+        if (!byIdentity.has(identity))
+            byIdentity.set(identity, key);
+    }
+    const keys = [...byIdentity.values()];
+    const totalBytes = keys.reduce((sum, key) => sum + Buffer.byteLength(key), 0);
+    if (keys.length > MAX_SSH_PUBLIC_KEYS ||
+        totalBytes > MAX_SSH_PUBLIC_KEYS_BYTES) {
+        return [];
+    }
+    return keys;
+}
+/** An ed25519 host key as PKCS#8 PEM, which sshgw reads as it is. */
+export function generateSshHostKey() {
+    return generateKeyPairSync('ed25519').privateKey.export({
+        type: 'pkcs8',
+        format: 'pem',
+    });
+}
+/**
+ * Seeds a created, not yet started sidecar with the job's host key and its
+ * current authorized_keys, so sshgw finds both on its first start and never
+ * answers with a fresh identity or an empty key file.
+ */
+export async function seedSshSidecar(container, seed) {
+    await container.putArchive(Readable.from(createTar([
+        {
+            name: SSH_SIDECAR_HOST_KEY_FILE,
+            content: Buffer.from(seed.hostKey, 'utf8'),
+            mode: 0o600,
+        },
+        {
+            name: SSH_SIDECAR_KEYS_FILE,
+            content: formatAuthorizedKeys(seed.keys),
+            mode: 0o600,
+        },
+    ])), { path: SSH_SIDECAR_KEYS_DIR });
+}
+/**
+ * Rewrites a sidecar's authorized_keys, whether the sidecar is running or
+ * still only created. sshgw re-reads the file on every attempt and enforces
+ * expiry-time itself, so no reload or timer is needed; a torn read can only
+ * hide a key for an instant, never add one.
+ */
+export async function replaceSshAuthorizedKeys(container, keys) {
+    await container.putArchive(Readable.from(createTar([
+        {
+            name: SSH_SIDECAR_KEYS_FILE,
+            content: formatAuthorizedKeys(keys),
+            mode: 0o600,
+        },
+    ])), { path: SSH_SIDECAR_KEYS_DIR });
+}
+function formatAuthorizedKeys(keys) {
+    const lines = keys.map(({ sshPublicKey, expiresAt }) => {
+        if (!isValidSshPublicKey(sshPublicKey))
+            throw new Error('Invalid SSH public key');
+        const expiry = expiresAt === undefined
+            ? ''
+            : `,expiry-time="${new Date(expiresAt)
+                .toISOString()
+                .slice(0, 19)
+                .replace(/[-:T]/g, '')}Z"`;
+        return `${SSH_AUTHORIZED_KEY_OPTIONS}${expiry} ${sshPublicKey}`;
+    });
+    return Buffer.from(lines.length ? `${lines.join('\n')}\n` : '', 'utf8');
+}
+/**
+ * Builds an in-memory POSIX ustar archive of small regular files. Used to
+ * ship the key files into the sidecar container via the runtime's putArchive
+ * endpoint without pulling in a tar dependency.
+ */
+export function createTar(files) {
+    // Two zero-filled 512-byte blocks mark the end of the archive.
+    const trailer = Buffer.alloc(1024, 0);
+    return Buffer.concat([...files.map(tarEntry), trailer]);
+}
+function tarEntry({ name, content, mode, }) {
+    const header = Buffer.alloc(512, 0);
+    const writeOctal = (value, offset, length) => {
+        // length includes the trailing NUL terminator.
+        const str = value.toString(8).padStart(length - 1, '0');
+        header.write(`${str}\0`, offset, length, 'ascii');
+    };
+    header.write(name, 0, 100, 'utf8'); // name
+    writeOctal(mode & 0o7777, 100, 8); // mode
+    writeOctal(0, 108, 8); // uid
+    writeOctal(0, 116, 8); // gid
+    writeOctal(content.length, 124, 12); // size
+    writeOctal(Math.floor(Date.now() / 1000), 136, 12); // mtime
+    header.write('        ', 148, 8, 'ascii'); // checksum placeholder (8 spaces)
+    header.write('0', 156, 1, 'ascii'); // typeflag: normal file
+    header.write('ustar', 257, 5, 'ascii'); // magic
+    header.write('00', 263, 2, 'ascii'); // version
+    let checksum = 0;
+    for (let i = 0; i < 512; i++)
+        checksum += header[i];
+    // 6 octal digits, NUL, space.
+    header.write(`${checksum.toString(8).padStart(6, '0')}\0 `, 148, 8, 'ascii');
+    const paddedContentLength = Math.ceil(content.length / 512) * 512;
+    const body = Buffer.alloc(paddedContentLength, 0);
+    content.copy(body);
+    return Buffer.concat([header, body]);
+}

package/dist/src/NodeManager/provider/webTerminal.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="node" />
+import type { Duplex } from 'stream';
+import type { ContainerOrchestrationInterface } from './containerOrchestration/interface.js';
+export type TerminalSession = {
+    stream: Duplex;
+    resize: (size: {
+        cols?: number;
+        rows?: number;
+    }) => Promise<void>;
+    inspectExitCode: () => Promise<number | null>;
+    close: () => void;
+};
+/**
+ * Finds the single running container that belongs to a job (optionally scoped
+ * to a specific operation) and opens an interactive PTY exec session into it.
+ *
+ * Mirrors the selection sshgw performs in the sidecar, but runs in-process
+ * over the node's own runtime socket.
+ */
+export declare function createJobTerminalExec(orchestration: ContainerOrchestrationInterface, jobId: string, options?: {
+    op?: string;
+    cols?: number;
+    rows?: number;
+}): Promise<TerminalSession>;