@botiverse/k-carrier 0.1.0

package/harness/src/fake-server/manifest.ts

@@ -0,0 +1,68 @@
+/**
+ * Manifest model — the L0 static-file protocol (design-v1 §L0).
+ *
+ * A release is described by `manifest.json`: version + per-platform targets
+ * (artifact filename, sha256, size). The fake-server serves this plus the
+ * artifacts.
+ *
+ * The exact JSON shape here IS the wire contract the core artifact layer
+ * will consume; kept in the harness first so the harness is the first
+ * consumer (harness-design §0.3 dogfood rule).
+ */
+
+import { createHash } from "node:crypto";
+
+export const MANIFEST_FILE = "manifest.json";
+
+/** One platform's binary target inside a manifest. */
+export interface ManifestTarget {
+  /** Artifact filename, relative to the release root (served at /<file>). */
+  file: string;
+  sha256: string;
+  size: number;
+}
+
+export interface Manifest {
+  version: string;
+  /** Platform tag (e.g. "darwin-arm64") -> binary target. */
+  targets: Record<string, ManifestTarget>;
+  /** Track the release was published under (latest | alpha). Optional. */
+  /** Explicit opt-out of the signature chain (never a silent default). */
+}
+
+export function buildManifest(
+  version: string,
+  targets: Record<string, ManifestTarget>,
+): Manifest {
+  const manifest: Manifest = { version, targets };
+  return manifest;
+}
+
+/** sha256 hex of bytes (Node crypto; zero deps). */
+export function sha256Hex(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/**
+ * Numeric dotted version compare (1.2.3 < 1.10.0). Enough for the harness's
+ * own assertions; the core's anti-rollback policy will own the real rule.
+ * Returns -1 / 0 / 1.
+ */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map((s) => {
+    const n = Math.trunc(Number(s));
+    return Number.isNaN(n) ? 0 : n;
+  });
+  const pb = b.split(".").map((s) => {
+    const n = Math.trunc(Number(s));
+    return Number.isNaN(n) ? 0 : n;
+  });
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da < db) return -1;
+    if (da > db) return 1;
+  }
+  return 0;
+}

package/harness/src/fake-server/server.ts

