@condition-sh/runner 2026.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rad Soft, Inc.
+
+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

@@ -0,0 +1,5 @@
+# @condition-sh/runner
+
+Mount a signed Condition runner inside your app.
+
+Docs at https://condition.sh.

package/index.js

@@ -0,0 +1,210 @@
+// packages/runner/src/server.ts
+import { describeProject, inboxAddress } from "@condition-sh/core";
+
+// packages/runner/src/signature.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+var TIMESTAMP_HEADER = "x-condition-timestamp";
+var SIGNATURE_HEADER = "x-condition-signature";
+var windowSeconds = 300;
+function payload(timestamp, method, route, body) {
+  return `${timestamp}
+${method.toUpperCase()}
+${route}
+${body}`;
+}
+function sign(secret, method, route, body, now = Date.now()) {
+  const timestamp = String(Math.floor(now / 1000));
+  const signature = createHmac("sha256", secret).update(payload(timestamp, method, route, body)).digest("hex");
+  return { [TIMESTAMP_HEADER]: timestamp, [SIGNATURE_HEADER]: signature };
+}
+function verifySignature(secret, headers, method, route, body, now = Date.now()) {
+  const timestamp = headers.get(TIMESTAMP_HEADER) ?? "";
+  const signature = headers.get(SIGNATURE_HEADER) ?? "";
+  if (!/^\d{1,12}$/.test(timestamp) || !/^[0-9a-f]{64}$/.test(signature))
+    return false;
+  if (Math.abs(now / 1000 - Number(timestamp)) > windowSeconds)
+    return false;
+  const expected = createHmac("sha256", secret).update(payload(timestamp, method, route, body)).digest();
+  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
+}
+
+// packages/runner/src/server.ts
+var runPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+var routePattern = /\/(scenarios|present|runs|runs\/([0-9a-f-]{36})\/(verify|login|cleanup))$/;
+
+class RunnerError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+var json = (value, status = 200) => Response.json(value, { status, headers: { "cache-control": "no-store" } });
+function lookup(project, body) {
+  const scenario = typeof body.scenario === "string" ? project.scenarios[body.scenario] : undefined;
+  if (!scenario)
+    throw new RunnerError(404, `unknown scenario ${String(body.scenario)}`);
+  return scenario;
+}
+async function perform(project, route, body) {
+  const [, name, runId, step] = route;
+  if (name === "present") {
+    const scenario2 = lookup(project, body);
+    const hook = body.kind === "input" ? scenario2.presentInput : scenario2.present;
+    return { presented: hook ? await hook(body.value) ?? null : null };
+  }
+  const scenario = lookup(project, body);
+  const id = runId ?? body.runId;
+  if (typeof id !== "string" || !runPattern.test(id))
+    throw new RunnerError(400, "invalid run ID");
+  const inboxDomain = typeof body.inboxDomain === "string" ? body.inboxDomain : undefined;
+  const context = {
+    runId: id,
+    input: body.input ?? {},
+    inbox: inboxDomain ? { address: (actor) => inboxAddress(actor, id, inboxDomain) } : undefined
+  };
+  switch (step) {
+    case undefined:
+      return { output: await scenario.prepare(context) ?? null };
+    case "verify":
+      await scenario.verify({ ...context, output: body.output });
+      return { verified: true };
+    case "cleanup":
+      await scenario.cleanup({ ...context, output: body.output ?? null });
+      return { cleaned: true };
+    default: {
+      if (!scenario.login)
+        throw new RunnerError(404, `scenario ${String(body.scenario)} does not provide login`);
+      if (typeof body.actor !== "string")
+        throw new RunnerError(400, "actor is required");
+      return { login: await scenario.login({ ...context, output: body.output, actor: body.actor }) };
+    }
+  }
+}
+function createRunner(options) {
+  if (!options.secret || options.secret.length < 32)
+    throw new Error("runner secret must be at least 32 characters");
+  return async (request) => {
+    if (!options.enabled)
+      return json({ error: "not found" }, 404);
+    const route = new URL(request.url).pathname.match(routePattern);
+    const expected = route?.[1] === "scenarios" ? "GET" : "POST";
+    if (!route || request.method !== expected)
+      return json({ error: "not found" }, 404);
+    const raw = await request.text();
+    if (!verifySignature(options.secret, request.headers, request.method, route[0], raw))
+      return json({ error: "invalid signature" }, 401);
+    if (route[1] === "scenarios") {
+      const { project, scenarios } = describeProject(options.project);
+      return json({ project, scenarios });
+    }
+    let body;
+    try {
+      body = JSON.parse(raw);
+    } catch {
+      return json({ error: "invalid JSON" }, 400);
+    }
+    try {
+      return json(await perform(options.project, route, body ?? {}));
+    } catch (error) {
+      if (error instanceof RunnerError)
+        return json({ error: error.message }, error.status);
+      return json({ error: error instanceof Error ? error.message : String(error) }, 422);
+    }
+  };
+}
+// packages/runner/src/client.ts
+import { defineProject } from "@condition-sh/core";
+function runnerUrl(value) {
+  const url = new URL(value);
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:"))
+    throw new Error("runner URL must use HTTPS");
+  if (url.username || url.password || url.search || url.hash)
+    throw new Error("runner URL must be a plain origin and path");
+  return url;
+}
+var notSent = /ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ConnectionRefused/;
+function neverSent(error) {
+  const { code, message } = error;
+  return notSent.test(`${code ?? ""} ${message ?? ""}`);
+}
+async function send(target, init, attempts = 3) {
+  for (let attempt = 1;; attempt++) {
+    try {
+      return await fetch(target, { ...init, signal: AbortSignal.timeout(120000) });
+    } catch (error) {
+      if (attempt >= attempts || !neverSent(error))
+        throw error;
+      await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
+    }
+  }
+}
+async function call({ url, secret }, method, route, body) {
+  const raw = body === undefined ? "" : JSON.stringify(body);
+  const base = runnerUrl(url);
+  const target = new URL(`${base.pathname.replace(/\/$/, "")}${route}`, base);
+  let response;
+  try {
+    response = await send(target, {
+      method,
+      redirect: "error",
+      headers: { "content-type": "application/json", ...sign(secret, method, route, raw) },
+      ...method === "GET" ? {} : { body: raw }
+    });
+  } catch (error) {
+    throw new Error(`runner unreachable: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  const result = await response.json().catch(() => ({}));
+  if (!response.ok)
+    throw new Error(`runner ${route.split("/").pop()}: ${response.status} ${result.error ?? "request failed"}`);
+  return result;
+}
+async function fetchScenarios(connection) {
+  const result = await call(connection, "GET", "/scenarios");
+  if (!Array.isArray(result.scenarios))
+    throw new Error("runner returned no scenario list");
+  return result;
+}
+function remoteScenario(connection, { name, description, input, actors }, inboxDomain) {
+  const present = (kind) => async (value) => (await call(connection, "POST", "/present", { scenario: name, kind, value })).presented;
+  const mail = (inbox) => inbox && inboxDomain ? { inboxDomain } : {};
+  return {
+    description,
+    ...input ? { input } : {},
+    ...actors ? { actors } : {},
+    async prepare({ runId, input: input2, inbox }) {
+      return (await call(connection, "POST", "/runs", { runId, scenario: name, input: input2, ...mail(inbox) })).output;
+    },
+    async verify({ runId, input: input2, output, inbox }) {
+      await call(connection, "POST", `/runs/${runId}/verify`, { scenario: name, input: input2, output, ...mail(inbox) });
+    },
+    async cleanup({ runId, input: input2, output, inbox }) {
+      await call(connection, "POST", `/runs/${runId}/cleanup`, { scenario: name, input: input2, output, ...mail(inbox) });
+    },
+    async login({ runId, input: input2, output, actor, inbox }) {
+      return (await call(connection, "POST", `/runs/${runId}/login`, { scenario: name, input: input2, output, actor, ...mail(inbox) })).login;
+    },
+    present: present("output"),
+    presentInput: present("input")
+  };
+}
+function remoteProject(options) {
+  runnerUrl(options.url);
+  return defineProject({
+    name: options.name,
+    inbox: options.inbox,
+    scenarios: Object.fromEntries(options.scenarios.map((scenario) => [
+      scenario.name,
+      remoteScenario(options, scenario, options.inbox?.domain)
+    ]))
+  });
+}
+export {
+  verifySignature,
+  sign,
+  runnerUrl,
+  remoteProject,
+  fetchScenarios,
+  createRunner
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@condition-sh/runner",
+  "version": "2026.9.1",
+  "description": "Mount a signed Condition runner inside your app.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rad-Soft/condition.git",
+    "directory": "packages/runner"
+  },
+  "homepage": "https://condition.sh",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@condition-sh/core": "^2026.9.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types/client.d.ts

@@ -0,0 +1,17 @@
+import { type Project, type RemoteInbox, type ScenarioSummary } from "@condition-sh/core";
+export type RemoteScenario = ScenarioSummary;
+type Connection = {
+    url: string;
+    secret: string;
+};
+export declare function runnerUrl(value: string): URL;
+export declare function fetchScenarios(connection: Connection): Promise<{
+    project: string;
+    scenarios: RemoteScenario[];
+}>;
+export declare function remoteProject(options: Connection & {
+    name: string;
+    scenarios: RemoteScenario[];
+    inbox?: RemoteInbox;
+}): Project;
+export {};

package/types/index.d.ts

@@ -0,0 +1,5 @@
+export { createRunner } from "./server.js";
+export type { RunnerOptions } from "./server.js";
+export { fetchScenarios, remoteProject, runnerUrl } from "./client.js";
+export type { RemoteScenario } from "./client.js";
+export { sign, verifySignature } from "./signature.js";

package/types/server.d.ts

@@ -0,0 +1,7 @@
+import { type Project } from "@condition-sh/core";
+export type RunnerOptions = {
+    project: Project;
+    secret: string;
+    enabled: boolean;
+};
+export declare function createRunner(options: RunnerOptions): (request: Request) => Promise<Response>;

package/types/signature.d.ts

@@ -0,0 +1,2 @@
+export declare function sign(secret: string, method: string, route: string, body: string, now?: number): Record<string, string>;
+export declare function verifySignature(secret: string, headers: Headers, method: string, route: string, body: string, now?: number): boolean;