@memrov2/pentcloud-tool-runtime 0.0.0-stage → 0.1.1-dev.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PentCloud contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# PentCloud tool runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared native Cloudflare Durable Object execution support for PentCloud’s tool SDKs: serialized commands, pinned-image verification, bounded binary attachments and native streamed Workflow evidence.
+
+Version 0.1.0. See [release and integration instructions](https://github.com/Memrov/PentCloud-tools/blob/main/docs/releases.md). This package does not launch an assessment or deploy an application by itself.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,3 @@
+# Third-party notices
+
+The adapter is MIT licensed. Tool images preserve their original upstream notices. See the repository build metadata and pack documentation for pinned software and assets.

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@memrov2/pentcloud-tool-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1-dev.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Cloudflare-native tool-runtime tool pack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Memrov/PentCloud-tools.git",
+    "directory": "packages/runtime"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "import": "./src/index.mjs"
+    },
+    "./worker": {
+      "types": "./src/worker.d.mts",
+      "import": "./src/worker.mjs"
+    }
+  },
+  "files": [
+    "src",
+    "tools.lock.json",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.mts

@@ -0,0 +1,73 @@
+export interface ToolCommand {
+  argv: string[];
+  stdin: string;
+  timeoutMs: number;
+  requiredFiles?: string[];
+}
+export interface PackLock {
+  packId: string;
+  packVersion: string;
+  tools: readonly { tool: string; version: string }[];
+}
+export interface ToolResult {
+  tool: string;
+  toolVersion: string;
+  packId: string;
+  packVersion: string;
+  image: string;
+  readyMs: number;
+  startedAt: string;
+  finishedAt: string;
+  argv: string[];
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  truncated: boolean;
+  error?: string;
+  inputHashes?: Record<string, string>;
+  processMs: number;
+  firstJSONMs: number;
+  cpuUserMs: number;
+  cpuSystemMs: number;
+  maxRSSKiB: number;
+}
+export declare function request(
+  input: unknown,
+  allowed: string[],
+  tools: string[],
+): URL;
+
+export interface StreamStep {
+  do(
+    name: string,
+    config: { retries: { limit: 0; delay: "1 second" }; timeout: "3 minutes" },
+    callback: () => Promise<ReadableStream<Uint8Array>>,
+  ): Promise<ReadableStream<Uint8Array>>;
+}
+export declare function runWorkflowStep<I>(
+  step: StreamStep,
+  runner: {
+    run(input: I, files?: Record<string, Uint8Array>): Promise<ToolResult>;
+  },
+  input: I,
+  files?: Record<string, Uint8Array>,
+): Promise<
+  Omit<
+    ToolResult,
+    | "stdout"
+    | "stderr"
+    | "argv"
+    | "processMs"
+    | "firstJSONMs"
+    | "cpuUserMs"
+    | "cpuSystemMs"
+    | "maxRSSKiB"
+    | "readyMs"
+  > & { stdoutBytes: number; stderrBytes: number; evidenceStep: string }
+>;
+
+export declare function prepareFiles(
+  required: string[],
+  files?: Record<string, Uint8Array>,
+): Promise<Record<string, { base64: string; sha256: string }>>;

package/src/index.mjs

@@ -0,0 +1,101 @@
+export function request(input, allowed, tools) {
+  if (
+    !input ||
+    typeof input !== "object" ||
+    Array.isArray(input) ||
+    Object.keys(input).some((k) => !allowed.includes(k)) ||
+    !tools.includes(input.tool)
+  )
+    throw new TypeError("Unsupported tool or request fields");
+  if (
+    typeof input.target !== "string" ||
+    !input.target ||
+    input.target.length > 2048 ||
+    /[\s\x00-\x1f\x7f\\]/.test(input.target)
+  )
+    throw new TypeError("Invalid target");
+  const url = new URL(input.target);
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    !url.hostname ||
+    url.username ||
+    url.password ||
+    url.hash
+  )
+    throw new TypeError("Use an HTTP(S) URL without credentials or a fragment");
+  return url;
+}
+
+export async function prepareFiles(required, input = {}) {
+  if (
+    !input ||
+    typeof input !== "object" ||
+    Array.isArray(input) ||
+    Object.keys(input).length !== required.length ||
+    Object.keys(input).some((name) => !required.includes(name))
+  )
+    throw new TypeError("Supply exactly the required input files");
+  let total = 0;
+  const files = required.map((name) => {
+    const value = input[name];
+    if (
+      !(value instanceof Uint8Array) ||
+      value.byteLength === 0 ||
+      (total += value.byteLength) > 2097152
+    )
+      throw new TypeError("Input files must total at most two MiB");
+    return [name, new Uint8Array(value)];
+  });
+  return Object.fromEntries(
+    await Promise.all(
+      files.map(async ([name, value]) => {
+        const digest = await crypto.subtle.digest("SHA-256", value);
+        let binary = "";
+        for (let offset = 0; offset < value.length; offset += 8192)
+          binary += String.fromCharCode(
+            ...value.subarray(offset, offset + 8192),
+          );
+        return [
+          name,
+          {
+            base64: btoa(binary),
+            sha256: [...new Uint8Array(digest)]
+              .map((v) => v.toString(16).padStart(2, "0"))
+              .join(""),
+          },
+        ];
+      }),
+    ),
+  );
+}
+
+/** Persist full output using Workflows' native stream support; complete with metadata only. */
+export async function runWorkflowStep(step, runner, input, files) {
+  const stream = await step.do(
+    "tool-evidence",
+    { retries: { limit: 0, delay: "1 second" }, timeout: "3 minutes" },
+    async () => {
+      const result = await runner.run(input, files);
+      return new Blob([JSON.stringify(result)], {
+        type: "application/json",
+      }).stream();
+    },
+  );
+  const result = await new Response(stream).json();
+  return {
+    packId: result.packId,
+    packVersion: result.packVersion,
+    tool: result.tool,
+    toolVersion: result.toolVersion,
+    image: result.image,
+    exitCode: result.exitCode,
+    timedOut: result.timedOut,
+    truncated: result.truncated,
+    startedAt: result.startedAt,
+    finishedAt: result.finishedAt,
+    stdoutBytes: new TextEncoder().encode(result.stdout).length,
+    stderrBytes: new TextEncoder().encode(result.stderr).length,
+    evidenceStep: "tool-evidence",
+    ...(result.inputHashes ? { inputHashes: result.inputHashes } : {}),
+  };
+}