@@ -0,0 +1,205 @@
+/**
+ * fake-server — local static publishing server (harness-design §1.2).
+ *
+ * A REAL HTTP static server (node:http, zero deps) that serves a release:
+ * manifest.json + artifacts. It is the
+ * black-box plane's publishing endpoint — DST's in-memory disk is a
+ * separate component (§1.45); this one serves real bytes over a
+ * real socket.
+ *
+ * Tamper API — the supply-chain teeth's whole point is "real tamper ->
+ * real reject": corruptByte / swapFiles / serveOlderVersion / dropFile all
+ * mutate what the client actually downloads, and the teeth verify that a
+ * real chain verifier rejects the result. No verification function is
+ * mocked anywhere. The on-disk release semantics live in ReleaseStore
+ * (store.ts); this file is the HTTP layer over it.
+ */
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { ReleaseStore, type PublishReleaseSpec, type PublishedRelease } from "./store.ts";
+
+export type { PublishReleaseSpec, PublishedRelease };
+
+export interface FakeServerOptions {
+  /** Directory that will hold the release store (usually inside a sandbox). */
+  storeDir: string;
+  /** Port to bind; omit for an OS-assigned ephemeral port. */
+  port?: number;
+  /** Throttle artifact responses (interruptible-download tests). */
+  throttle?: { bytesPerTick: number; tickMs: number };
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".json": "application/json",
+  ".pub": "application/x-pem-file",
+  ".bin": "application/octet-stream",
+  ".sig": "application/octet-stream",
+};
+
+export class FakeServer {
+  /** The release store backing this server (the factory's publish target). */
+  readonly store: ReleaseStore;
+  private readonly requestedPort: number | undefined;
+  private readonly throttle: { bytesPerTick: number; tickMs: number } | undefined;
+  private server: Server | null = null;
+  private actualPort = 0;
+  /** Every request the server handled (for asserting Range flows). */
+  readonly requestLog: Array<{ method: string; url: string; range: string | null }> = [];
+
+  constructor(opts: FakeServerOptions) {
+    this.store = new ReleaseStore(opts.storeDir);
+    this.requestedPort = opts.port;
+    this.throttle = opts.throttle;
+  }
+
+  get url(): string {
+    if (!this.server) throw new Error("FakeServer not started");
+    return `http://127.0.0.1:${this.actualPort}`;
+  }
+
+  get port(): number {
+    return this.actualPort;
+  }
+
+  get active(): string | null {
+    return this.store.active;
+  }
+
+  async start(): Promise<void> {
+    if (this.server) return;
+    const server = createServer((req, res) => void this.handle(req, res));
+    this.server = server;
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(this.requestedPort ?? 0, "127.0.0.1", () => {
+        const addr = server.address();
+        if (addr && typeof addr === "object") this.actualPort = addr.port;
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (!this.server) return;
+    const server = this.server;
+    this.server = null;
+    await new Promise<void>((resolve) => {
+      server.close(() => {
+        resolve();
+      });
+    });
+  }
+
+  async publishRelease(spec: PublishReleaseSpec): Promise<PublishedRelease> {
+    this.requireStarted();
+    return this.store.publish(spec);
+  }
+
+  async corruptByte(file: string, offset: number): Promise<void> {
+    return this.store.corruptByte(file, offset);
+  }
+
+  /** Serve each file the other's bytes: both then fail their own sha256. */
+  async swapFiles(fileA: string, fileB: string): Promise<void> {
+    return this.store.swapFiles(fileA, fileB);
+  }
+
+  async serveOlderVersion(): Promise<string> {
+    return this.store.switchToOlderVersion();
+  }
+
+  async dropFile(file: string): Promise<void> {
+    return this.store.dropFile(file);
+  }
+
+  async restore(): Promise<void> {
+    return this.store.restore();
+  }
+
+  async readFile(file: string): Promise<Uint8Array> {
+    return this.store.readFile(file);
+  }
+
+  private requireStarted(): void {
+    if (!this.server) throw new Error("FakeServer not started");
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.writeHead(405, { "content-type": "text/plain" }).end("method not allowed");
+      return;
+    }
+    const raw = (req.url ?? "/").split("?")[0] ?? "/";
+    let file: string;
+    try {
+      file = decodeURIComponent(raw).replace(/^\/+/, "");
+    } catch {
+      res.writeHead(400, { "content-type": "text/plain" }).end("bad request");
+      return;
+    }
+    if (!file) {
+      res.writeHead(404, { "content-type": "text/plain" }).end("not found");
+      return;
+    }
+    let target: string;
+    try {
+      target = await this.store.resolveFile(file);
+    } catch {
+      res.writeHead(404, { "content-type": "text/plain" }).end("not found");
+      return;
+    }
+    this.requestLog.push({ method: req.method, url: file, range: req.headers.range ?? null });
+    try {
+      const data = await fs.readFile(target);
+      const ext = path.extname(file).toLowerCase();
+      const contentType = CONTENT_TYPES[ext] ?? "application/octet-stream";
+
+      // Range: bytes=N- (the single-range form the resumable download uses)
+      const rangeMatch = /^bytes=(\d+)-$/.exec(req.headers.range ?? "");
+      if (rangeMatch) {
+        const start = Number(rangeMatch[1]);
+        if (start >= data.length) {
+          res.writeHead(416, { "content-type": "text/plain" }).end("range not satisfiable");
+          return;
+        }
+        const slice = data.subarray(start);
+        res.writeHead(206, {
+          "content-type": contentType,
+          "content-range": `bytes ${start}-${data.length - 1}/${data.length}`,
+          "content-length": slice.length,
+        });
+        await this.writeBody(res, slice);
+        return;
+      }
+
+      res.writeHead(200, {
+        "content-type": contentType,
+        "content-length": data.length,
+      });
+      if (req.method === "GET") await this.writeBody(res, data);
+      else res.end();
+    } catch {
+      res.writeHead(404, { "content-type": "text/plain" }).end("not found");
+    }
+  }
+
+  /** Write the body, chunked and delayed when throttled (kill-window tests). */
+  private async writeBody(res: ServerResponse, data: Buffer): Promise<void> {
+    if (!this.throttle) {
+      res.end(data);
+      return;
+    }
+    const { bytesPerTick, tickMs } = this.throttle;
+    for (let off = 0; off < data.length; off += bytesPerTick) {
+      const chunk = data.subarray(off, off + bytesPerTick);
+      res.write(chunk);
+      if (off + bytesPerTick < data.length) {
+        await new Promise((r) => {
+          setTimeout(r, tickMs);
+        });
+      }
+    }
+    res.end();
+  }
+}

package/harness/src/fake-server/store.ts

@@ -0,0 +1,208 @@
+/**
+ * ReleaseStore — on-disk release store behind the fake-server: publish
+ * (manifest + artifacts), pristine copies,
+ * file-level tamper ops and version switching. Pure filesystem semantics,
+ * no HTTP; the FakeServer in server.ts is the HTTP layer over this.
+ *
+ * Tamper ops mutate the served files on disk (a compromised server's files
+ * ARE what the client gets); restore() regenerates from pristine.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import {
+  MANIFEST_FILE,
+  buildManifest,
+  sha256Hex,
+  compareVersions,
+  type Manifest,
+} from "./manifest.ts";
+
+export interface PublishReleaseSpec {
+  version: string;
+  /** Logical artifact name -> content; served at /<name>. */
+  artifacts: Record<string, string | Uint8Array>;
+  /** Platform tag for the manifest target. Default: "current". */
+  platform?: string;
+  /** Which artifact is the binary for `platform`. Default: the sole artifact. */
+  binary?: string;
+  /** Default true: the new release becomes the active (served) one. */
+  makeActive?: boolean;
+  /** chmod +x every artifact file (real binaries need to be runnable). */
+  executable?: boolean;
+}
+
+export interface PublishedRelease {
+  version: string;
+  /** All files served for this release (relative paths). */
+  files: string[];
+  manifest: Manifest;
+}
+
+export class ReleaseStore {
+  private readonly storeDir: string;
+  private activeVersion: string | null = null;
+  /** version -> file -> pristine bytes, for restore(). */
+  private readonly pristine = new Map<string, Map<string, Uint8Array>>();
+
+  constructor(storeDir: string) {
+    this.storeDir = storeDir;
+  }
+
+  get active(): string | null {
+    return this.activeVersion;
+  }
+
+  /** Whether a release with this version has been published. */
+  has(version: string): boolean {
+    return this.pristine.has(version);
+  }
+
+  /**
+   * Publish a release into the store: writes artifacts + manifest + the
+   * manifest, and makes it the active release (unless
+   * makeActive is false).
+   */
+  async publish(spec: PublishReleaseSpec): Promise<PublishedRelease> {
+    const version = spec.version;
+    if (this.pristine.has(version)) {
+      throw new Error(`release ${version} already published`);
+    }
+    const artifactNames = Object.keys(spec.artifacts);
+    if (artifactNames.length === 0) throw new Error("release has no artifacts");
+    const binary = spec.binary ?? (artifactNames.length === 1 ? artifactNames[0] : undefined);
+    if (!binary) throw new Error("multiple artifacts: specify which one is the platform binary");
+    if (!artifactNames.includes(binary)) throw new Error(`binary ${binary} not among artifacts`);
+
+    const releaseDir = this.releaseDir(version);
+    await fs.mkdir(releaseDir, { recursive: true });
+
+    const bytes = new Map<string, Uint8Array>();
+    const targets: Manifest["targets"] = {};
+    for (const name of artifactNames) {
+      const content = spec.artifacts[name];
+      if (content === undefined) throw new Error(`artifact ${name} has no content`);
+      const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+      bytes.set(name, data);
+      await fs.writeFile(path.join(releaseDir, name), data);
+    }
+    if (spec.executable) {
+      for (const name of artifactNames) {
+        await fs.chmod(path.join(releaseDir, name), 0o755);
+      }
+    }
+    const binaryData = bytes.get(binary);
+    if (!binaryData) throw new Error(`missing bytes for binary ${binary}`);
+    targets[spec.platform ?? "current"] = {
+      file: binary,
+      sha256: sha256Hex(binaryData),
+      size: binaryData.length,
+    };
+    const manifest = buildManifest(version, targets);
+    const manifestJson = new TextEncoder().encode(JSON.stringify(manifest, null, 2));
+
+    await fs.writeFile(path.join(releaseDir, MANIFEST_FILE), manifestJson);
+
+    // Pristine copy for restore().
+    const pristineFiles = new Map<string, Uint8Array>();
+    for (const name of artifactNames) {
+      const data = bytes.get(name);
+      if (data) pristineFiles.set(name, data);
+    }
+    pristineFiles.set(MANIFEST_FILE, manifestJson);
+    this.pristine.set(version, pristineFiles);
+
+    if (spec.makeActive !== false) this.activeVersion = version;
+    return { version, files: [...pristineFiles.keys()], manifest };
+  }
+
+  /**
+   * Flip one byte of a served file. offset is 0-based from the start of
+   * the file; the byte is XORed with 0xff (a genuine corruption, never a
+   * no-op unless applied twice to the same offset).
+   */
+  async corruptByte(file: string, offset: number): Promise<void> {
+    const target = await this.resolveFile(file);
+    const data = await fs.readFile(target);
+    if (offset < 0 || offset >= data.length) {
+      throw new RangeError(
+        `corruptByte: offset ${offset} out of range for ${file} (${data.length} bytes)`,
+      );
+    }
+    const corrupted = Buffer.from(data);
+    const current = corrupted[offset];
+    if (current === undefined) {
+      throw new RangeError(`corruptByte: offset ${offset} out of range for ${file}`);
+    }
+    corrupted[offset] = current ^ 0xff;
+    await fs.writeFile(target, corrupted);
+  }
+
+  /**
+   * Swap two files' contents: each file now holds the other's bytes, so a
+   * sha256 that was correct for one file is presented against the other.
+   */
+  async swapFiles(fileA: string, fileB: string): Promise<void> {
+    const a = await this.resolveFile(fileA);
+    const b = await this.resolveFile(fileB);
+    const dataA = await fs.readFile(a);
+    const dataB = await fs.readFile(b);
+    await fs.writeFile(a, dataB);
+    await fs.writeFile(b, dataA);
+  }
+
+  /**
+   * Switch the active release to the strictly-older one (downgrade
+   * attack). Returns the version now being served. Throws if no strictly
+   * older release is published.
+   */
+  async switchToOlderVersion(): Promise<string> {
+    const activeVersion = this.activeVersion;
+    if (!activeVersion) throw new Error("no active release");
+    const versions = [...this.pristine.keys()].filter((v) => compareVersions(v, activeVersion) < 0);
+    if (versions.length === 0) throw new Error("no older release published");
+    versions.sort(compareVersions);
+    const older = versions[0]; // oldest published
+    if (!older) throw new Error("no older release published");
+    this.activeVersion = older;
+    return older;
+  }
+
+  /** Stop serving a file: the client gets 404 for it from now on. */
+  async dropFile(file: string): Promise<void> {
+    await fs.unlink(await this.resolveFile(file));
+  }
+
+  /** Regenerate the active release from its pristine copy (undo tamper). */
+  async restore(): Promise<void> {
+    const activeVersion = this.activeVersion;
+    if (!activeVersion) throw new Error("no active release");
+    const pristine = this.pristine.get(activeVersion);
+    if (!pristine) throw new Error(`no pristine copy for ${activeVersion}`);
+    const releaseDir = this.releaseDir(activeVersion);
+    for (const [file, data] of pristine) {
+      await fs.writeFile(path.join(releaseDir, file), data);
+    }
+  }
+
+  /** Read a served file's current bytes (what a client would download). */
+  async readFile(file: string): Promise<Uint8Array> {
+    return new Uint8Array(await fs.readFile(await this.resolveFile(file)));
+  }
+
+  /** Absolute path of a served file; throws if missing or escaping root. */
+  async resolveFile(file: string): Promise<string> {
+    const activeVersion = this.activeVersion;
+    if (!activeVersion) throw new Error("no active release");
+    const releaseDir = this.releaseDir(activeVersion);
+    const resolved = path.resolve(releaseDir, `.${path.sep}${file}`);
+    if (resolved !== releaseDir && !resolved.startsWith(releaseDir + path.sep)) {
+      throw new Error(`path escapes release root: ${file}`);
+    }
+    await fs.access(resolved);
+    return resolved;
+  }
+
+  private releaseDir(version: string): string {
+    return path.join(this.storeDir, "releases", version);
+  }
+}

