@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/orgs/settings.controller.js

@@ -0,0 +1,53 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Controller, Get, Inject, Patch } from "@nestjs/common";
+import { ORG_SETTINGS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "./org.guard.js";
+import { OrgSettingsPatchSchema, } from "./settings.service.js";
+let OrgSettingsController = class OrgSettingsController {
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    async get(org) {
+        return {
+            settings: await this.settings.get(org.orgId),
+            deployment: this.settings.deployment(),
+            sandboxLimits: await this.settings.sandboxLimits(org.orgId),
+        };
+    }
+    async update(principal, org, body) {
+        const p = requireUser(principal);
+        return {
+            settings: await this.settings.update(org.orgId, body, p.account.id, patTokenId(p)),
+            deployment: this.settings.deployment(),
+            sandboxLimits: await this.settings.sandboxLimits(org.orgId),
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.read"),
+    __param(0, CurrentOrg())
+], OrgSettingsController.prototype, "get", null);
+__decorate([
+    Patch(),
+    OrgAction("org.update"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(OrgSettingsPatchSchema)))
+], OrgSettingsController.prototype, "update", null);
+OrgSettingsController = __decorate([
+    Controller("api/v1/orgs/:orgId/settings"),
+    __param(0, Inject(ORG_SETTINGS))
+], OrgSettingsController);
+export { OrgSettingsController };

package/dist/orgs/settings.service.d.ts

@@ -0,0 +1,120 @@
+import { type SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+/**
+ * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
+ * （更新时与存量合并），新版本加字段不需要迁移。
+ * - `toolSearch`：工具超过阈值时是否改用目录 + `tool_search`（D11，默认 on）。
+ * - `locale`：组织默认语言（`zh` / `en`，默认 en），机器人在 IM 里说的固定话术按它选择。
+ * - `sandboxToolPolicy`：沙箱工具的默认策略（M5 T8，默认 allow）。为 `ask` 时除只读的
+ *   `sandbox_read` / `sandbox_glob` / `sandbox_grep` 外都需要审批（执行时实时读取）。
+ * - `sandboxEgress`：组织的沙箱出站（Ruling M19 / D6），缺省跟随部署的 `sandbox.limits.egress` + `allowHosts`。
+ *   见 {@link effectiveSandboxEgress}。存量值非法时按 `none` 读（宁可断网，不悄悄放宽到部署默认）。
+ */
+/** 组织沙箱出站白名单的主机数上限。 */
+export declare const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
+/**
+ * 组织的沙箱出站设置：`none`（只有回环），或 `allowlist`。`allowHosts` 给出时**替换**部署的白名单
+ * （组织可以去掉预置项、也可以加别的主机），省略时沿用部署的白名单。没有 `open`：组织不能比部署放得更开。
+ */
+export declare const SandboxEgressSettingSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        allowlist: "allowlist";
+        none: "none";
+    }>;
+    allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type SandboxEgressSetting = z.infer<typeof SandboxEgressSettingSchema>;
+export declare const OrgSettingsSchema: z.ZodObject<{
+    toolSearch: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
+        off: "off";
+        on: "on";
+    }>>>;
+    locale: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>>;
+    sandboxToolPolicy: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+    }>>>;
+    sandboxEgress: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            allowlist: "allowlist";
+            none: "none";
+        }>;
+        allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strip>;
+export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
+/** PATCH 体：只改给出的字段；未知字段 → 400。 */
+export declare const OrgSettingsPatchSchema: z.ZodObject<{
+    toolSearch: z.ZodOptional<z.ZodEnum<{
+        off: "off";
+        on: "on";
+    }>>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+    sandboxToolPolicy: z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+    }>>;
+    sandboxEgress: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        mode: z.ZodEnum<{
+            allowlist: "allowlist";
+            none: "none";
+        }>;
+        allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type OrgSettingsPatch = z.infer<typeof OrgSettingsPatchSchema>;
+/** 部署的沙箱出站（`sandbox.limits.egress` + `allowHosts`）。 */
+export type DeploymentEgress = Pick<SandboxLimits, "egress" | "allowHosts">;
+/**
+ * 组织实际生效的沙箱出站：没有组织设置 → 部署默认；`none` → 只有回环；`allowlist` → 组织的白名单
+ * （省略时用部署的），但部署是 `none` 时仍为 `none`（组织永远不比部署放得更开，部署改成 none 后存量设置也随之收紧）。
+ */
+export declare function effectiveSandboxEgress(deployment: DeploymentEgress, org: SandboxEgressSetting | undefined): DeploymentEgress;
+/**
+ * 组织实际生效的沙箱限额（C19 / Ruling M16）：企业管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
+ * 给出的 cpu / memoryMb 替换部署默认，未给的项、disk 与出站沿用 `deployment`。只在创建沙箱时读取。
+ */
+export declare function effectiveSandboxLimits(deployment: SandboxLimits, override: {
+    cpu?: number | undefined;
+    memoryMb?: number | undefined;
+} | undefined): SandboxLimits;
+/** 组织设置 GET 带回的只读沙箱限额：实际生效值与来源（有企业管理员的覆盖为 `override`）。 */
+export interface OrgSandboxLimits {
+    cpu: number;
+    memoryMb: number;
+    source: "deployment" | "override";
+}
+/** 设置页展示用的部署默认值（`GET` 一并返回）。 */
+export interface OrgSettingsDeployment {
+    sandboxEgress: {
+        mode: SandboxLimits["egress"];
+        allowHosts: string[];
+    };
+}
+/** 把存储的 jsonb 解析为设置（宽松，见 {@link OrgSettingsSchema}）。 */
+export declare function parseOrgSettings(raw: unknown): OrgSettings;
+/** 读组织设置（每次实时读 PG，多副本下改动立即生效）；组织不存在或已删除按默认值。 */
+export declare function readOrgSettings(db: KernelDb, orgId: string): Promise<OrgSettings>;
+/** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
+export declare class OrgSettingsService {
+    private readonly db;
+    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
+    private readonly config?;
+    constructor(db: KernelDb, 
+    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
+    config?: (() => Pick<KernelConfig, "sandbox">) | undefined);
+    /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
+    deployment(): OrgSettingsDeployment;
+    /** 组织实际生效的沙箱 cpu / 内存（只读；由企业管理员在部署设置里覆盖）。 */
+    sandboxLimits(orgId: string): Promise<OrgSandboxLimits>;
+    get(orgId: string): Promise<OrgSettings>;
+    update(orgId: string, patch: OrgSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<OrgSettings>;
+}