package/src/worker.d.mts

@@ -0,0 +1,20 @@
+import { DurableObject } from "cloudflare:workers";
+import type { ToolCommand, ToolResult, PackLock } from "./index.mjs";
+declare class ToolRunner<I> extends DurableObject {
+  ready(): Promise<{ image: string; instance: "lite" | "standard-1"; readyMs: number }>;
+  run(input: I, files?: Record<string, Uint8Array>): Promise<ToolResult>;
+  retire(): Promise<{ stopped: boolean; retired: true }>;
+  stop(): Promise<{ stopped: boolean }>;
+  capabilities(): Promise<{
+    platform: string;
+    architecture: string;
+    rawPacketSocket: boolean;
+    rawPacketError?: string;
+    image: string;
+    readyMs: number;
+  }>;
+}
+export declare function createRunner<I>(
+  lock: PackLock,
+  buildCommand: (input: I) => ToolCommand,
+): new (ctx: DurableObjectState, env: unknown) => ToolRunner<I>;

package/src/worker.mjs

@@ -0,0 +1,168 @@
+import { DurableObject } from "cloudflare:workers";
+import { prepareFiles } from "./index.mjs";
+const decode = (data) => new TextDecoder().decode(data);
+const hash = async (value) =>
+  [
+    ...new Uint8Array(
+      await crypto.subtle.digest(
+        "SHA-256",
+        new TextEncoder().encode(JSON.stringify(value)),
+      ),
+    ),
+  ]
+    .map((x) => x.toString(16).padStart(2, "0"))
+    .join("");
+async function exec(container, argv, body, signal) {
+  const process = await container.exec(argv, {
+    signal,
+    ...(body ? { stdin: new Blob([body]).stream() } : {}),
+  });
+  const result = await process.output();
+  return {
+    exitCode: result.exitCode,
+    stdout: decode(result.stdout),
+    stderr: decode(result.stderr),
+  };
+}
+export function createRunner(lock, buildCommand) {
+  const root = "/opt/pentcloud-" + lock.packId;
+  return class ToolRunner extends DurableObject {
+    #queue = Promise.resolve();
+    #serialize(action) {
+      const result = this.#queue.then(action);
+      this.#queue = result.catch(() => {});
+      return result;
+    }
+    async #ready() {
+      if (await this.ctx.storage.get("retired")) throw new Error("Owned tool runtime is retired");
+      const container = this.ctx.container,
+        image = container.images[lock.packId],
+        start = Date.now();
+      if (!image)
+        throw new Error("Configure the " + lock.packId + " named image");
+      if (container.running) {
+        if ((await container.inspect())?.image !== image)
+          throw new Error(
+            "Image changed; stop the current runtime before upgrading",
+          );
+      } else
+        container.start({
+          image,
+          instance: lock.packId === "password" ? "standard-1" : "lite",
+          enableInternet: lock.runtime?.enableInternet ?? true,
+          labels: { pack: lock.packId, version: lock.packVersion },
+        });
+      await container.setInactivityTimeout(120000);
+      const signal = AbortSignal.timeout(90000);
+      while (true) {
+        try {
+          if (
+            (await exec(container, ["/bin/true"], undefined, signal))
+              .exitCode === 0
+          )
+            break;
+        } catch (error) {
+          if (signal.aborted)
+            throw new Error("Container readiness exceeded 90 seconds");
+        }
+        if (signal.aborted || Date.now() - start >= 90000)
+          throw new Error("Container readiness exceeded 90 seconds");
+        await new Promise((resolve) =>
+          setTimeout(resolve, Math.min(1000, 90000 - (Date.now() - start))),
+        );
+      }
+      const marker = await exec(
+        container,
+        ["/bin/cat", root + "/pack.json"],
+        undefined,
+        signal,
+      );
+      let release;
+      try {
+        release = JSON.parse(marker.stdout);
+      } catch {
+        throw new Error("Invalid pack image manifest");
+      }
+      if (marker.exitCode !== 0 || release.lockSha256 !== (await hash(lock)))
+        throw new Error("Pack image and SDK pins do not match");
+      if ((await container.inspect())?.image !== image)
+        throw new Error("Unable to verify pack image identity");
+      return { image, instance: lock.packId === "password" ? "standard-1" : "lite", readyMs: Date.now() - start };
+    }
+    ready() {
+      return this.#serialize(() => this.#ready());
+    }
+    run(input, files) {
+      const { requiredFiles = [], ...command } = buildCommand(input),
+        tool = input.tool;
+      const prepared = prepareFiles(requiredFiles, files);
+      prepared.catch(() => {});
+      return this.#serialize(async () => {
+        const attachments = await prepared;
+        const startedAt = new Date().toISOString(),
+          ready = await this.#ready();
+        const output = await exec(
+          this.ctx.container,
+          [root + "/bin/pack-exec"],
+          JSON.stringify({
+            ...command,
+            ...(Object.keys(attachments).length ? { files: attachments } : {}),
+          }),
+          AbortSignal.timeout(90000),
+        );
+        if (output.exitCode !== 0)
+          throw new Error("Pack execution helper failed");
+        let result;
+        try {
+          result = JSON.parse(output.stdout);
+        } catch {
+          throw new Error("Invalid pack execution response");
+        }
+        if (
+          !Number.isInteger(result.exitCode) ||
+          typeof result.stdout !== "string" ||
+          typeof result.stderr !== "string" ||
+          typeof result.timedOut !== "boolean" ||
+          typeof result.truncated !== "boolean"
+        )
+          throw new Error("Incomplete pack execution response");
+        return {
+          ...result,
+          ...ready,
+          tool,
+          toolVersion: lock.tools.find((t) => t.tool === tool).version,
+          packId: lock.packId,
+          packVersion: lock.packVersion,
+          startedAt,
+          finishedAt: new Date().toISOString(),
+        };
+      });
+    }
+    retire() {
+      return this.#serialize(async () => {
+        await this.ctx.storage.put("retired", true);
+        if (this.ctx.container.running) await this.ctx.container.destroy();
+        return { stopped: !this.ctx.container.running, retired: true };
+      });
+    }
+    stop() {
+      return this.#serialize(async () => {
+        if (this.ctx.container.running) await this.ctx.container.destroy();
+        return { stopped: !this.ctx.container.running };
+      });
+    }
+    capabilities() {
+      return this.#serialize(async () => {
+        const ready = await this.#ready();
+        const result = await exec(
+          this.ctx.container,
+          [root + "/bin/pack-exec", "--capabilities"],
+          undefined,
+          AbortSignal.timeout(10000),
+        );
+        if (result.exitCode !== 0) throw new Error("Capability probe failed");
+        return { ...JSON.parse(result.stdout), ...ready };
+      });
+    }
+  };
+}