package/harness/src/fixtures/minimal-adapter.ts

@@ -0,0 +1,108 @@
+/**
+ * Minimal adopter adapter fixture — an INDEPENDENT HostAdapter + workload
+ * driver used to exercise `k-harness --adapter` (harness-design §1.7: the
+ * adopter contract subset runs against the adapter, not the fake host).
+ *
+ * It is intentionally NOT InprocFakeHost: a real adopter brings its own
+ * host semantics; this one is a from-scratch minimal implementation of the
+ * same contract surface (its own ledger bytes, its own startIds), so the
+ * adapter-mode tests prove the contract checks are host-agnostic.
+ *
+ * Default export contract: `(stateDir: string) => HostDriver`.
+ */
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import type { ProcessEvidence, Slot } from "../../../core/src/lifecycle/hostAdapter.ts";
+import type { HostDriver, LedgerState } from "../fake-host/inproc.ts";
+
+const LEDGER = "adapter-ledger.bin";
+
+export function createMinimalAdapter(stateDir: string): HostDriver {
+  let counter = 0;
+  let checksum: Uint8Array = createHash("sha256").update("minimal-adapter-v1").digest();
+  let runningSlot: Slot | null = null;
+  let parked = false;
+  let incarnation = 0;
+  let currentStartId: string | null = null;
+
+  const ledgerBytes = (): Uint8Array => {
+    const out = new Uint8Array(8 + 32);
+    new DataView(out.buffer).setBigUint64(0, BigInt(counter), false);
+    out.set(checksum, 8);
+    return out;
+  };
+
+  const writeLedger = async (): Promise<void> => {
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(path.join(stateDir, LEDGER), ledgerBytes());
+  };
+
+  return {
+    async quiesce() {
+      if (parked) return;
+      if (!runningSlot) throw new Error("quiesce: no running slot");
+      parked = true;
+      await writeLedger();
+    },
+    async stop(slot: Slot) {
+      if (runningSlot !== slot) throw new Error(`stop: ${slot} is not the running slot`);
+      runningSlot = null;
+    },
+    async start(slot: Slot) {
+      if (runningSlot !== null) throw new Error(`start: ${runningSlot} already running`);
+      runningSlot = slot;
+      incarnation += 1;
+      currentStartId = `minimal-inc:${incarnation}`;
+    },
+    async healthProbe(): Promise<ProcessEvidence> {
+      if (!runningSlot) throw new Error("probe: no running slot");
+      if (!currentStartId) throw new Error("probe: no startId");
+      return {
+        version: runningSlot === "stable" ? "1.0.0" : "2.0.0",
+        pid: process.pid,
+        startId: currentStartId,
+      };
+    },
+    async resume() {
+      if (!parked) throw new Error("resume: not quiesced");
+      parked = false;
+      // restore in-memory state from the parked ledger file
+      const raw = new Uint8Array(await fs.readFile(path.join(stateDir, LEDGER)));
+      counter = Number(new DataView(raw.buffer, raw.byteOffset, raw.byteLength).getBigUint64(0, false));
+      checksum = raw.slice(8);
+    },
+    get running(): Slot | null {
+      return runningSlot;
+    },
+    get parked(): boolean {
+      return parked;
+    },
+    get startId(): string | null {
+      return currentStartId;
+    },
+    async doWork(n: number) {
+      if (parked) throw new Error("workload is parked (quiesced)");
+      if (!runningSlot) throw new Error("doWork: no running slot");
+      for (let i = 0; i < n; i++) {
+        counter += 1;
+        checksum = createHash("sha256").update(be64(counter)).update(checksum).digest();
+      }
+      await writeLedger();
+    },
+    async ledger(): Promise<Uint8Array> {
+      return new Uint8Array(await fs.readFile(path.join(stateDir, LEDGER)));
+    },
+    async ledgerState(): Promise<LedgerState> {
+      return { counter, checksum };
+    },
+  };
+}
+
+function be64(n: number): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, BigInt(n), false);
+  return out;
+}
+
+export default createMinimalAdapter;