package/dist/orgs/settings.service.js

@@ -0,0 +1,178 @@
+import { validateAllowHost } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { readSandboxLimitOverride } from "../identity/settings.js";
+import { lockOrgAndAuthorize } from "./org-lock.js";
+/**
+ * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
+ * （更新时与存量合并），新版本加字段不需要迁移。
+ * - `toolSearch`：工具超过阈值时是否改用目录 + `tool_search`（D11，默认 on）。
+ * - `locale`：组织默认语言（`zh` / `en`，默认 en），机器人在 IM 里说的固定话术按它选择。
+ * - `sandboxToolPolicy`：沙箱工具的默认策略（M5 T8，默认 allow）。为 `ask` 时除只读的
+ *   `sandbox_read` / `sandbox_glob` / `sandbox_grep` 外都需要审批（执行时实时读取）。
+ * - `sandboxEgress`：组织的沙箱出站（Ruling M19 / D6），缺省跟随部署的 `sandbox.limits.egress` + `allowHosts`。
+ *   见 {@link effectiveSandboxEgress}。存量值非法时按 `none` 读（宁可断网，不悄悄放宽到部署默认）。
+ */
+/** 组织沙箱出站白名单的主机数上限。 */
+export const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
+/**
+ * 组织的沙箱出站设置：`none`（只有回环），或 `allowlist`。`allowHosts` 给出时**替换**部署的白名单
+ * （组织可以去掉预置项、也可以加别的主机），省略时沿用部署的白名单。没有 `open`：组织不能比部署放得更开。
+ */
+export const SandboxEgressSettingSchema = z
+    .object({
+    mode: z.enum(["none", "allowlist"]),
+    allowHosts: z
+        .array(z.string())
+        .max(ORG_SANDBOX_ALLOW_HOSTS_MAX)
+        .superRefine((hosts, ctx) => {
+        hosts.forEach((h, i) => {
+            for (const message of validateAllowHost(h)) {
+                ctx.addIssue({ code: "custom", path: [i], message: `${h}: ${message}` });
+            }
+        });
+        if (new Set(hosts).size !== hosts.length) {
+            ctx.addIssue({ code: "custom", message: "allowHosts must not contain duplicates" });
+        }
+    })
+        .optional(),
+})
+    .strict();
+export const OrgSettingsSchema = z.object({
+    toolSearch: z.enum(["on", "off"]).default("on").catch("on"),
+    locale: z.enum(["zh", "en"]).default("en").catch("en"),
+    sandboxToolPolicy: z.enum(["allow", "ask"]).default("allow").catch("allow"),
+    sandboxEgress: SandboxEgressSettingSchema.optional().catch({ mode: "none" }),
+});
+/** PATCH 体：只改给出的字段；未知字段 → 400。 */
+export const OrgSettingsPatchSchema = z
+    .object({
+    toolSearch: z.enum(["on", "off"]).optional(),
+    locale: z.enum(["zh", "en"]).optional(),
+    sandboxToolPolicy: z.enum(["allow", "ask"]).optional(),
+    /** null 清除（恢复跟随部署默认）。 */
+    sandboxEgress: SandboxEgressSettingSchema.nullable().optional(),
+})
+    .strict();
+/**
+ * 组织实际生效的沙箱出站：没有组织设置 → 部署默认；`none` → 只有回环；`allowlist` → 组织的白名单
+ * （省略时用部署的），但部署是 `none` 时仍为 `none`（组织永远不比部署放得更开，部署改成 none 后存量设置也随之收紧）。
+ */
+export function effectiveSandboxEgress(deployment, org) {
+    if (org === undefined)
+        return { egress: deployment.egress, allowHosts: [...deployment.allowHosts] };
+    if (org.mode === "none" || deployment.egress === "none")
+        return { egress: "none", allowHosts: [] };
+    return { egress: "allowlist", allowHosts: [...(org.allowHosts ?? deployment.allowHosts)] };
+}
+/**
+ * 组织实际生效的沙箱限额（C19 / Ruling M16）：企业管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
+ * 给出的 cpu / memoryMb 替换部署默认，未给的项、disk 与出站沿用 `deployment`。只在创建沙箱时读取。
+ */
+export function effectiveSandboxLimits(deployment, override) {
+    return {
+        ...deployment,
+        allowHosts: [...deployment.allowHosts],
+        ...(override?.cpu !== undefined && { cpu: override.cpu }),
+        ...(override?.memoryMb !== undefined && { memoryMb: override.memoryMb }),
+    };
+}
+/** 按值比较（`sandboxEgress` 是对象）；键序由 schema 固定。 */
+const sameSettings = (a, b) => JSON.stringify(OrgSettingsSchema.parse(a)) === JSON.stringify(OrgSettingsSchema.parse(b));
+const asObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+/** 把存储的 jsonb 解析为设置（宽松，见 {@link OrgSettingsSchema}）。 */
+export function parseOrgSettings(raw) {
+    return OrgSettingsSchema.parse(asObject(raw));
+}
+/** 读组织设置（每次实时读 PG，多副本下改动立即生效）；组织不存在或已删除按默认值。 */
+export async function readOrgSettings(db, orgId) {
+    const row = await db
+        .selectFrom("orgs")
+        .select("settings")
+        .where("id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    return parseOrgSettings(row?.settings);
+}
+/** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
+export class OrgSettingsService {
+    db;
+    config;
+    constructor(db, 
+    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
+    config) {
+        this.db = db;
+        this.config = config;
+    }
+    /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
+    deployment() {
+        const lim = this.config?.().sandbox.limits;
+        return {
+            sandboxEgress: { mode: lim?.egress ?? "allowlist", allowHosts: [...(lim?.allowHosts ?? [])] },
+        };
+    }
+    /** 组织实际生效的沙箱 cpu / 内存（只读；由企业管理员在部署设置里覆盖）。 */
+    async sandboxLimits(orgId) {
+        const lim = this.config?.().sandbox.limits;
+        const override = await readSandboxLimitOverride(this.db, orgId);
+        return {
+            // 没有部署配置（测试构造）时用 schema 默认值 1 核 / 2048 MiB
+            cpu: override?.cpu ?? lim?.cpu ?? 1,
+            memoryMb: override?.memoryMb ?? lim?.memoryMb ?? 2048,
+            source: override === undefined ? "deployment" : "override",
+        };
+    }
+    async get(orgId) {
+        const row = await this.db
+            .selectFrom("orgs")
+            .select("settings")
+            .where("id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!row)
+            throw new ApiError("org.not_found", "Organization not found");
+        return parseOrgSettings(row.settings);
+    }
+    async update(orgId, patch, actorAccountId, actorTokenId) {
+        if (patch.sandboxEgress?.mode === "allowlist" &&
+            this.deployment().sandboxEgress.mode === "none") {
+            throw new ApiError("org.sandbox_egress_not_allowed", "This deployment disables sandbox network access (sandbox.limits.egress is none); an organization can only set sandboxEgress to none");
+        }
+        return this.db.transaction().execute(async (trx) => {
+            await lockOrgAndAuthorize(trx, orgId, actorAccountId, "org.update");
+            const row = await trx
+                .selectFrom("orgs")
+                .select("settings")
+                .where("id", "=", orgId)
+                .executeTakeFirstOrThrow();
+            const stored = asObject(row.settings);
+            const before = parseOrgSettings(stored);
+            const changes = Object.fromEntries(Object.entries(patch)
+                .filter(([, v]) => v !== undefined)
+                // null 清除 sandboxEgress：恢复跟随部署默认
+                .map(([k, v]) => [k, v === null ? undefined : v]));
+            const after = { ...before, ...changes };
+            if (after.sandboxEgress === undefined)
+                delete after.sandboxEgress;
+            if (sameSettings(before, after))
+                return before;
+            // 与存量合并：保留本版本不认识的键（清除的 sandboxEgress 不留在存量里）
+            const { sandboxEgress: _old, ...rest } = stored;
+            await trx
+                .updateTable("orgs")
+                .set({ settings: JSON.stringify({ ...rest, ...after }) })
+                .where("id", "=", orgId)
+                .execute();
+            await audit(trx, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.settings_updated",
+                target: orgId,
+                detail: { before, after },
+            });
+            return after;
+        });
+    }
+}

