@harrylabsj/kiwi 0.6.0

package/dist/discovery/ucp/resolver.js

@@ -0,0 +1,214 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * UCP Profile resolver（基线 §25 / §43）：抓取 `/.well-known/ucp`。
+ *
+ * 行为表：
+ *   - HTTPS only：非 https URL 直接拒绝（profile_not_https），不发起抓取；
+ *   - SSRF 复用 a2a client 的 url-policy（assertSafeTargetUrl 静态校验 +
+ *     assertResolvableTargetUrl 请求前 DNS 复查），拒绝 → unsafe_target（fail-closed）；
+ *   - 不跟随重定向：fetch redirect:"manual"，3xx / opaqueredirect / redirected
+ *     → profile_redirect；
+ *   - 超时：AbortController，超时 → profile_unreachable；
+ *   - Cache-Control：MUST 含 public 且 max-age>=60，否则 profile_cache_control；
+ *   - 缓存：按 Cache-Control max-age 缓存（最小 TTL 60s 地板），命中缓存 cached:true，
+ *     不重新抓取也不重复 SSRF/DNS 校验；
+ *   - 解析/校验失败 → profile_malformed / profile_bad_status / profile_unreachable。
+ *
+ * 零新增依赖：Node 22 原生 fetch + AbortController。
+ */
+import { assertResolvableTargetUrl, assertSafeTargetUrl } from "../../a2a/client/url-policy.js";
+import { readJsonBody, SafeHttpError } from "../../net/safe-http.js";
+import { UcpError } from "./error.js";
+import { validateUcpProfile } from "./validate.js";
+export const WELL_KNOWN_UCP_PATH = "/.well-known/ucp";
+const MIN_CACHE_TTL_MS = 60_000;
+export function parseCacheControl(header) {
+    if (header === null || header.trim() === "") {
+        return { ok: false, reason: "Cache-Control header is missing" };
+    }
+    const directives = header.split(",").map((d) => d.trim().toLowerCase());
+    if (!directives.some((d) => d === "public")) {
+        return { ok: false, reason: "Cache-Control must include the public directive" };
+    }
+    if (directives.some((d) => d === "private" || d === "no-store")) {
+        return { ok: false, reason: "Cache-Control must not be private or no-store" };
+    }
+    const match = /max-age\s*=\s*"?(\d+)"?/i.exec(header);
+    if (match === null) {
+        return { ok: false, reason: "Cache-Control must include max-age" };
+    }
+    const maxAge = Number(match[1]);
+    if (!Number.isInteger(maxAge) || maxAge < MIN_CACHE_TTL_MS / 1000) {
+        return {
+            ok: false,
+            reason: `Cache-Control max-age must be >= ${MIN_CACHE_TTL_MS / 1000} (got ${maxAge})`,
+        };
+    }
+    return { ok: true, maxAge };
+}
+function mapUnsafe(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return new UcpError("unsafe_target", `UCP profile target rejected: ${detail}`);
+}
+/** 缓存上限（评审项 L3：此前无驱逐，发现大量对端后内存永久累积）。 */
+const MAX_CACHE_ENTRIES = 512;
+export class UcpResolver {
+    deps;
+    cache = new Map();
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
+    }
+    profileUrlFor(input) {
+        if (input.domain !== undefined && input.profileUrl !== undefined) {
+            throw new UcpError("invalid_input", "UcpResolveInput must provide exactly one of domain or profileUrl");
+        }
+        if (input.profileUrl !== undefined)
+            return input.profileUrl;
+        if (input.domain !== undefined) {
+            try {
+                const url = new URL(`https://${input.domain}${WELL_KNOWN_UCP_PATH}`);
+                if (url.hostname.length === 0 || url.username !== "" || url.password !== "") {
+                    throw new Error("invalid host");
+                }
+                return url.href;
+            }
+            catch {
+                throw new UcpError("invalid_input", `domain is not a valid host: "${input.domain}"`);
+            }
+        }
+        throw new UcpError("invalid_input", "UcpResolveInput must provide domain or profileUrl");
+    }
+    async resolve(input) {
+        const url = this.profileUrlFor(input);
+        const now = this.now();
+        const hit = this.cache.get(url);
+        if (hit !== undefined && hit.expiresAt > now) {
+            return { ...hit.result, cached: true };
+        }
+        if (hit !== undefined)
+            this.cache.delete(url); // 过期条目立即移除（此前滞留到同 URL 再次访问）
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new UcpError("invalid_input", `invalid profile URL: ${url}`);
+        }
+        if (parsed.protocol !== "https:") {
+            throw new UcpError("profile_not_https", `UCP profile must be fetched over HTTPS (got ${parsed.protocol})`);
+        }
+        let safeUrl;
+        try {
+            safeUrl = assertSafeTargetUrl(url, { allowPrivateRanges: this.deps.allowPrivateRanges });
+        }
+        catch (err) {
+            throw mapUnsafe(err);
+        }
+        try {
+            await assertResolvableTargetUrl(safeUrl, {
+                allowPrivateRanges: this.deps.allowPrivateRanges,
+                skipDnsCheck: this.deps.skipDnsCheck,
+                resolveIp: this.deps.resolveIp,
+            });
+        }
+        catch (err) {
+            throw mapUnsafe(err);
+        }
+        const fetchImpl = this.deps.fetchImpl ?? globalThis.fetch;
+        const timeoutMs = this.deps.timeoutMs ?? 10_000;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                redirect: "manual",
+                signal: controller.signal,
+                headers: { accept: "application/json" },
+            });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                throw new UcpError("profile_unreachable", `UCP profile fetch timed out after ${timeoutMs}ms`);
+            }
+            throw new UcpError("profile_unreachable", `UCP profile fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (response.redirected ||
+            response.type === "opaqueredirect" ||
+            (response.status >= 300 && response.status < 400)) {
+            throw new UcpError("profile_redirect", `UCP profile fetch must not follow redirects (HTTP ${response.status})`);
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw new UcpError("profile_bad_status", `UCP profile fetch returned HTTP ${response.status}`);
+        }
+        const cacheControl = parseCacheControl(response.headers.get("cache-control"));
+        if (!cacheControl.ok) {
+            throw new UcpError("profile_cache_control", cacheControl.reason ?? "invalid Cache-Control");
+        }
+        let raw;
+        try {
+            // 响应体读取在超时覆盖内 + 大小上限（出站加固）。
+            raw = await readJsonBody(response, { signal: controller.signal });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                throw new UcpError("profile_unreachable", `UCP profile fetch timed out after ${timeoutMs}ms`);
+            }
+            throw new UcpError("profile_malformed", err instanceof SafeHttpError && err.code === "response_too_large"
+                ? err.message
+                : "UCP profile response is not valid JSON");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let validation;
+        try {
+            validation = validateUcpProfile(raw);
+        }
+        catch (err) {
+            if (err instanceof UcpError)
+                throw err;
+            throw new UcpError("profile_malformed", `UCP profile failed validation: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const fetchedAt = this.now();
+        const ttlMs = Math.max(cacheControl.maxAge ?? 60, 60) * 1000;
+        const result = {
+            profile: validation.profile,
+            rejected: validation.rejected,
+            source: input.domain !== undefined ? `domain:${input.domain}` : `profile:${url}`,
+            fetchedAt,
+            ttlMs,
+            cached: false,
+            rawProfile: raw,
+        };
+        // 防无界增长：超限时惰性清除全部过期条目（容量兜底）。
+        if (this.cache.size >= MAX_CACHE_ENTRIES) {
+            for (const [key, entry] of this.cache) {
+                if (entry.expiresAt <= this.now())
+                    this.cache.delete(key);
+            }
+        }
+        this.cache.set(url, { result, expiresAt: fetchedAt + ttlMs });
+        return result;
+    }
+}
+//# sourceMappingURL=resolver.js.map

