dsh-plugin-update 0.2.0 → 0.3.0

package/dist/redaction.d.ts

@@ -0,0 +1,120 @@
+/**
+ * src/redaction.ts —— 失败详情脱敏规则表（#19，承接 #6；#24 单源收敛）。
+ *
+ * 五条具名规则，顺序固定。处理方式只有两种：替换成占位符，或丢弃整项。
+ * 判据是机械的：秘密片段的起止能否被规则无歧义定位（与 #5 风险序一致：误导 > 缺失）。
+ *
+ * - 绝对路径 → 替换为 `<路径>`（#5 冻结，不动）。路径终止于空白，起止唯一。
+ * - URL 用户信息（scheme://user:pass@）→ 丢弃整项。密码自身可能含 `@`，起止不唯一。
+ * - 令牌前缀（npm / GitHub / sk / Bearer 形状）→ 替换为 `<脱敏>`。
+ * - 密码键值对（token / password / api_key / cookie 形状）→ 替换为 `<脱敏>`（保留键名与分隔符，只换值）。
+ * - 邮箱 → 替换为 `<脱敏>`。
+ *
+ * 只有两个占位符：`<路径>` 与 `<脱敏>`。不为每种秘密建一套分类学。
+ *
+ * 处理顺序固定为：压平空白 → URL 用户信息（命中即整项丢弃）→ 路径 → 令牌 → 键值对 → 邮箱
+ * → 空白边界封顶（封顶后不再扫描）。顺序的目的是输出确定性（同一输入两次运行逐字节相同），
+ * 封顶在脱敏之后，且封顶之后不再扫描。
+ *
+ * 本模块是唯一的规则源（#24 单源收敛）：宿主侧（store.ts 经 sanitizeDetail）与面板侧
+ * （panel.ts 经 redactForCopy）同缝消费，不再各存一份 PANEL_* 镜像。面板侧的复制预算
+ * 1500 字也在此单源定义（COPY_BUDGET_CHARS），面板只转出口。
+ * 本模块零 Node 导入（只用 URL / TextEncoder 全局），宿主与浏览器闭包两边都进得去。
+ *
+ * 绝不外发的三样按构造问题处理，不在文字层拦：
+ * 响应正文与安装输出全文（入口不接受此类参数）、调用栈（不构造）、内网主机名
+ * （不是高精度标记，是猜的——源信息隐私由源主机名字段承担，不在文字层拦）。
+ *
+ * 已知缺口（显式 known-gap，不静默修）：`file:///tmp/x` 三斜杠形状会被当成 URL 放过
+ * （`file://` 的前置带着冒号），见 KNOWN_GAP_FILE_URL_PREFIX 与测试里的显式断言。
+ * UNC 反斜杠本轮已覆盖（#19 落地时）。
+ */
+/** 失败详情封顶字数：回给用户的是一行人话，不是整段安装输出（与旧口径同值，落刀点改为感白边界）。 */
+export declare const DETAIL_MAX_CHARS = 300;
+/**
+ * 复制文本预算（字符）：面板复制诊断全文的上限，超限在空白边界截断。
+ * 单源定义于此（#24 收敛前散在 panel.ts，值同为 1500，行为收敛后只此一处）。
+ */
+export declare const COPY_BUDGET_CHARS = 1500;
+/**
+ * 内联证据预算（字节）：#5 定深证据分界约 1KB，300 字中文即 900 字节，
+ * 加上溯源信息很可能越线。#24 起运行时强制执行（见 enforceDiagBudget），
+ * 测试对着这个常量断言。
+ */
+export declare const DIAG_INLINE_BUDGET_BYTES = 1024;
+/** 脱敏占位符：路径是唯一结构上可识别的类别，单占位；其余全部共用一个。 */
+export declare const REDACTED_PATH = "<\u8DEF\u5F84>";
+export declare const REDACTED_SECRET = "<\u8131\u654F>";
+/**
+ * 已知缺口前缀：`file:///` 三斜杠形状原样放过（URL 与文件系统路径的边界模糊）。
+ * 显式记为 known-gap：不断言它会被掩掉，而是断言它原样通过且已被记录。
+ * 若将来要覆盖，需另立规格（属 URL 与路径边界的产品决定，不顺手修）。
+ */
+export declare const KNOWN_GAP_FILE_URL_PREFIX = "file:///";
+/**
+ * 五条规则的真实可引用标识（固定顺序）：事件清单的 `rules` 栏引用这些名字，
+ * 而不必复述匹配形态（见 src/gate.ts）。顺序即应用顺序，改顺序即改行为。
+ */
+export declare const REDACTION_RULE_NAMES: readonly ["R_ABSOLUTE_PATH", "R_URL_USERINFO", "R_TOKEN", "R_CRED_PAIR", "R_EMAIL"];
+export type RedactionRuleName = (typeof REDACTION_RULE_NAMES)[number];
+/** 本包认可的源主机名集合：「一律官方源」政策本来就蕴含的集合，不是新增维护负担。 */
+export declare const ENDORSED_REGISTRY_HOSTS: readonly ["registry.npmjs.org"];
+/**
+ * 空白边界落刀（通用）：max 处若在词中，退到上一个空白；末尾若把占位符切开（如 `<路`），
+ * 退到占位符起点。中文无空白时退无可退，按 max 硬切（长度不变，可见行为变化须进发布说明）。
+ */
+export declare function truncateToWordBoundary(text: string, max: number): string;
+/**
+ * 把外面世界的脏错误收成一行：压平空白 → URL 用户信息（命中整项丢弃）→ 路径 → 令牌
+ * → 键值对 → 邮箱 → 300 字封顶（封顶后不再扫描）。
+ * URL 用户信息命中时丢弃整项（返回空串）：密码自身可能含 `@`，起止不唯一，
+ * 替换会把一次泄漏变成一次静默的错（证据被销毁），丢弃至少看得出。
+ */
+export declare function sanitizeDetail(text: string): string;
+/**
+ * 复制前把一行文本收干净（#24 单源：与 sanitizeDetail 同规则同顺序，只换 1500 预算）。
+ * 确定性：同一输入两次运行逐字节相同。URL 用户信息同样整项丢弃（返空串），
+ * 调用方（panel.ts buildDiagnosticText）对空串回落到稳定码，不静默。
+ */
+export declare function sanitizeForCopy(text: unknown): string;
+/**
+ * 源主机名规则（R 源信息）：只在命中国家认可的源时给 origin 主机名，
+ * 不带用户信息、端口、路径、查询参数；客户端 IP 永不进；不认可即省略（省略本身即信息）。
+ * 本函数只做规则（供 #18 的 diag 落地时调用），本票不新增任何回包键。
+ */
+export declare function resolveRegistryHost(registryUrl: string): string | null;
+/** 诊断块 JSON 字节数（TextEncoder 全局，宿主与浏览器闭包两边都有；无则退化为字符数）。 */
+export declare function diagByteLength(value: unknown): number;
+/**
+ * 字节墙下永不丢的键：码 / 阶段 / 路由+方法（原子对，要么同有要么同省） / 请求编号
+ * （及版本门 `v` 与 envelope 码）。这些键即使超预算也保留——丢了它们诊断即不可定位，
+ * 不如超一点（实际仍能压进预算，见下）。
+ * 路由与方法正交但原子：构造侧（diag.ts deriveRouteMethod）同产同省，墙侧若只保路由
+ * 必拆散该对（对抗审查实锤：#21 超长中文用例 route 在 method 被省，well-formed 断言红）。
+ * 方法串极短（https/fs/phone/spawn/service，约十字节），永保代价可忽略。
+ */
+export declare const DIAG_NEVER_DROP_KEYS: readonly ["v", "code", "error", "errorKind", "stage", "route", "method", "requestId"];
+/**
+ * 按序省的键（#24 票面顺序）：registryHost → action → 版本（latest → running → target 包名）
+ * → 其余可选。尾段按诊断价值升序（先省最不定位的）：耗时（仅范围断言）→ 退出码（仅 exec 有）
+ * → 环境（面板多已知）→ 检查编号（请求号已永保，join 一半冗余）
+ * → HTTP 状态（429 信号最定位，最后省）。方法不在此列（与路由原子永保）。
+ * 面板只渲染不推导，不靠顺序分支。
+ * （对抗审查订正：旧尾段把 latency 放最后即最难省，与“仅范围断言”价值倒挂，已掉头；
+ * 旧尾段含 method，已移入永保，理由见上。）
+ */
+export declare const DIAG_DROP_ORDER: readonly ["registryHost", "action", "latestVersion", "runningVersion", "targetPackageName", "latencyMs", "exitCode", "environmentKind", "checkId", "httpStatus"];
+export type DiagDropKey = (typeof DIAG_DROP_ORDER)[number];
+/**
+ * DIAG 字节墙 enforcement：输入任意 diag 候选对象，返回预算内的对象 + 显式 truncated 位。
+ *
+ * - 码/阶段/路由+方法（原子对）/请求编号（及 v）永不丢；
+ * - detail 只截断不省（先按 300 字口径，再按需收窄，落刀不断占位符）；
+ * - registryHost / action / 版本按 DIAG_DROP_ORDER 依次省；
+ * - 显式 `truncated: true` 当且仅当本次动过 detail 或省过任一键（否则 false）。
+ *
+ * 纯函数、确定性：同一输入同一输出；不读盘、不联网、不抛错（坏输入回最小骨架）。
+ */
+export declare function enforceDiagBudget<T extends Record<string, unknown>>(input: T): T & {
+    truncated: boolean;
+};

