rainskills 0.1.42 → 0.1.44

package/README.md

@@ -1,49 +1,165 @@
-# Rainskills
+# RainSkills
 
-> 让你的 AI Agent 把应用真正跑起来。
+> 让你的 AI Agent 把当前项目部署上线，并验证页面和 API。
 
-Rainskills 是一组开源 Agent Skills，让 Codex、Claude Code、Pi Agent、
-DeepSeek Harness、WorkBuddy 和 Hermes Agent 能够完成应用识别、部署、
-排错、交付验证、版本管理和回滚。
+RainSkills 是一组开源 Agent Skills，让 Codex、Claude Code、Pi Agent、
+DeepSeek Harness、WorkBuddy 和 Hermes Agent 能够继续完成应用部署、
+故障排查、交付验证、版本管理和回滚。
 
-安装后，你只需要告诉 Agent：
+它从 Agent 已经理解的当前项目出发，把前端、后端、数据库、缓存、
+端口和存储组织成 Rainbond 应用。应用可以运行在 Rainbond Cloud、
+你自己的服务器或 Kubernetes 中。
 
-> 帮我把当前项目部署上线，并验证页面和 API。
+**AI 负责生成，RainSkills 负责交付，Rainbond 负责持续运行。**
 
-Rainskills 会分析项目结构、组件和依赖，连接 Rainbond Cloud、已有 Rainbond，
-或者在本机和服务器上安装 Rainbond，然后继续完成部署与验证。
+[产品介绍](https://www.rainbond.com/rainskills) ·
+[安装与使用](https://www.rainbond.com/docs/ai/rainskills) ·
+[视频教程](https://www.rainbond.com/videos/rainskills-ai-deploy) ·
+[Rainbond Cloud](https://run.rainbond.com)
 
-**AI 负责生成，Rainskills 负责部署，Rainbond 负责持续运行。**
+## 为什么使用 RainSkills
 
-[快速安装](https://www.rainbond.com) ·
-[使用文档](https://www.rainbond.com/docs/ai/rainskills) · [Rainbond Cloud](https://run.rainbond.com)
+AI Agent 已经理解了代码、依赖和项目结构。进入部署阶段后，如果改用临时脚本或直接 SSH，
+这些上下文通常需要重新整理，部署结果也很难沉淀为可以持续维护的应用。
 
-## 快速安装
+| 对比维度 | Agent 直接 SSH / 临时脚本 | RainSkills + Rainbond |
+| --- | --- | --- |
+| 工作起点 | 重新整理服务器、端口、依赖和命令 | 直接复用当前项目上下文 |
+| 应用结构 | 人工拼装进程、数据库、网络和存储 | 用应用拓扑管理组件与依赖 |
+| 失败排查 | 手工寻找构建、容器和网关日志 | Agent 读取构建日志、运行日志、Pod 和平台事件 |
+| 完成标准 | 命令成功或进程已经启动 | 页面和 API 完成实际访问验证 |
+| 权限边界 | Agent 通常直接持有 SSH 或生产凭据 | 浏览器授权、受控工具调用和高风险操作确认 |
+| 后续维护 | 继续维护脚本和服务器差异 | 在同一应用上升级、快照、发布和回滚 |
 
-从 Skill 市场安装：
+RainSkills 更适合多组件应用、自托管环境、私有化交付，以及需要持续排障和版本管理的项目。
+
+## RainSkills 如何工作
+
+```text
+当前项目或部署目标
+  → Codex、Claude Code 等 AI Agent
+  → RainSkills 选择对应的部署、排障或验证 Skill
+  → 首次需要时选择并连接一个 Rainbond 运行环境
+  → Rainbond 构建并运行应用
+  → RainSkills 验证页面、API 和最终访问地址
+```
+
+RainSkills 安装与运行环境连接是两个阶段。安装完成后可以直接提出部署任务；
+第一次需要 Rainbond 时，Agent 再引导你选择 Cloud、已有私有环境、本机或服务器。
+
+![RainSkills 在 AI Agent 中完成应用部署并返回访问地址](https://grstatic.tos-cn-beijing.volces.com/wechat/rainskills/rainskills-deploy.png)
+
+## 快速开始
+
+使用 Skill 市场安装：
 
 ```bash
 npx skills add goodrain/rainskills
 ```
 
-或者直接运行：
+或者直接运行官方安装器：
 
 ```bash
 npx --yes rainskills
 ```
 
-安装后，在项目目录告诉 Agent：
+DeepSeek Harness 用户也可以把 RainSkills bootstrap 作为 profile bundle 安装：
+
+```bash
+dsh plugin --profile web add rainskills
+```
+
+安装后调用 `/rainskills`，或直接告诉 Agent“安装 RainSkills”。该 bundle 只注册
+bootstrap Skill；完整的 `rainbond-*` Skills 仍由官方安装器统一安装和更新。
+
+`npx` 安装方式需要 Node.js 18 或更高版本。建议使用仍在维护的 Node.js 22 或 24。
+
+安装完成后，在项目目录告诉 Agent：
+
+```text
+帮我部署当前项目，并验证页面和 API。
+```
+
+如果还没有可用的 Rainbond，Agent 会在第一次需要运行环境时让你选择 Cloud、
+已有私有环境、本机或服务器，不会在安装 Skill 时替你决定目标环境。
+
+## 可以直接告诉 Agent 什么
+
+- `帮我部署当前项目`
+- `帮我部署这个 Git 仓库`
+- `帮我通过镜像或安装包部署应用`
+- `帮我安装一个应用模板`
+- `帮我部署 Dify、n8n 或 Harbor`
+- `帮我检查 backend 为什么构建失败`
+- `确认当前应用是否已经交付成功，并给我访问地址`
+- `给当前应用创建快照`
+- `把当前应用回滚到上一个快照`
+
+## 支持范围
+
+### AI Agent
+
+- Codex
+- Claude Code
+- Pi Agent
+- DeepSeek Harness
+- WorkBuddy
+- Hermes Agent
+
+### 项目来源
+
+- 当前本地项目
+- 普通 Git 仓库
+- 本地软件包
+- 私有容器镜像或单镜像组件
+- Compose、Helm 或多镜像描述
+- Dify、n8n、Harbor 等第三方开源应用
+- Rainbond 应用模板
+
+Compose、Helm 和第三方应用中的特权容器、Operator、CRD、Job、主机网络或主机目录等语义，
+需要根据当前 Rainbond 能力单独判断，不承诺原样转换所有 Kubernetes 配置。
+
+### 运行环境
+
+- Rainbond Cloud
+- 已经运行的私有 Rainbond
+- 本机 Rainbond
+- 独立服务器上的 Rainbond
+- 已有 Kubernetes 集群中的 Rainbond
+
+## 安全和权限边界
+
+- 通过浏览器完成 Rainbond 授权，不要求在聊天中粘贴 JWT、密码或私钥。
+- 创建、更新和删除资源前核对目标企业、团队、应用和组件。
+- 删除资源、平台安装、数据变更和其他高风险操作需要明确确认。
+- Rainbond 授权凭据保存在受保护的本地状态中，不写入项目文件。
+- 部署完成后继续验证组件、页面和 API，不把命令成功当作交付完成。
+
+用户明确选择在独立服务器安装 Rainbond 时，受控安装流程可能使用 SSH。
+应用部署和后续管理仍通过 Rainbond 应用模型完成，而不是依赖散落的服务器命令。
+
+## 适合哪些场景
+
+- AI Agent 已经写完或修改了项目，需要继续部署。
+- 项目包含前端、后端、数据库、缓存或异步任务。
+- 应用需要运行在自己的服务器、私有云或 Kubernetes 中。
+- 部署完成后仍需日志、升级、快照、发布和回滚。
+- 团队需要复用私有化或客户现场的交付流程。
+
+## 哪些场景可能不需要 RainSkills
 
-> 帮我部署当前项目，并验证页面和 API。
+- 只发布一个接受完全托管的纯静态页面。
+- 团队已经有成熟的内部开发平台和 GitOps 流程。
+- 只是一次性的本地实验，不需要持续运行、排障或回滚。
 
-## Rainskills 可以做什么
+## 文档与支持
 
-- 识别本地项目、Git 仓库、镜像和开源软件
-- 分析前端、后端、数据库及组件依赖
-- 自动完成应用构建和部署
-- 根据事件和日志排查部署故障
-- 验证组件状态、访问地址、页面和 API
-- 管理应用版本、升级、快照和回滚
+- [RainSkills 产品介绍](https://www.rainbond.com/rainskills)
+- [安装与使用文档](https://www.rainbond.com/docs/ai/rainskills)
+- [安装与连接视频教程](https://www.rainbond.com/videos/rainskills-ai-deploy)
+- [市场上架 Runbook](https://github.com/goodrain/rainskills/blob/main/docs/marketplace-publishing.md)
+- [Rainbond 安装文档](https://www.rainbond.com/docs/installation)
+- [提交问题](https://github.com/goodrain/rainskills/issues)
 
 ## License
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rainskills
-description: Use when a user asks to install, set up, initialize, update, repair, start using Rainskills, or connect, reconnect, inspect, or replace the single Rainskills runtime.
+description: Install, update, repair, connect, reconnect, inspect, or replace the single Rainskills runtime. Use for Rainskills setup and onboarding, not application deployment.
 ---
 
 # Rainskills
@@ -9,7 +9,7 @@ This is the single marketplace entry for the complete Rainskills product. The in
 
 ## Initialize
 
-1. Detect the current host client and map it to exactly one supported installer target: Codex=`codex`, Claude Code=`claude`, Pi Agent=`pi`, DeepSeek Harness=`dsh`, WorkBuddy=`workbuddy`, or Hermes Agent=`hermes`. All six use the same CLI profile, installed Skills, and protected local Rainskills CLI; none requires a separate client MCP adapter. DeepSeek Harness installs to `$DSH_HOME/skills` (default `~/.dsh/skills`). WorkBuddy installs to `$WORKBUDDY_CONFIG_DIR/skills` (default `~/.workbuddy-ai/skills`). Hermes Agent installs to `$HERMES_HOME/skills` (default `~/.hermes/skills`); `AI_AGENT=hermes-agent` or `HERMES_AGENT=true` is a reliable fallback when the host must be detected from a terminal subprocess. The macOS, Linux, and WSL installer intentionally does not support OpenClaw; report that limitation instead of invoking an unsupported target. Do not ask the user which supported client they are currently using. If the host cannot be determined reliably, omit the target and let the installer ask.
+1. Detect the current host client and map it to exactly one supported installer target: Codex=`codex`, Claude Code=`claude`, Pi Agent=`pi`, DeepSeek Harness=`dsh`, WorkBuddy=`workbuddy`, or Hermes Agent=`hermes`. All six use the same CLI profile, installed Skills, and protected local Rainskills CLI; none requires a separate client MCP adapter. DeepSeek Harness installs to `$DSH_HOME/skills` (default `~/.dsh/skills`). WorkBuddy installs to `$WORKBUDDY_CONFIG_DIR/skills` (default `~/.workbuddy/skills`). Hermes Agent installs to `$HERMES_HOME/skills` (default `~/.hermes/skills`); `AI_AGENT=hermes-agent` or `HERMES_AGENT=true` is a reliable fallback when the host must be detected from a terminal subprocess. The macOS, Linux, and WSL installer intentionally does not support OpenClaw; report that limitation instead of invoking an unsupported target. Do not ask the user which supported client they are currently using. If the host cannot be determined reliably, omit the target and let the installer ask.
 2. Resolve the directory containing this `SKILL.md`. On native Windows, if the adjacent `bin/rainskills.js` exists, run it by absolute path with the detected target in an attached interactive terminal: `node <skill-directory>/bin/rainskills.js <target>`. On macOS, Linux, or WSL, if the adjacent `install.sh` exists, run `bash <skill-directory>/install.sh <target>` the same way. Do not replace the installer with manual file copies.
 3. Keep stdin, stdout, and stderr attached. When `RAINSKILLS_USER_INPUT_REQUIRED` appears, pause for that installer choice. If the installer emits `rainskills.next-action.v1`, execute only its fixed `argv` through the same launcher; never evaluate output as a shell command. If the adjacent `bin/rainskills.js` exists, use it for fixed next actions; otherwise use the same versioned npm package fallback described below.
 4. Stay attached until every independent Skill is installed. Do not select, connect, or configure an application runtime during installation. In the user-facing response, output only the fixed completion message below.
@@ -54,7 +54,7 @@ Hermes Agent 中必须使用 `terminal` 以 `background=true` 启动授权命令
 
 DeepSeek Harness 和 WorkBuddy 也必须保持原命令附着直到退出；如果宿主把长命令转成持久终端或后台任务，只能轮询该原始命令句柄，不得另起 `runtime status` 推测授权结果。WorkBuddy 安装后若当前任务的 Skill 清单尚未刷新，在下一条业务动作前先刷新 Skill 列表或新建任务，不得退回内置 Sites 代替 Rainbond 部署。
 
-Rainskills 只保存一个全局运行环境，不维护环境列表、名称、默认值或环境 ID。使用固定 launcher `node <home>/.rainbond/lib/rainskills/bin/rainskills.js`（运行包版本 `rainskills@0.1.42`）：
+Rainskills 只保存一个全局运行环境，不维护环境列表、名称、默认值或环境 ID。使用固定 launcher `node <home>/.rainbond/lib/rainskills/bin/rainskills.js`（运行包版本 `rainskills@0.1.44`）：
 
 - 状态：执行 `runtime status --json`。
 - 首次连接：执行 `runtime connect <target> --saas` 或 `runtime connect <target> --rainbond-url <Console origin>`。

package/bin/delivery-probe.js

@@ -0,0 +1,306 @@
+"use strict";
+
+const dns = require("node:dns").promises;
+const http = require("node:http");
+const https = require("node:https");
+const net = require("node:net");
+
+const MAX_REDIRECTS = 3;
+const CONNECT_TIMEOUT_MS = 5_000;
+const TOTAL_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 256 * 1024;
+const MAX_URL_LENGTH = 4_096;
+const POLICY_VERSION = "rainskills.delivery-probe-policy.v1";
+
+function isPublicIpv4(address) {
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return false;
+  }
+  const [a, b] = parts;
+  if (a === 0 || a === 10 || a === 127 || a >= 224) return false;
+  if (a === 100 && b >= 64 && b <= 127) return false;
+  if (a === 169 && b === 254) return false;
+  if (a === 172 && b >= 16 && b <= 31) return false;
+  if (a === 192 && (b === 0 || b === 168)) return false;
+  if (a === 192 && b === 0 && parts[2] === 2) return false;
+  if (a === 198 && (b === 18 || b === 19 || b === 51)) return false;
+  if (a === 203 && b === 0 && parts[2] === 113) return false;
+  return true;
+}
+
+function ipv6Parts(address) {
+  let normalized = address.toLowerCase().split("%", 1)[0];
+  const dotted = normalized.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    if (!net.isIPv4(dotted[1])) return null;
+    const octets = dotted[1].split(".").map(Number);
+    normalized = `${normalized.slice(0, -dotted[1].length)}${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+  }
+  const halves = normalized.split("::");
+  if (halves.length > 2) return null;
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  const missing = 8 - left.length - right.length;
+  if ((halves.length === 1 && missing !== 0) || missing < 0) return null;
+  const tokens = [...left, ...Array(missing).fill("0"), ...right];
+  if (tokens.length !== 8 || tokens.some((token) => !/^[0-9a-f]{1,4}$/.test(token))) return null;
+  return tokens.map((token) => Number.parseInt(token, 16));
+}
+
+function embeddedIpv4(parts, offset) {
+  return [
+    parts[offset] >> 8,
+    parts[offset] & 0xff,
+    parts[offset + 1] >> 8,
+    parts[offset + 1] & 0xff,
+  ].join(".");
+}
+
+function isPublicIpv6(address) {
+  const parts = ipv6Parts(address);
+  if (!parts) return false;
+  if (parts.every((part) => part === 0)) return false;
+  if (parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1) return false;
+  if ((parts[0] & 0xfe00) === 0xfc00) return false;
+  if ((parts[0] & 0xffc0) === 0xfe80) return false;
+  if ((parts[0] & 0xff00) === 0xff00) return false;
+  if (parts[0] === 0x0100 && parts.slice(1, 4).every((part) => part === 0)) return false;
+  if (parts[0] === 0x2001 && parts[1] === 0x0000) return false;
+  if (parts[0] === 0x2001 && (parts[1] & 0xfff0) === 0x0010) return false;
+  if (parts[0] === 0x2001 && (parts[1] & 0xfff0) === 0x0020) return false;
+  if (parts[0] === 0x2001 && parts[1] === 0x0002) return false;
+  if (parts[0] === 0x2001 && parts[1] === 0x0db8) return false;
+  if ((parts[0] & 0xfff0) === 0x3ff0) return false;
+  if (parts.slice(0, 5).every((part) => part === 0) && parts[5] === 0xffff) {
+    return isPublicIpv4(embeddedIpv4(parts, 6));
+  }
+  if (parts.slice(0, 6).every((part) => part === 0)) {
+    return isPublicIpv4(embeddedIpv4(parts, 6));
+  }
+  if (parts[0] === 0x0064 && parts[1] === 0xff9b && parts.slice(2, 6).every((part) => part === 0)) {
+    return isPublicIpv4(embeddedIpv4(parts, 6));
+  }
+  if (parts[0] === 0x2002) return isPublicIpv4(embeddedIpv4(parts, 1));
+  return true;
+}
+
+function isPublicAddress(address) {
+  const family = net.isIP(address);
+  if (family === 4) return isPublicIpv4(address);
+  if (family === 6) return isPublicIpv6(address);
+  return false;
+}
+
+function normalizedHostname(url) {
+  return url.hostname.replace(/^\[|\]$/g, "");
+}
+
+async function defaultResolveHost(hostname) {
+  const records = await dns.lookup(hostname, { all: true, verbatim: true });
+  return records.map((record) => record.address);
+}
+
+function defaultRequestUrl(url, {
+  method,
+  address,
+  headers,
+  connectTimeoutMs = CONNECT_TIMEOUT_MS,
+  totalTimeoutMs = TOTAL_TIMEOUT_MS,
+  maxBodyBytes = MAX_BODY_BYTES,
+}) {
+  const client = url.protocol === "https:" ? https : http;
+  return new Promise((resolve) => {
+    let settled = false;
+    let connectTimer;
+    let totalTimer;
+    const finish = (result, request) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      clearTimeout(totalTimer);
+      if (request && !request.destroyed) request.destroy();
+      resolve(result);
+    };
+    const request = client.request(url, {
+      method,
+      headers,
+      redirect: "manual",
+      lookup: (_hostname, options, callback) => {
+        const family = net.isIP(address);
+        if (options && options.all) {
+          callback(null, [{ address, family }]);
+          return;
+        }
+        callback(null, address, family);
+      },
+    }, (response) => {
+      const statusCode = response.statusCode || 0;
+      const location = response.headers.location;
+      const contentType = String(response.headers["content-type"] || "");
+      const contentLength = Number(response.headers["content-length"] || 0);
+      if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
+        response.resume();
+        finish({ error: "body_too_large" }, request);
+        return;
+      }
+      if (method === "HEAD" || (statusCode >= 300 && statusCode < 400)) {
+        response.resume();
+        finish({ statusCode, location, contentType, bodyBytes: 0 }, request);
+        return;
+      }
+      let bodyBytes = 0;
+      response.on("data", (chunk) => {
+        bodyBytes += chunk.length;
+        if (bodyBytes > maxBodyBytes) finish({ error: "body_too_large" }, request);
+      });
+      response.on("end", () => finish({ statusCode, location, contentType, bodyBytes }, request));
+      response.on("error", () => finish({ error: "response_error" }, request));
+    });
+    request.on("socket", (socket) => {
+      if (!socket.connecting) return;
+      connectTimer = setTimeout(() => finish({ error: "timeout" }, request), connectTimeoutMs);
+      socket.once(url.protocol === "https:" ? "secureConnect" : "connect", () => clearTimeout(connectTimer));
+    });
+    request.on("error", (error) => finish({ error: error.code === "ETIMEDOUT" ? "timeout" : "request_error" }, request));
+    totalTimer = setTimeout(() => finish({ error: "timeout" }, request), totalTimeoutMs);
+    request.end();
+  });
+}
+
+function parseTarget(value) {
+  if (typeof value !== "string" || !value || value.length > MAX_URL_LENGTH) return null;
+  let url;
+  try {
+    url = new URL(value);
+  } catch (_error) {
+    return null;
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) return null;
+  return url;
+}
+
+function createDeliveryProbe({
+  resolveHost = defaultResolveHost,
+  requestUrl = defaultRequestUrl,
+} = {}) {
+  return async function probe(input) {
+    const allowedInputKeys = new Set(["policy_version", "url", "method"]);
+    const validShape = input && typeof input === "object" && !Array.isArray(input)
+      && Object.keys(input).every((key) => allowedInputKeys.has(key));
+    const method = input?.method;
+    let current = parseTarget(input?.url);
+    const candidateUrl = current ? current.href : String(input?.url || "");
+    if (!validShape || !current || !["HEAD", "GET"].includes(method) || input?.policy_version !== POLICY_VERSION) {
+      return { policy_version: POLICY_VERSION, status: "rejected", reason: "unsafe_url_or_method", candidate_url: candidateUrl };
+    }
+    const redirects = [];
+    let prefetchedResolution = null;
+
+    const resolveSafeAddresses = async (url) => {
+      const hostname = normalizedHostname(url);
+      try {
+        const addresses = net.isIP(hostname) ? [hostname] : await resolveHost(hostname);
+        if (!Array.isArray(addresses) || !addresses.length || addresses.some((address) => !isPublicAddress(address))) {
+          return { error: "non_public_address" };
+        }
+        return { addresses };
+      } catch (_error) {
+        return { error: "dns_error" };
+      }
+    };
+
+    for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount += 1) {
+      const resolved = prefetchedResolution || await resolveSafeAddresses(current);
+      prefetchedResolution = null;
+      if (resolved.error) {
+        return {
+          policy_version: POLICY_VERSION,
+          status: resolved.error === "dns_error" ? "failed" : "rejected",
+          reason: resolved.error,
+          candidate_url: candidateUrl,
+        };
+      }
+
+      const headers = Object.freeze({ Accept: "*/*", "User-Agent": "rainskills-delivery-probe/1" });
+      const response = await requestUrl(current, {
+        method,
+        address: resolved.addresses[0],
+        headers,
+        connectTimeoutMs: CONNECT_TIMEOUT_MS,
+        totalTimeoutMs: TOTAL_TIMEOUT_MS,
+        maxBodyBytes: MAX_BODY_BYTES,
+      });
+      if (response?.error) {
+        return { policy_version: POLICY_VERSION, status: "failed", reason: response.error, candidate_url: candidateUrl };
+      }
+
+      const statusCode = Number(response?.statusCode || 0);
+      if (statusCode >= 300 && statusCode < 400) {
+        if (!response.location) {
+          return { policy_version: POLICY_VERSION, status: "failed", reason: "redirect_without_location", candidate_url: candidateUrl };
+        }
+        if (redirectCount === MAX_REDIRECTS) {
+          return { policy_version: POLICY_VERSION, status: "failed", reason: "too_many_redirects", candidate_url: candidateUrl };
+        }
+        let next;
+        try {
+          next = parseTarget(new URL(response.location, current).href);
+        } catch (_error) {
+          next = null;
+        }
+        if (!next) return { policy_version: POLICY_VERSION, status: "rejected", reason: "unsafe_redirect", candidate_url: candidateUrl };
+        const nextResolved = await resolveSafeAddresses(next);
+        if (nextResolved.error) {
+          return { policy_version: POLICY_VERSION, status: "rejected", reason: "unsafe_redirect", candidate_url: candidateUrl };
+        }
+        if (current.protocol === "https:" && next.protocol !== "https:") {
+          return { policy_version: POLICY_VERSION, status: "rejected", reason: "redirect_downgrade", candidate_url: candidateUrl };
+        }
+        const sameEndpoint = next.host === current.host && next.protocol === current.protocol;
+        const httpUpgrade = current.protocol === "http:"
+          && next.protocol === "https:"
+          && normalizedHostname(next) === normalizedHostname(current)
+          && (current.port || "80") === "80"
+          && (next.port || "443") === "443";
+        if (!sameEndpoint && !httpUpgrade) {
+          return {
+            policy_version: POLICY_VERSION,
+            status: "manual_validation_required",
+            reason: "cross_host_redirect",
+            candidate_url: candidateUrl,
+            redirect_target: next.href,
+          };
+        }
+        redirects.push(next.href);
+        current = next;
+        prefetchedResolution = nextResolved;
+        continue;
+      }
+
+      return {
+        policy_version: POLICY_VERSION,
+        status: statusCode >= 200 && statusCode < 400 ? "verified" : "failed",
+        reason: statusCode >= 200 && statusCode < 400 ? null : "http_status",
+        candidate_url: candidateUrl,
+        final_url: current.href,
+        status_code: statusCode,
+        content_type: String(response.contentType || ""),
+        body_bytes: Number(response.bodyBytes || 0),
+        redirects,
+      };
+    }
+    return { policy_version: POLICY_VERSION, status: "failed", reason: "too_many_redirects", candidate_url: candidateUrl };
+  };
+}
+
+module.exports = {
+  CONNECT_TIMEOUT_MS,
+  MAX_BODY_BYTES,
+  MAX_REDIRECTS,
+  TOTAL_TIMEOUT_MS,
+  POLICY_VERSION,
+  createDeliveryProbe,
+  defaultRequestUrl,
+  isPublicAddress,
+};

package/bin/handoff-context.js

@@ -0,0 +1,151 @@
+"use strict";
+
+const { createHash } = require("node:crypto");
+
+const SCHEMA = "rainskills.handoff-context.v1";
+const PROFILE = new Set(["cli", "embedded"]);
+const SOURCE_KIND = new Set(["source", "image", "package", "template", null]);
+const RUNTIME_STATE = new Set([
+  "topology_missing", "topology_building", "runtime_unhealthy", "runtime_healthy",
+  "capacity_blocked", "code_or_build_handoff_needed",
+]);
+const NEXT_PHASE = new Set(["init", "bootstrap", "troubleshoot", "verify", "stop"]);
+const CONTEXT_KEYS = Object.freeze([
+  "schema", "producer", "profile", "observed_at", "enterprise_id", "team_id",
+  "team_name", "region_name", "app_id", "app_name", "runtime_fingerprint",
+  "identity_fingerprint", "snapshot_revision", "source_kind", "runtime_state",
+  "next_phase", "invalidation_reason",
+]);
+const CREATE_KEYS = new Set([
+  "producer", "profile", "observed_at", "enterprise_id", "team_id", "team_name",
+  "region_name", "app_id", "app_name", "endpoint", "runtime_revision",
+  "snapshot_revision", "source_kind", "runtime_state", "next_phase", "invalidation_reason",
+]);
+const SENSITIVE_KEY = /(?:jwt|token|password|secret|credential|confirmation|raw.?log|tool.?output)/i;
+const SHA256 = /^[a-f0-9]{64}$/;
+const SKILL_ID = /^rainbond-[a-z0-9-]+$/;
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+function fingerprint(value) {
+  return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}
+
+function assertString(value, label, nullable = false) {
+  if (nullable && value === null) return;
+  if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string`);
+}
+
+function runtimeIdentity(value) {
+  return {
+    profile: value.profile,
+    endpoint: value.endpoint,
+    runtime_revision: value.runtime_revision,
+  };
+}
+
+function workspaceIdentity(value) {
+  return {
+    enterprise_id: value.enterprise_id,
+    team_id: value.team_id,
+    region_name: value.region_name,
+    app_id: value.app_id,
+  };
+}
+
+function validateCreationInput(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("handoff input must be an object");
+  for (const key of Object.keys(value)) {
+    if (SENSITIVE_KEY.test(key)) throw new Error("sensitive handoff fields are forbidden");
+    if (!CREATE_KEYS.has(key)) throw new Error(`unknown handoff field: ${key}`);
+  }
+  if (!SKILL_ID.test(value.producer || "")) throw new Error("producer is invalid");
+  if (!PROFILE.has(value.profile)) throw new Error("profile is invalid");
+  if (!Number.isFinite(Date.parse(value.observed_at))) throw new Error("observed_at is invalid");
+  for (const key of ["enterprise_id", "team_id", "team_name", "region_name", "endpoint", "runtime_revision"]) assertString(value[key], key);
+  if (!(value.app_id === null || (Number.isInteger(value.app_id) && value.app_id > 0))) throw new Error("app_id is invalid");
+  assertString(value.app_name, "app_name", true);
+  assertString(value.snapshot_revision, "snapshot_revision", true);
+  if (!SOURCE_KIND.has(value.source_kind)) throw new Error("source_kind is invalid");
+  if (!RUNTIME_STATE.has(value.runtime_state)) throw new Error("runtime_state is invalid");
+  if (!NEXT_PHASE.has(value.next_phase)) throw new Error("next_phase is invalid");
+  assertString(value.invalidation_reason, "invalidation_reason", true);
+}
+
+function validateContextShape(context) {
+  if (!context || typeof context !== "object" || Array.isArray(context)) throw new Error("context must be an object");
+  const keys = Object.keys(context).sort();
+  if (JSON.stringify(keys) !== JSON.stringify([...CONTEXT_KEYS].sort())) throw new Error("context fields are invalid");
+  if (context.schema !== SCHEMA || !SKILL_ID.test(context.producer || "") || !PROFILE.has(context.profile)) throw new Error("context identity is invalid");
+  if (!Number.isFinite(Date.parse(context.observed_at))) throw new Error("context observed_at is invalid");
+  for (const key of ["enterprise_id", "team_id", "team_name", "region_name"]) assertString(context[key], key);
+  if (!(context.app_id === null || (Number.isInteger(context.app_id) && context.app_id > 0))) throw new Error("context app_id is invalid");
+  assertString(context.app_name, "app_name", true);
+  if (!SHA256.test(context.runtime_fingerprint) || !SHA256.test(context.identity_fingerprint)) throw new Error("context fingerprint is invalid");
+  assertString(context.snapshot_revision, "snapshot_revision", true);
+  if (!SOURCE_KIND.has(context.source_kind) || !RUNTIME_STATE.has(context.runtime_state) || !NEXT_PHASE.has(context.next_phase)) throw new Error("context state is invalid");
+  assertString(context.invalidation_reason, "invalidation_reason", true);
+}
+
+function createHandoffContext(value) {
+  validateCreationInput(value);
+  return {
+    schema: SCHEMA,
+    producer: value.producer,
+    profile: value.profile,
+    observed_at: new Date(value.observed_at).toISOString(),
+    enterprise_id: value.enterprise_id,
+    team_id: value.team_id,
+    team_name: value.team_name,
+    region_name: value.region_name,
+    app_id: value.app_id,
+    app_name: value.app_name,
+    runtime_fingerprint: fingerprint(runtimeIdentity(value)),
+    identity_fingerprint: fingerprint(workspaceIdentity(value)),
+    snapshot_revision: value.snapshot_revision,
+    source_kind: value.source_kind,
+    runtime_state: value.runtime_state,
+    next_phase: value.next_phase,
+    invalidation_reason: value.invalidation_reason,
+  };
+}
+
+function validateHandoffContext(context, { current, signal = null, now = Date.now(), maxAgeMs = 30_000 } = {}) {
+  try {
+    validateContextShape(context);
+    validateCreationInput({
+      producer: context.producer,
+      observed_at: context.observed_at,
+      team_name: context.team_name,
+      app_name: context.app_name,
+      snapshot_revision: context.snapshot_revision,
+      source_kind: context.source_kind,
+      runtime_state: context.runtime_state,
+      next_phase: context.next_phase,
+      invalidation_reason: context.invalidation_reason,
+      ...current,
+    });
+  } catch (_error) {
+    return { valid: false, reason: "invalid-context" };
+  }
+  const signalReasons = new Set(["runtime-reconnect", "unauthorized-401", "forbidden-403", "not-found", "revision-conflict"]);
+  if (signal && signalReasons.has(signal)) return { valid: false, reason: signal };
+  if (fingerprint(runtimeIdentity(current)) !== context.runtime_fingerprint) return { valid: false, reason: "runtime-identity-changed" };
+  if (fingerprint(workspaceIdentity(current)) !== context.identity_fingerprint) return { valid: false, reason: "workspace-identity-changed" };
+  if (current.source_kind !== context.source_kind) return { valid: false, reason: "source-strategy-changed" };
+  if (current.snapshot_revision !== context.snapshot_revision) return { valid: false, reason: "snapshot-revision-changed" };
+  if (now - Date.parse(context.observed_at) > maxAgeMs) return { valid: false, reason: "mutable-state-stale" };
+  if (context.invalidation_reason) return { valid: false, reason: context.invalidation_reason };
+  return { valid: true, reason: null };
+}
+
+module.exports = {
+  createHandoffContext,
+  validateHandoffContext,
+};