package/dist/discovery/ucp/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/discovery/ucp/resolver.ts"],"names":[],"mappings":"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"}

package/dist/discovery/ucp/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * UCP Profile 领域类型（UCP 2026-04-08 spec family，基线 §3.2 / §25 / §43）。
+ *
+ * Business 在 `/.well-known/ucp` 发布 profile：
+ *
+ *   {
+ *     ucp: {
+ *       version: "YYYY-MM-DD",
+ *       services: { "<reverse-domain>.<service>": [ { version, spec, transport, endpoint?, schema? } ] },
+ *       capabilities: { "<reverse-domain>.<service>.<capability>": [ { version, spec, schema, extends? } ] },
+ *     },
+ *     signing_keys?: JWK[],
+ *   }
+ *
+ * 命名不变量（基线 §8.3 + UCP namespace authority 规则）：
+ *   - capability 名 = {reverse-domain}.{service}.{capability}（角色三段式）；
+ *   - service 名   = {reverse-domain}.{service}；
+ *   - reverse-domain 反转即 namespace authority host（com.example.* → example.com，
+ *     dev.ucp.* → ucp.dev）；
+ *   - spec/schema URL origin MUST 与 namespace authority 一致。
+ *
+ * 本模块只建模类型与纯函数；运行时校验在 validate.ts，抓取在 resolver.ts。
+ */
+/** UCP service transport 枚举（UCP 2026-04-08）。 */
+export declare const UCP_TRANSPORTS: readonly ["rest", "mcp", "a2a", "embedded"];
+export type UcpTransport = (typeof UCP_TRANSPORTS)[number];
+export interface UcpServiceDeclaration {
+    version: string;
+    spec: string;
+    transport: UcpTransport;
+    /** a2a transport 时 MUST 指向 Agent Card URL（基线 §25）。 */
+    endpoint?: string;
+    schema?: string;
+    /** forward-compat：未知字段保留。 */
+    [key: string]: unknown;
+}
+export interface UcpCapabilityDeclaration {
+    version: string;
+    spec: string;
+    schema: string;
+    /** Vendor Root Capability 不带 extends（基线 §25.2）。 */
+    extends?: string | string[];
+    [key: string]: unknown;
+}
+/** JWK 宽松建模（WP2+ 做签名验证时再收紧）。 */
+export interface UcpSigningKey {
+    kty: string;
+    [key: string]: unknown;
+}
+export interface UcpProfile {
+    ucp: {
+        /** UCP spec family 日期，YYYY-MM-DD（§43 pin 2026-04-08）。 */
+        version: string;
+        services?: Record<string, UcpServiceDeclaration[]>;
+        capabilities?: Record<string, UcpCapabilityDeclaration[]>;
+        [key: string]: unknown;
+    };
+    signing_keys?: UcpSigningKey[];
+    [key: string]: unknown;
+}
+export interface UcpNamespaceParts {
+    reverseDomain: string;
+    authorityHost: string;
+    service: string;
+    capability?: string;
+}
+export declare function isDnsLabel(label: string): boolean;
+/** reverse-domain（如 `com.harrylabsj.kiwi`）→ namespace authority host（`kiwi.harrylabsj.com`）。 */
+export declare function reverseDomainToAuthority(reverseDomain: string): string;
+/**
+ * service 名：{reverse-domain}.{service}。reverse-domain 至少 2 labels（真实反向 DNS）。
+ * 返回 undefined 表示名字不合法（validate.ts 记为 namespace_invalid）。
+ */
+export declare function parseServiceNamespace(name: string): UcpNamespaceParts | undefined;
+/**
+ * capability 名：{reverse-domain}.{service}.{capability}。reverse-domain 至少 2 labels。
+ * 返回 undefined 表示名字不合法（validate.ts 记为 namespace_invalid）。
+ */
+export declare function parseCapabilityNamespace(name: string): UcpNamespaceParts | undefined;
+/** 结构级 HTTPS URL 判定（spec / schema / endpoint）。 */
+export declare function isHttpsUrl(value: unknown): value is string;
+export declare function originHostFor(value: string): string | undefined;