package/dist/redaction.js

@@ -0,0 +1,205 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/redaction.ts
+const DETAIL_MAX_CHARS = 300;
+const COPY_BUDGET_CHARS = 1500;
+const DIAG_INLINE_BUDGET_BYTES = 1024;
+const REDACTED_PATH = "<\u8DEF\u5F84>";
+const REDACTED_SECRET = "<\u8131\u654F>";
+const KNOWN_GAP_FILE_URL_PREFIX = "file:///";
+const REDACTION_RULE_NAMES = [
+  "R_ABSOLUTE_PATH",
+  "R_URL_USERINFO",
+  "R_TOKEN",
+  "R_CRED_PAIR",
+  "R_EMAIL"
+];
+const ENDORSED_REGISTRY_HOSTS = ["registry.npmjs.org"];
+const ABSOLUTE_PATH_RE = /[A-Za-z]:\\[^\s"']*|\\\\[^\s"'()\[\];]+|(^|[\s"'(\[=,])\/\/[^\s"'()\[\];]+|(^|[\s"'(\[=:,])\/(?!\/)[^\s"'()\[\];]+/g;
+const URL_USERINFO_RE = /[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s/]*@/;
+const NPM_TOKEN_RE = /\bnpm_[A-Za-z0-9_-]{8,}/g;
+const GITHUB_TOKEN_RE = /\b(?:gh[pousr]_[A-Za-z0-9]{8,}|github_pat_[A-Za-z0-9_]{10,})/g;
+const SK_TOKEN_RE = /\bsk-[A-Za-z0-9_-]{6,}/g;
+const BEARER_TOKEN_RE = /(\bbearer\s+)[A-Za-z0-9._~+/-=]{6,}/gi;
+const CRED_PAIR_RE = /(\b(?:token|password|passwd|pwd|api[_-]?key|access[_-]?key|auth[_-]?token|secret|cookie)\s*[:=]\s*)("[^"]+"|'[^']+'|[^\s'";,)\]]+)/gi;
+const EMAIL_RE = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+function flattenWhitespace(text) {
+  return String(text ?? "").replace(/\s+/g, " ").trim();
+}
+function applyPathRule(text) {
+  ABSOLUTE_PATH_RE.lastIndex = 0;
+  return text.replace(ABSOLUTE_PATH_RE, (_whole, g1, g2) => {
+    const lead = g1 ?? g2 ?? "";
+    return `${lead}${REDACTED_PATH}`;
+  });
+}
+function applyTokenRule(text) {
+  NPM_TOKEN_RE.lastIndex = 0;
+  GITHUB_TOKEN_RE.lastIndex = 0;
+  SK_TOKEN_RE.lastIndex = 0;
+  BEARER_TOKEN_RE.lastIndex = 0;
+  return text.replace(NPM_TOKEN_RE, REDACTED_SECRET).replace(GITHUB_TOKEN_RE, REDACTED_SECRET).replace(SK_TOKEN_RE, REDACTED_SECRET).replace(BEARER_TOKEN_RE, (_whole, prefix) => `${prefix}${REDACTED_SECRET}`);
+}
+function applyCredPairRule(text) {
+  CRED_PAIR_RE.lastIndex = 0;
+  return text.replace(CRED_PAIR_RE, (_whole, head) => `${head}${REDACTED_SECRET}`);
+}
+function applyEmailRule(text) {
+  EMAIL_RE.lastIndex = 0;
+  return text.replace(EMAIL_RE, REDACTED_SECRET);
+}
+function hasUserinfo(text) {
+  URL_USERINFO_RE.lastIndex = 0;
+  return URL_USERINFO_RE.test(text);
+}
+function truncateToWordBoundary(text, max) {
+  const input = String(text ?? "");
+  if (input.length <= max) return input;
+  const slice = input.slice(0, max);
+  const lastSpace = slice.lastIndexOf(" ");
+  let cut = lastSpace > 0 ? slice.slice(0, lastSpace) : slice;
+  const lastOpen = cut.lastIndexOf("<");
+  const lastClose = cut.lastIndexOf(">");
+  if (lastOpen > lastClose) cut = cut.slice(0, lastOpen).trimEnd();
+  if (!cut) cut = slice;
+  return `${cut}\u2026`;
+}
+function truncateDetail(text) {
+  return truncateToWordBoundary(text, DETAIL_MAX_CHARS);
+}
+function truncateForCopy(text) {
+  return truncateToWordBoundary(text, COPY_BUDGET_CHARS);
+}
+function scrubWithoutBudget(text) {
+  return applyEmailRule(applyCredPairRule(applyTokenRule(applyPathRule(text))));
+}
+function sanitizeDetail(text) {
+  const flat = flattenWhitespace(text);
+  if (!flat) return "";
+  if (hasUserinfo(flat)) return "";
+  return truncateDetail(scrubWithoutBudget(flat));
+}
+function sanitizeForCopy(text) {
+  const flat = flattenWhitespace(String(text ?? ""));
+  if (!flat) return "";
+  if (hasUserinfo(flat)) return "";
+  return truncateForCopy(scrubWithoutBudget(flat));
+}
+function resolveRegistryHost(registryUrl) {
+  try {
+    const raw = String(registryUrl ?? "").trim();
+    if (!raw) return null;
+    const host = new URL(raw).hostname.toLowerCase();
+    if (!host) return null;
+    return ENDORSED_REGISTRY_HOSTS.includes(host) ? host : null;
+  } catch {
+    return null;
+  }
+}
+function diagByteLength(value) {
+  try {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const encoder = globalThis.TextEncoder;
+    if (typeof encoder === "function") return new encoder().encode(text ?? "").length;
+    return String(text ?? "").length;
+  } catch {
+    try {
+      return String(JSON.stringify(value) ?? "").length;
+    } catch {
+      return 0;
+    }
+  }
+}
+const DIAG_NEVER_DROP_KEYS = ["v", "code", "error", "errorKind", "stage", "route", "method", "requestId"];
+const DIAG_DROP_ORDER = [
+  "registryHost",
+  "action",
+  "latestVersion",
+  "runningVersion",
+  "targetPackageName",
+  "latencyMs",
+  "exitCode",
+  "environmentKind",
+  "checkId",
+  "httpStatus"
+];
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function enforceDiagBudget(input) {
+  const base = isRecord(input) ? { ...input } : {};
+  const sizeOf = (obj) => diagByteLength(obj);
+  const convergeDetailTo300 = (obj) => {
+    const current = obj["detail"];
+    if (typeof current !== "string" || !current) return false;
+    const next = truncateToWordBoundary(current, DETAIL_MAX_CHARS);
+    if (next !== current) {
+      obj["detail"] = next;
+      return true;
+    }
+    return false;
+  };
+  const shrinkDetailToFit = (obj) => {
+    const current = obj["detail"];
+    if (typeof current !== "string" || !current) return false;
+    let next = current;
+    let changed = false;
+    while (next && sizeOf({ ...obj, detail: next, truncated: true }) > DIAG_INLINE_BUDGET_BYTES) {
+      const shorter = next.length - 50;
+      if (shorter <= 0) {
+        next = "";
+        break;
+      }
+      const cut = truncateToWordBoundary(next.slice(0, shorter), shorter) || next.slice(0, shorter) + "\u2026";
+      if (cut.length >= next.length) {
+        next = next.slice(0, shorter) + "\u2026";
+      } else {
+        next = cut;
+      }
+      changed = true;
+    }
+    if (next !== current) {
+      obj["detail"] = next;
+      return true;
+    }
+    return changed;
+  };
+  if (sizeOf({ ...base, truncated: base["truncated"] ?? false }) <= DIAG_INLINE_BUDGET_BYTES) {
+    const already = base["truncated"] === true;
+    return { ...base, truncated: already };
+  }
+  const working = { ...base };
+  convergeDetailTo300(working);
+  for (const key of DIAG_DROP_ORDER) {
+    if (sizeOf({ ...working, truncated: true }) <= DIAG_INLINE_BUDGET_BYTES) break;
+    if (key in working) {
+      delete working[key];
+    }
+  }
+  if (sizeOf({ ...working, truncated: true }) > DIAG_INLINE_BUDGET_BYTES && typeof working["detail"] === "string" && working["detail"]) {
+    shrinkDetailToFit(working);
+    if (sizeOf({ ...working, truncated: true }) > DIAG_INLINE_BUDGET_BYTES && typeof working["detail"] === "string" && working["detail"]) {
+      working["detail"] = "";
+    }
+  }
+  for (const key of DIAG_NEVER_DROP_KEYS) {
+    if (key in base && !(key in working)) working[key] = base[key];
+  }
+  return { ...working, truncated: true };
+}
+export {
+  COPY_BUDGET_CHARS,
+  DETAIL_MAX_CHARS,
+  DIAG_DROP_ORDER,
+  DIAG_INLINE_BUDGET_BYTES,
+  DIAG_NEVER_DROP_KEYS,
+  ENDORSED_REGISTRY_HOSTS,
+  KNOWN_GAP_FILE_URL_PREFIX,
+  REDACTED_PATH,
+  REDACTED_SECRET,
+  REDACTION_RULE_NAMES,
+  diagByteLength,
+  enforceDiagBudget,
+  resolveRegistryHost,
+  sanitizeDetail,
+  sanitizeForCopy,
+  truncateToWordBoundary
+};