package/dist/packages/npm.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 从 npm registry 下载插件包（D14 / C21 / C26）。registry 地址来自配置（可信），但它返回的内容一律当作外部输入：
+ * - 不跟随重定向（3xx 直接失败）：否则 registry 的一次重定向就能把下载（连同令牌）引到任意地址；
+ * - 元数据与 tarball 都边读边计数，超过上限立即中止；
+ * - 没有 `opts` 时 tarball 必须与 registry 同源（令牌只发往该源），并按 packument 的 `dist.integrity`
+ *   （sha512 SRI）校验；给了 `opts.expectedIntegrity`（清单引入，T24）时只认它；
+ * - `opts.tarballUrl`（清单直接给出的下载地址）必须是 https，测试里可经 `allowInsecureLoopback` 允许回环 http，
+ *   且必须同时给出 `expectedIntegrity`；不会带 registry 令牌。
+ */
+/** 下载或校验失败（HTTP 层映射为 `packages.npm_failed`，502）。消息为英文，不含令牌。 */
+export declare class NpmFetchError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 下载内容与期望的 integrity 不符（`expected` / `actual` 为 `sha512-<base64>`）。 */
+export declare class IntegrityMismatchError extends NpmFetchError {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(message: string, expected: string, actual: string);
+}
+/** The package exceeds the size limit (the HTTP layer maps it to `extension.package_too_large`, 413). */
+export declare class PackageTooLargeError extends Error {
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+export interface NpmFetchConfig {
+    registry: string;
+    token?: string;
+    maxBytes: number;
+    /** 只供测试：允许 `opts.tarballUrl` 用回环地址上的 http。 */
+    allowInsecureLoopback?: boolean;
+}
+/** 回环地址（`localhost`、`127.*`、`::1`）。 */
+export declare const isLoopback: (host: string) => boolean;
+/** 读响应体，累计超过 `max` 立即取消并抛 `onTooLarge()`。 */
+export declare function readCapped(res: Response, max: number, onTooLarge: () => Error): Promise<Buffer>;
+/**
+ * 下载 `name@version`（`version` 可以是精确版本、dist-tag 或范围，缺省 `latest`），返回 tgz 字节、解析出的版本与
+ * 实际校验所用的 integrity。失败抛 {@link NpmFetchError}（含 {@link IntegrityMismatchError}）或
+ * {@link PackageTooLargeError}。
+ */
+export declare function fetchNpmPackage(cfg: NpmFetchConfig, name: string, version: string | undefined, signal: AbortSignal, opts?: {
+    expectedIntegrity?: string;
+    tarballUrl?: string;
+}): Promise<{
+    bytes: Uint8Array;
+    version: string;
+    integrity: string;
+}>;

package/dist/packages/npm.js

@@ -0,0 +1,218 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { isIP } from "node:net";
+import semver from "semver";
+/**
+ * 从 npm registry 下载插件包（D14 / C21 / C26）。registry 地址来自配置（可信），但它返回的内容一律当作外部输入：
+ * - 不跟随重定向（3xx 直接失败）：否则 registry 的一次重定向就能把下载（连同令牌）引到任意地址；
+ * - 元数据与 tarball 都边读边计数，超过上限立即中止；
+ * - 没有 `opts` 时 tarball 必须与 registry 同源（令牌只发往该源），并按 packument 的 `dist.integrity`
+ *   （sha512 SRI）校验；给了 `opts.expectedIntegrity`（清单引入，T24）时只认它；
+ * - `opts.tarballUrl`（清单直接给出的下载地址）必须是 https，测试里可经 `allowInsecureLoopback` 允许回环 http，
+ *   且必须同时给出 `expectedIntegrity`；不会带 registry 令牌。
+ */
+/** 下载或校验失败（HTTP 层映射为 `packages.npm_failed`，502）。消息为英文，不含令牌。 */
+export class NpmFetchError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "NpmFetchError";
+    }
+}
+/** 下载内容与期望的 integrity 不符（`expected` / `actual` 为 `sha512-<base64>`）。 */
+export class IntegrityMismatchError extends NpmFetchError {
+    expected;
+    actual;
+    constructor(message, expected, actual) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "IntegrityMismatchError";
+    }
+}
+/** The package exceeds the size limit (the HTTP layer maps it to `extension.package_too_large`, 413). */
+export class PackageTooLargeError extends Error {
+    maxBytes;
+    constructor(maxBytes) {
+        super(`the package is larger than ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+        this.name = "PackageTooLargeError";
+    }
+}
+/** packument（包元数据）的大小上限：热门包的完整元数据可以有几十 MB，插件包不会这么多。 */
+const MAX_METADATA_BYTES = 16 * 1024 * 1024;
+// npm 包名（简化，与 plugin-sdk 的规则一致）：可带 scope，小写，≤ 214 字符。
+const NPM_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const TAG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/** 回环地址（`localhost`、`127.*`、`::1`）。 */
+export const isLoopback = (host) => {
+    const h = host.replace(/^\[|\]$/g, "");
+    return h === "localhost" || h === "::1" || (isIP(h) === 4 && h.startsWith("127."));
+};
+/** 读响应体，累计超过 `max` 立即取消并抛 `onTooLarge()`。 */
+export async function readCapped(res, max, onTooLarge) {
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > max) {
+        await res.body?.cancel().catch(() => { });
+        throw onTooLarge();
+    }
+    if (!res.body)
+        return Buffer.alloc(0);
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel().catch(() => { });
+            throw onTooLarge();
+        }
+        chunks.push(value);
+    }
+    if (chunks.length === 1) {
+        const c = chunks[0];
+        return Buffer.from(c.buffer, c.byteOffset, c.byteLength);
+    }
+    return Buffer.concat(chunks);
+}
+async function get(url, headers, signal, what) {
+    let res;
+    try {
+        res = await fetch(url, { headers, redirect: "manual", signal });
+    }
+    catch (e) {
+        throw new NpmFetchError(`cannot fetch the ${what}: ${errMsg(e)}`, { cause: e });
+    }
+    if (res.status >= 300 && res.status < 400) {
+        await res.body?.cancel().catch(() => { });
+        throw new NpmFetchError(`the ${what} responded with a redirect (${res.status}); redirects are not followed`);
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        throw new NpmFetchError(`the ${what} responded with HTTP ${res.status}`);
+    }
+    return res;
+}
+/** `sha512-<base64>` 形式的 SRI；可能有空格分隔的多个，取其中的 sha512。 */
+function sha512Of(integrity) {
+    for (const part of integrity.trim().split(/\s+/)) {
+        const m = /^sha512-([A-Za-z0-9+/]+={0,2})(?:\?.*)?$/.exec(part);
+        if (m) {
+            const b = Buffer.from(m[1], "base64");
+            if (b.length === 64)
+                return b;
+        }
+    }
+    return undefined;
+}
+function verify(bytes, integrity, label) {
+    const want = sha512Of(integrity);
+    if (!want)
+        throw new NpmFetchError(`${label} is not a sha512 integrity`);
+    const got = createHash("sha512").update(bytes).digest();
+    if (!timingSafeEqual(want, got)) {
+        throw new IntegrityMismatchError(`the downloaded package does not match ${label}`, `sha512-${want.toString("base64")}`, `sha512-${got.toString("base64")}`);
+    }
+}
+/**
+ * 下载 `name@version`（`version` 可以是精确版本、dist-tag 或范围，缺省 `latest`），返回 tgz 字节、解析出的版本与
+ * 实际校验所用的 integrity。失败抛 {@link NpmFetchError}（含 {@link IntegrityMismatchError}）或
+ * {@link PackageTooLargeError}。
+ */
+export async function fetchNpmPackage(cfg, name, version, signal, opts = {}) {
+    if (typeof name !== "string" || name.length > 214 || !NPM_NAME_RE.test(name)) {
+        throw new NpmFetchError(`"${String(name)}" is not a valid npm package name`);
+    }
+    const registry = new URL(cfg.registry.endsWith("/") ? cfg.registry : `${cfg.registry}/`);
+    const authHeaders = cfg.token !== undefined ? { authorization: `Bearer ${cfg.token}` } : {};
+    const tooLarge = () => new PackageTooLargeError(cfg.maxBytes);
+    let tarball;
+    let resolved;
+    let integrity;
+    let tarballHeaders = authHeaders;
+    if (opts.tarballUrl !== undefined) {
+        if (opts.expectedIntegrity === undefined) {
+            throw new NpmFetchError("a tarballUrl needs an expectedIntegrity to verify the download");
+        }
+        if (version === undefined || semver.valid(version) === null) {
+            throw new NpmFetchError("a tarballUrl needs an exact version");
+        }
+        try {
+            tarball = new URL(opts.tarballUrl);
+        }
+        catch {
+            throw new NpmFetchError("the tarball URL is not a valid URL");
+        }
+        const insecureOk = cfg.allowInsecureLoopback === true &&
+            tarball.protocol === "http:" &&
+            isLoopback(tarball.hostname);
+        if (tarball.protocol !== "https:" && !insecureOk) {
+            throw new NpmFetchError("the tarball URL must use https");
+        }
+        // 令牌只发给 registry 源
+        if (tarball.origin !== registry.origin)
+            tarballHeaders = {};
+        resolved = version;
+        integrity = opts.expectedIntegrity;
+    }
+    else {
+        // scope 包名里的 `/` 按 npm 客户端的写法编码为 %2f
+        const docUrl = new URL(name.replace("/", "%2f"), registry);
+        const res = await get(docUrl, { ...authHeaders, accept: "application/json" }, signal, "npm registry");
+        const raw = await readCapped(res, MAX_METADATA_BYTES, () => new NpmFetchError("the npm package metadata is too large"));
+        let doc;
+        try {
+            doc = JSON.parse(raw.toString("utf8"));
+        }
+        catch {
+            throw new NpmFetchError("the npm package metadata is not valid JSON");
+        }
+        const versions = doc.versions && typeof doc.versions === "object" ? doc.versions : {};
+        const tags = doc["dist-tags"] && typeof doc["dist-tags"] === "object" ? doc["dist-tags"] : {};
+        const want = version ?? "latest";
+        let picked;
+        if (Object.hasOwn(versions, want) && semver.valid(want) !== null)
+            picked = want;
+        else if (TAG_RE.test(want) && typeof tags[want] === "string" && semver.valid(want) === null) {
+            picked = tags[want];
+        }
+        else if (semver.validRange(want) !== null) {
+            picked =
+                semver.maxSatisfying(Object.keys(versions).filter((v) => semver.valid(v) !== null), want) ?? undefined;
+        }
+        const entry = picked !== undefined && Object.hasOwn(versions, picked) ? versions[picked] : undefined;
+        if (picked === undefined || !entry) {
+            throw new NpmFetchError(`npm package ${name} has no version matching "${want}"`);
+        }
+        const dist = entry.dist ?? {};
+        if (typeof dist.tarball !== "string") {
+            throw new NpmFetchError(`npm package ${name}@${picked} has no tarball`);
+        }
+        try {
+            tarball = new URL(dist.tarball);
+        }
+        catch {
+            throw new NpmFetchError(`npm package ${name}@${picked} has an invalid tarball URL`);
+        }
+        if (tarball.origin !== registry.origin) {
+            throw new NpmFetchError(`the tarball of ${name}@${picked} is not on the registry origin ${registry.origin}`);
+        }
+        if (opts.expectedIntegrity !== undefined)
+            integrity = opts.expectedIntegrity;
+        else if (typeof dist.integrity === "string")
+            integrity = dist.integrity;
+        else
+            throw new NpmFetchError(`npm package ${name}@${picked} has no integrity to verify`);
+        resolved = picked;
+    }
+    const res = await get(tarball, tarballHeaders, signal, "package tarball");
+    const bytes = await readCapped(res, cfg.maxBytes, tooLarge);
+    verify(bytes, integrity, opts.expectedIntegrity !== undefined ? "the expected integrity" : "the npm dist.integrity");
+    return {
+        bytes: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+        version: resolved,
+        integrity,
+    };
+}

package/dist/packages/provenance.d.ts

@@ -0,0 +1,47 @@
+import { type NpmFetchConfig } from "./npm.js";
+/**
+ * npm provenance for the import review (spec §5.5, Decision 7): the registry's attestations of
+ * `name@version` (`<registry>/-/npm/v1/attestations/<name>@<version>`) are read and the SLSA
+ * provenance statement (in-toto, inside a DSSE envelope) is parsed for the repository, commit and
+ * workflow it was built from. This is display only: the sigstore signatures are not verified, and
+ * nothing here ever fails an import. A registry without provenance, a network error, a timeout, an
+ * oversized or malformed answer all give `{ checked: false, reason }` ("provenance not checked").
+ * The registry token goes only to the registry (the attestation URL is always on its origin).
+ */
+/** What the SLSA provenance of an npm package says about its build. */
+export interface Provenance {
+    checked: true;
+    /** The source repository, as attested (e.g. `https://github.com/acme/plugins`). */
+    repository: string;
+    /** The git commit the package was built from. */
+    commit: string;
+    /** The workflow file that built it (e.g. `.github/workflows/release.yml`). */
+    workflow: string;
+    /** The SLSA build type (which CI system's build definition). */
+    buildType: string;
+}
+/** Provenance was not checked (no attestation, offline, or an answer that could not be read). */
+export interface ProvenanceNotChecked {
+    checked: false;
+    reason: string;
+}
+export type ProvenanceResult = Provenance | ProvenanceNotChecked;
+/** The predicate type of an SLSA v1 provenance statement. */
+export declare const SLSA_PROVENANCE_V1 = "https://slsa.dev/provenance/v1";
+/** Provenance must not hold up an import: a slow registry gives "not checked". */
+export declare const PROVENANCE_TIMEOUT_MS = 15000;
+/**
+ * Reads the SLSA provenance of `name@version` from the configured registry. `integrity` (the
+ * tarball's `sha512-…`, when known) must be among the statement's subject digests, so a statement
+ * about another tarball is not shown. Never throws (an aborted `signal` included).
+ */
+export declare function fetchProvenance(cfg: NpmFetchConfig, name: string, version: string, signal: AbortSignal, opts?: {
+    integrity?: string;
+}): Promise<ProvenanceResult>;
+/**
+ * Parses an attestations answer (`{ attestations: [{ predicateType, bundle: { dsseEnvelope } }] }`).
+ * Exported for tests.
+ */
+export declare function parseAttestations(body: unknown, integrity?: string): ProvenanceResult;
+/** Two repository URLs name the same repository (scheme, `git+`, `.git`, case ignored). */
+export declare function sameRepository(a: string, b: string): boolean;