package/dist/discovery/ucp/types.js

@@ -0,0 +1,103 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * UCP Profile 领域类型（UCP 2026-04-08 spec family，基线 §3.2 / §25 / §43）。
+ *
+ * Business 在 `/.well-known/ucp` 发布 profile：
+ *
+ *   {
+ *     ucp: {
+ *       version: "YYYY-MM-DD",
+ *       services: { "<reverse-domain>.<service>": [ { version, spec, transport, endpoint?, schema? } ] },
+ *       capabilities: { "<reverse-domain>.<service>.<capability>": [ { version, spec, schema, extends? } ] },
+ *     },
+ *     signing_keys?: JWK[],
+ *   }
+ *
+ * 命名不变量（基线 §8.3 + UCP namespace authority 规则）：
+ *   - capability 名 = {reverse-domain}.{service}.{capability}（角色三段式）；
+ *   - service 名   = {reverse-domain}.{service}；
+ *   - reverse-domain 反转即 namespace authority host（com.example.* → example.com，
+ *     dev.ucp.* → ucp.dev）；
+ *   - spec/schema URL origin MUST 与 namespace authority 一致。
+ *
+ * 本模块只建模类型与纯函数；运行时校验在 validate.ts，抓取在 resolver.ts。
+ */
+/** UCP service transport 枚举（UCP 2026-04-08）。 */
+export const UCP_TRANSPORTS = ["rest", "mcp", "a2a", "embedded"];
+const DNS_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+export function isDnsLabel(label) {
+    return label.length >= 1 && label.length <= 63 && DNS_LABEL_RE.test(label);
+}
+/** reverse-domain（如 `com.harrylabsj.kiwi`）→ namespace authority host（`kiwi.harrylabsj.com`）。 */
+export function reverseDomainToAuthority(reverseDomain) {
+    return reverseDomain.split(".").reverse().join(".");
+}
+/**
+ * service 名：{reverse-domain}.{service}。reverse-domain 至少 2 labels（真实反向 DNS）。
+ * 返回 undefined 表示名字不合法（validate.ts 记为 namespace_invalid）。
+ */
+export function parseServiceNamespace(name) {
+    const labels = name.split(".");
+    if (labels.length < 3)
+        return undefined;
+    if (!labels.every(isDnsLabel))
+        return undefined;
+    const service = labels[labels.length - 1];
+    const reverseDomain = labels.slice(0, -1).join(".");
+    return { reverseDomain, authorityHost: reverseDomainToAuthority(reverseDomain), service };
+}
+/**
+ * capability 名：{reverse-domain}.{service}.{capability}。reverse-domain 至少 2 labels。
+ * 返回 undefined 表示名字不合法（validate.ts 记为 namespace_invalid）。
+ */
+export function parseCapabilityNamespace(name) {
+    const labels = name.split(".");
+    if (labels.length < 4)
+        return undefined;
+    if (!labels.every(isDnsLabel))
+        return undefined;
+    const capability = labels[labels.length - 1];
+    const service = labels[labels.length - 2];
+    const reverseDomain = labels.slice(0, -2).join(".");
+    return {
+        reverseDomain,
+        authorityHost: reverseDomainToAuthority(reverseDomain),
+        service,
+        capability,
+    };
+}
+/** 结构级 HTTPS URL 判定（spec / schema / endpoint）。 */
+export function isHttpsUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && url.username === "" && url.password === "";
+    }
+    catch {
+        return false;
+    }
+}
+export function originHostFor(value) {
+    try {
+        return new URL(value).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/discovery/ucp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/discovery/ucp/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,CAAU,CAAC;AAgD1E,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,wBAAwB,CAAC,aAAqB;IAC5D,OAAO,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAC3C,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,wBAAwB,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;AAC5F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAC9C,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAC3C,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,OAAO;QACL,aAAa;QACb,aAAa,EAAE,wBAAwB,CAAC,aAAa,CAAC;QACtD,OAAO;QACP,UAAU;KACX,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/discovery/ucp/validate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { UcpProfile } from "./types.js";
+export type UcpRejectionCode = "entry_malformed" | "namespace_invalid" | "transport_unsupported" | "spec_invalid" | "schema_invalid" | "spec_origin_mismatch" | "schema_origin_mismatch" | "endpoint_invalid" | "a2a_endpoint_required" | "extends_invalid";
+export interface UcpRejectedEntry {
+    kind: "service" | "capability";
+    name: string;
+    /** 声明数组内下标；整条 namespace 被拒时为 -1。 */
+    index: number;
+    /** JSON Pointer 风格路径。 */
+    path: string;
+    code: UcpRejectionCode;
+    message: string;
+}
+export interface UcpValidationResult {
+    /** 过滤后的可用 profile（非法条目已剔除）。 */
+    profile: UcpProfile;
+    /** 被拒绝（丢弃）的条目。 */
+    rejected: UcpRejectedEntry[];
+}
+/**
+ * 运行时校验。返回 `{ profile, rejected }`；硬结构错误抛 UcpError("profile_malformed")。
+ * profile 是过滤后的可用版本（非法条目剔除、未知字段保留）。
+ */
+export declare function validateUcpProfile(value: unknown): UcpValidationResult;