package/dist/service.d.ts

@@ -0,0 +1,72 @@
+/**
+ * src/service.ts — 更新模块的业务流程（安装闭环）。
+ *
+ * 由 update-core/src/service.ts 原样拎入：只记得规矩，不动手装：查状态读本地、查新版联网问一次、
+ * 装前复核用的凭证与指纹在这里生成与比对，安装的排队、去重、复核、备份顺序也在此。
+ * 真正的跑腿（读盘、联网、拼命令、执行）全在适配器，本文件零导入，依赖全当参数传。
+ *
+ * 相对原样的增量（规格 #591 第 4、5 条）：目标包名、官方源、联网超时、凭证有效期经 UpdatePorts
+ * 的可选字段注入，默认值等于现状常量（冻结默认值）。不传即走现状，老调用零变化。
+ */
+import type { FetchImpl, ReleaseInfo, UpdateCore, UpdateErrorCode, UpdatePorts } from './ports.js';
+export declare const PACKAGE_NAME = "dsh-mattpocock-skills-deck";
+export declare const NPM_REGISTRY = "https://registry.npmjs.org/";
+export declare const CHECK_TIMEOUT_MS = 10000;
+export declare const CONFIRMATION_TTL_MS: number;
+/** 2 秒内重复点击复用上次结果，不重新联网。 */
+export declare const RECHECK_WINDOW_MS = 2000;
+export declare const MAX_METADATA_BYTES: number;
+export declare const INTEGRITY_PATTERN = "^sha512-[A-Za-z0-9+/]{86}==$";
+/**
+ * 请求编号是否合法（#19 收紧：非空、去空格后 1 到 128 个字符，且为不透明编号形状）。
+ *
+ * 收紧内容：只收 `[A-Za-z0-9._~-]`（UUID 与 `req-1` 形都在内），拒绝路径 / 令牌 / 邮箱 /
+ * 键值对 / URL 用户信息形状——要放进诊断块的正是接入方经公开电话传进来的这个值，
+ * 旧口径下路径与令牌形状的字符串都能通过（见 #19 Out of Scope 第 1 件）。
+ * 属公开契约变更（破冰范围）：兼容说明与迁移口径见 #19 进度区——调用方请用 UUID 或同形状不透明串，
+ * 不要把路径、令牌、邮箱、URL 当编号传；旧的合法不透明串（`req-1`、`id-N`、UUID）不受影响。
+ */
+export declare function validRequestId(v: unknown): v is string;
+export declare function updateError(code: UpdateErrorCode): Error & {
+    code: UpdateErrorCode;
+};
+export declare function validVersion(v: unknown): v is string;
+/** 版本通道：默认只推 stable；prerelease 须调用方显式 opt-in（#16）。 */
+export type ReleaseChannel = 'stable' | 'prerelease';
+export declare const RELEASE_CHANNELS: readonly ["stable", "prerelease"];
+export declare function validReleaseChannel(v: unknown): v is ReleaseChannel;
+/**
+ * 发行版本号（含预发布）：`X.Y.Z` 或 `X.Y.Z-ids`（ids 见 SemVer §9）。
+ * stable 版（纯三段）恒为真；`0.2.0-rc.2` 这类预发布在此为真、在 validVersion 为假。
+ */
+export declare function validReleaseVersion(v: unknown): v is string;
+/** 是否预发布版本（发行合法但非纯三段）。 */
+export declare function isPrereleaseVersion(v: unknown): v is string;
+/** 该版本在该通道是否允许出现：stable 通道只收纯三段，prerelease 通道两者皆收。 */
+export declare function isVersionAllowedInChannel(version: unknown, channel?: ReleaseChannel): version is string;
+/** -1 更小，0 相等，1 更大（入参须先过 validVersion 或 parseTriple）。 */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * 发行版比较（SemVer §11）：先比三段数字；三段相等时，无预发布 > 有预发布；
+ * 都有预发布则按标识符逐个比（纯数字按数字比、数字 < 字母、段多者大）。
+ * 入参须先过 validReleaseVersion，否则抛 invalid-release。
+ */
+export declare function compareReleaseVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * 运行环境是否满足远端要求的 Node 范围。
+ * 只看懂星号、精确版与 ^ ~ > >= < <= 比较式；看不懂的写法一律放行不误拦。
+ */
+export declare function satisfiesNodeRange(nodeVersion: string, range: string | undefined): boolean;
+/**
+ * 问官方源的最新版接口，只接受名字对得上、版本号合法正式版、
+ * 包地址与完整性校验全合规的返回，否则按版本信息无效处理。
+ *
+ * 联网取数失败带 httpStatus（仅 !ok 有；假件不给即省略，diag 按阶段×键表断言）：
+ * 取数阶段该有、校验阶段不该有（由 diag 层按阶段强制省略，本层只诚实携带）。
+ */
+export declare function fetchNpmRelease(fetchImpl: FetchImpl, timeoutMs?: number, opts?: {
+    targetPackageName?: string;
+    registryUrl?: string;
+    releaseChannel?: ReleaseChannel;
+}): Promise<ReleaseInfo>;
+export declare function createUpdateCore(ports: UpdatePorts): UpdateCore;

package/dist/service.js

@@ -7,7 +7,12 @@ const RECHECK_WINDOW_MS = 2e3;
 const MAX_METADATA_BYTES = 256 * 1024;
 const INTEGRITY_PATTERN = "^sha512-[A-Za-z0-9+/]{86}==$";
 function validRequestId(v) {
-  return typeof v === "string" && v.trim().length >= 1 && v.trim().length <= 128;
+  if (typeof v !== "string") return false;
+  const id = v.trim();
+  if (id.length < 1 || id.length > 128) return false;
+  if (!/^[A-Za-z0-9._~-]+$/.test(id)) return false;
+  if (/^(npm_|gh[pousr]_|github_pat_|sk-|bearer)/i.test(id)) return false;
+  return true;
 }
 function updateError(code) {
   return Object.assign(new Error(code), { code });
@@ -15,6 +20,37 @@ function updateError(code) {
 function validVersion(v) {
   return typeof v === "string" && /^\d+\.\d+\.\d+$/.test(v);
 }
+const RELEASE_CHANNELS = ["stable", "prerelease"];
+function validReleaseChannel(v) {
+  return v === "stable" || v === "prerelease";
+}
+function validPrereleaseIds(ids) {
+  if (typeof ids !== "string" || !ids) return false;
+  const parts = ids.split(".");
+  if (parts.length === 0) return false;
+  for (const p of parts) {
+    if (!p || !/^[0-9A-Za-z-]+$/.test(p)) return false;
+    if (/^\d+$/.test(p) && p.length > 1 && p.startsWith("0")) return false;
+  }
+  return true;
+}
+function validReleaseVersion(v) {
+  if (typeof v !== "string" || !v) return false;
+  const dash = v.indexOf("-");
+  if (dash < 0) return validVersion(v);
+  const core = v.slice(0, dash);
+  const ids = v.slice(dash + 1);
+  if (!validVersion(core) || !validPrereleaseIds(ids)) return false;
+  if (ids.includes("+")) return false;
+  return true;
+}
+function isPrereleaseVersion(v) {
+  return validReleaseVersion(v) && !validVersion(v);
+}
+function isVersionAllowedInChannel(version, channel = "stable") {
+  if (channel === "prerelease") return validReleaseVersion(version);
+  return validVersion(version);
+}
 function parseTriple(v) {
   const parts = String(v).split(".");
   if (parts.length > 3) return null;
@@ -38,6 +74,40 @@ function compareVersions(a, b) {
   }
   return 0;
 }
+function parseReleaseIds(ids) {
+  return ids.split(".").map((p) => /^\d+$/.test(p) ? Number(p) : p);
+}
+function compareReleaseVersions(a, b) {
+  if (!validReleaseVersion(a) || !validReleaseVersion(b)) throw updateError("invalid-release");
+  const dashA = String(a).indexOf("-");
+  const dashB = String(b).indexOf("-");
+  const coreA = dashA < 0 ? String(a) : String(a).slice(0, dashA);
+  const coreB = dashB < 0 ? String(b) : String(b).slice(0, dashB);
+  const order = compareVersions(coreA, coreB);
+  if (order !== 0) return order;
+  const preA = dashA < 0 ? null : parseReleaseIds(String(a).slice(dashA + 1));
+  const preB = dashB < 0 ? null : parseReleaseIds(String(b).slice(dashB + 1));
+  if (preA === null && preB === null) return 0;
+  if (preA === null) return 1;
+  if (preB === null) return -1;
+  const width = Math.max(preA.length, preB.length);
+  for (let i = 0; i < width; i++) {
+    const x = preA[i];
+    const y = preB[i];
+    if (x === void 0) return -1;
+    if (y === void 0) return 1;
+    if (typeof x === "number" && typeof y === "number") {
+      if (x < y) return -1;
+      if (x > y) return 1;
+      continue;
+    }
+    if (typeof x === "number") return -1;
+    if (typeof y === "number") return 1;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
 function compareOne(node, op, target) {
   const order = compareTriple(node, target);
   if (op === "=" || op === "") return order === 0;
@@ -102,9 +172,20 @@ function timeoutSignal(ms) {
   }
   return void 0;
 }
+function httpStatusOf(response) {
+  const raw = response?.status;
+  return typeof raw === "number" && Number.isInteger(raw) && raw >= 100 && raw <= 599 ? raw : null;
+}
+function checkFailedWithStatus(response) {
+  const err = updateError("check-failed");
+  const status = httpStatusOf(response);
+  if (status !== null) err.httpStatus = status;
+  return err;
+}
 async function fetchNpmRelease(fetchImpl, timeoutMs = CHECK_TIMEOUT_MS, opts) {
   const targetName = opts?.targetPackageName ?? PACKAGE_NAME;
   const registry = opts?.registryUrl ?? NPM_REGISTRY;
+  const channel = opts?.releaseChannel === "prerelease" ? "prerelease" : "stable";
   let response = null;
   try {
     response = await fetchImpl(`${registry}${encodeURIComponent(targetName)}/latest`, {
@@ -116,13 +197,13 @@ async function fetchNpmRelease(fetchImpl, timeoutMs = CHECK_TIMEOUT_MS, opts) {
     throw updateError("check-failed");
   }
   try {
-    if (!response.ok) throw updateError("check-failed");
+    if (!response.ok) throw checkFailedWithStatus(response);
     const declared = Number(response.headers.get("content-length"));
     if (Number.isFinite(declared) && declared > MAX_METADATA_BYTES) throw updateError("invalid-release");
     const text = await response.text();
     if (byteLength(text) > MAX_METADATA_BYTES) throw updateError("invalid-release");
     const value = JSON.parse(text);
-    if (value.name !== targetName || !validVersion(value.version)) throw updateError("invalid-release");
+    if (value.name !== targetName || !isVersionAllowedInChannel(value.version, channel)) throw updateError("invalid-release");
     const version = value.version;
     const nodeRange = value.engines?.node;
     if (nodeRange !== void 0 && typeof nodeRange !== "string") throw updateError("invalid-release");
@@ -142,7 +223,7 @@ async function fetchNpmRelease(fetchImpl, timeoutMs = CHECK_TIMEOUT_MS, opts) {
     if (error?.code === "check-failed") throw error;
     if (error?.code === "invalid-release") throw error;
     if (response !== null && response.ok) throw updateError("invalid-release");
-    throw updateError("check-failed");
+    throw checkFailedWithStatus(response);
   }
 }
 function createUpdateCore(ports) {
@@ -150,8 +231,9 @@ function createUpdateCore(ports) {
   const confirmationTtlMs = ports.confirmationTtlMs ?? CONFIRMATION_TTL_MS;
   const targetPackageName = ports.targetPackageName ?? PACKAGE_NAME;
   const registryUrl = ports.registryUrl ?? NPM_REGISTRY;
+  const releaseChannel = ports.releaseChannel === "prerelease" ? "prerelease" : "stable";
   function fetchRelease() {
-    return fetchNpmRelease(ports.fetchImpl, checkTimeoutMs, { targetPackageName, registryUrl });
+    return fetchNpmRelease(ports.fetchImpl, checkTimeoutMs, { targetPackageName, registryUrl, releaseChannel });
   }
   let checked = null;
   let checking = null;
@@ -215,8 +297,14 @@ function createUpdateCore(ports) {
     const busy = job?.state === "installing" || job?.state === "verifying";
     const fresh = checked !== null && checked.checkId !== null && ports.now() < checked.expiresAt;
     const runningVersion = ports.readRunningVersion();
+    let newer = false;
+    try {
+      newer = isVersionAllowedInChannel(runningVersion, releaseChannel) && !!checked?.release && isVersionAllowedInChannel(checked.release.version, releaseChannel) && compareReleaseVersions(checked.release.version, runningVersion) === 1;
+    } catch {
+      newer = false;
+    }
     const canInstall = Boolean(
-      env.eligible && !blockedReason && !busy && fresh && checked?.installationKey === env.installationKey && validVersion(runningVersion) && checked?.release && compareVersions(checked.release.version, runningVersion) === 1
+      env.eligible && !blockedReason && !busy && fresh && checked?.installationKey === env.installationKey && newer
     );
     return {
       runningVersion,
@@ -353,11 +441,17 @@ export {
   NPM_REGISTRY,
   PACKAGE_NAME,
   RECHECK_WINDOW_MS,
+  RELEASE_CHANNELS,
+  compareReleaseVersions,
   compareVersions,
   createUpdateCore,
   fetchNpmRelease,
+  isPrereleaseVersion,
+  isVersionAllowedInChannel,
   satisfiesNodeRange,
   updateError,
+  validReleaseChannel,
+  validReleaseVersion,
   validRequestId,
   validVersion
 };