@agentxm/extension-content 0.38.0 → 0.39.0

package/dist/src/packaging/archive-guardrails.js

@@ -1,3 +1,4 @@
+import { inflateRawSync } from "node:zlib";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 export class ArchiveGuardrailError extends Data.TaggedError("ArchiveGuardrailError") {
@@ -8,6 +9,8 @@ export const ZIP_LOCAL_SIGNATURE = 0x04034b50;
 const COMPRESSION_STORE = 0;
 const COMPRESSION_DEFLATE = 8;
 const SUPPORTED_COMPRESSION = new Set([COMPRESSION_STORE, COMPRESSION_DEFLATE]);
+// Bound target decoding and segment allocation separately from ordinary payload files.
+const MAX_LINK_TARGET_BYTES = 64 * 1024;
 const S_IFLNK = 0xa000;
 const S_IFMT = 0xf000;
 const textDecoder = new TextDecoder();
@@ -98,10 +101,92 @@ export const parseZipCentralDirectory = (buf) => Effect.gen(function* () {
     }
     return entries;
 });
+const LOCAL_FILE_HEADER_SIZE = 30;
+const INFLATE_CHUNK_SIZE = 16 * 1024;
+export const defaultReadEntry = (archiveBytes, entry) => Effect.gen(function* () {
+    const { localHeaderOffset, compressedSize, compressionMethod, fileName } = entry;
+    if (localHeaderOffset + LOCAL_FILE_HEADER_SIZE > archiveBytes.length) {
+        return yield* new ArchiveGuardrailError({
+            code: "malformed_archive",
+            message: `Local file header for entry "${fileName}" exceeds archive bounds.`,
+            entry: fileName,
+        });
+    }
+    const view = new DataView(archiveBytes.buffer, archiveBytes.byteOffset, archiveBytes.byteLength);
+    const signature = view.getUint32(localHeaderOffset, true);
+    if (signature !== ZIP_LOCAL_SIGNATURE) {
+        return yield* new ArchiveGuardrailError({
+            code: "malformed_archive",
+            message: `Invalid local file header signature for entry "${fileName}".`,
+            entry: fileName,
+        });
+    }
+    const fileNameLength = view.getUint16(localHeaderOffset + 26, true);
+    const extraFieldLength = view.getUint16(localHeaderOffset + 28, true);
+    const dataStart = localHeaderOffset + LOCAL_FILE_HEADER_SIZE + fileNameLength + extraFieldLength;
+    if (dataStart + compressedSize > archiveBytes.length) {
+        return yield* new ArchiveGuardrailError({
+            code: "malformed_archive",
+            message: `Compressed data for entry "${fileName}" exceeds archive bounds.`,
+            entry: fileName,
+        });
+    }
+    const compressedData = archiveBytes.slice(dataStart, dataStart + compressedSize);
+    if (compressionMethod === 0) {
+        if (compressedData.byteLength !== entry.uncompressedSize) {
+            return yield* new ArchiveGuardrailError({
+                code: "malformed_archive",
+                message: `Stored entry size does not match its declaration: "${fileName}".`,
+                entry: fileName,
+            });
+        }
+        return compressedData;
+    }
+    if (compressionMethod === 8) {
+        const expansionFailure = () => new ArchiveGuardrailError({
+            code: "decompression_limit_exceeded",
+            message: `Entry "${fileName}" decompresses beyond its declared size of ${entry.uncompressedSize} bytes.`,
+            entry: fileName,
+        });
+        // workerd grows its bounded zlib buffer by whole chunks, including the
+        // final partial chunk. Reserve one chunk of codec headroom, then enforce
+        // the exact declared size below. Expansion remains bounded during decode.
+        const result = yield* Effect.try({
+            try: () => inflateRawSync(compressedData, {
+                chunkSize: INFLATE_CHUNK_SIZE,
+                maxOutputLength: entry.uncompressedSize + INFLATE_CHUNK_SIZE,
+            }),
+            catch: (error) => {
+                const errorCode = typeof error === "object" &&
+                    error !== null &&
+                    "code" in error &&
+                    typeof error.code === "string"
+                    ? error.code
+                    : "";
+                return errorCode === "ERR_BUFFER_TOO_LARGE" ||
+                    (error instanceof RangeError && error.message === "Memory limit exceeded")
+                    ? expansionFailure()
+                    : new ArchiveGuardrailError({
+                        code: "malformed_archive",
+                        message: `Failed to decompress entry "${fileName}".`,
+                        entry: fileName,
+                    });
+            },
+        });
+        if (result.byteLength > entry.uncompressedSize)
+            return yield* expansionFailure();
+        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+    }
+    return yield* new ArchiveGuardrailError({
+        code: "unsupported_compression",
+        message: `Unsupported compression method ${compressionMethod} for entry "${fileName}".`,
+        entry: fileName,
+    });
+});
 const checkPathTraversal = (entries) => {
     for (const entry of entries) {
         const normalized = entry.fileName.replace(/\\/g, "/");
-        if (normalized.includes("../") || normalized.includes("/..") || normalized === "..") {
+        if (normalized.split("/").includes("..")) {
             return Effect.fail(new ArchiveGuardrailError({
                 code: "path_traversal",
                 message: `Archive entry contains path traversal: "${entry.fileName}".`,
@@ -127,7 +212,7 @@ const checkAbsolutePaths = (entries) => {
 const checkDuplicateEntries = (entries) => {
     const seen = new Set();
     for (const entry of entries) {
-        const normalized = entry.fileName.toLowerCase();
+        const normalized = entry.fileName.replace(/\/$/, "").normalize("NFC").toLowerCase();
         if (seen.has(normalized)) {
             return Effect.fail(new ArchiveGuardrailError({
                 code: "duplicate_entry",
@@ -139,19 +224,127 @@ const checkDuplicateEntries = (entries) => {
     }
     return Effect.void;
 };
-const checkSymlinks = (entries) => {
+// Normalize only for portable identity comparisons; preserve original archive bytes.
+const memberKey = (name) => name.normalize("NFC").toLowerCase();
+const checkMemberTopology = (entries) => Effect.gen(function* () {
+    const members = new Map();
     for (const entry of entries) {
-        const unixMode = entry.externalAttributes >>> 16;
-        if ((unixMode & S_IFMT) === S_IFLNK) {
-            return Effect.fail(new ArchiveGuardrailError({
+        const name = entry.fileName.replace(/\/$/, "");
+        const kind = (entry.externalAttributes >>> 16) & S_IFMT;
+        if (name.length === 0 ||
+            /[\\\0:]/.test(name) ||
+            name.split("/").some((part) => part === "" || part === "." || part === "..") ||
+            ![0, 0x8000, 0x4000, S_IFLNK].includes(kind) ||
+            (entry.fileName.endsWith("/") && kind !== 0 && kind !== 0x4000) ||
+            (kind === 0x4000 && !entry.fileName.endsWith("/"))) {
+            return yield* new ArchiveGuardrailError({
+                code: "malformed_archive",
+                message: `Archive entry has an ambiguous path or unsupported file kind: "${entry.fileName}".`,
+                entry: entry.fileName,
+            });
+        }
+        members.set(memberKey(name), entry);
+    }
+    for (const entry of entries) {
+        const parts = entry.fileName.replace(/\/$/, "").split("/");
+        parts.pop();
+        while (parts.length > 0) {
+            const ancestor = members.get(memberKey(parts.join("/")));
+            if (ancestor !== undefined &&
+                !ancestor.fileName.endsWith("/") &&
+                ((ancestor.externalAttributes >>> 16) & S_IFMT) !== 0x4000) {
+                return yield* new ArchiveGuardrailError({
+                    code: "malformed_archive",
+                    message: `Archive entry is nested beneath a file or link: "${entry.fileName}".`,
+                    entry: entry.fileName,
+                });
+            }
+            parts.pop();
+        }
+    }
+});
+const checkSymlinks = (archiveBytes, entries) => Effect.gen(function* () {
+    const targets = new Map();
+    for (const entry of entries) {
+        if (((entry.externalAttributes >>> 16) & S_IFMT) !== S_IFLNK)
+            continue;
+        if (entry.uncompressedSize > MAX_LINK_TARGET_BYTES) {
+            return yield* new ArchiveGuardrailError({
                 code: "symlink_entry",
-                message: `Archive contains symlink entry: "${entry.fileName}".`,
                 entry: entry.fileName,
-            }));
+                message: `Archive link target exceeds the ${MAX_LINK_TARGET_BYTES}-byte validation limit: "${entry.fileName}".`,
+            });
         }
+        const bytes = yield* defaultReadEntry(archiveBytes, entry);
+        const target = yield* Effect.try({
+            try: () => new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+            catch: () => new ArchiveGuardrailError({
+                code: "symlink_entry",
+                message: `Archive link target is not UTF-8: "${entry.fileName}".`,
+                entry: entry.fileName,
+            }),
+        });
+        if (target.length === 0 || target.startsWith("/") || /[\\\0:]/.test(target)) {
+            return yield* new ArchiveGuardrailError({
+                code: "symlink_entry",
+                message: `Archive link target must be a relative contained path: "${entry.fileName}".`,
+                entry: entry.fileName,
+            });
+        }
+        targets.set(memberKey(entry.fileName), target);
     }
-    return Effect.void;
-};
+    // Expand links before processing subsequent '..' segments, as a filesystem
+    // does. Exit markers distinguish a cycle from a repeated finite traversal.
+    // Bound total interpretation work independently of decompressed byte limits.
+    let remainingSteps = 1_000_000;
+    for (const [name, target] of targets) {
+        const resolved = name.split("/").slice(0, -1);
+        const pending = target.split("/").reverse();
+        const active = new Set([name]);
+        while (pending.length > 0) {
+            if (--remainingSteps < 0) {
+                return yield* new ArchiveGuardrailError({
+                    code: "symlink_entry",
+                    message: "Archive link resolution exceeds the bounded validation budget.",
+                    entry: name,
+                });
+            }
+            const part = pending.pop();
+            if (part === undefined)
+                break;
+            if (typeof part !== "string") {
+                active.delete(part.leave);
+                continue;
+            }
+            if (part === "" || part === ".")
+                continue;
+            if (part === "..") {
+                if (resolved.length === 0) {
+                    return yield* new ArchiveGuardrailError({
+                        code: "symlink_entry",
+                        message: `Archive link escapes its package: "${name}".`,
+                        entry: name,
+                    });
+                }
+                resolved.pop();
+                continue;
+            }
+            const next = memberKey([...resolved, part].join("/"));
+            const nested = targets.get(next);
+            if (nested === undefined) {
+                resolved.push(part);
+                continue;
+            }
+            // A cycle remains inert payload; a filesystem cannot traverse beyond it.
+            if (active.has(next))
+                break;
+            active.add(next);
+            pending.push({ leave: next });
+            for (const segment of nested.split("/").reverse())
+                pending.push(segment);
+        }
+    }
+});
 const checkCompressionMethods = (entries) => {
     for (const entry of entries) {
         if (!SUPPORTED_COMPRESSION.has(entry.compressionMethod)) {
@@ -240,11 +433,12 @@ export const validateArchive = (archiveBytes, limits) => Effect.gen(function* ()
     yield* checkPathTraversal(entries);
     yield* checkAbsolutePaths(entries);
     yield* checkDuplicateEntries(entries);
-    yield* checkSymlinks(entries);
     yield* checkCompressionMethods(entries);
     yield* checkEntryCount(entries, appliedLimits);
     yield* checkDecompressedSize(entries, appliedLimits);
     yield* checkCompressionRatio(entries, appliedLimits);
+    yield* checkMemberTopology(entries);
+    yield* checkSymlinks(archiveBytes, entries);
     return entries;
 });
 //# sourceMappingURL=archive-guardrails.js.map

package/dist/src/packaging/filtered-package-validation.js

@@ -1,20 +1,16 @@
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
-import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { HookManifestSchema, requiredHookRuntimeFiles, } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
 import { parseFrontmatterEffect } from "../content/frontmatter.js";
 import { inspectKnowledgeEntries } from "../knowledge/okf.js";
-import { parseSkillMd } from "../content/skill-content.js";
-import { parseSubagentMd } from "../content/subagent-content.js";
+import { readSubagentPackage } from "../content/subagent-content.js";
 /** A type-specific package invariant failed against the filtered archive. */
 export class FilteredPackageError extends Data.TaggedError("FilteredPackageError") {
 }
 const rawField = (raw, field) => typeof raw === "object" && raw !== null && !Array.isArray(raw)
     ? Reflect.get(raw, field)
     : undefined;
-const safeArchivePath = (value) => value.length > 0 &&
-    !value.startsWith("/") &&
-    !value.includes("\\") &&
-    !value.split("/").some((segment) => segment === "" || segment === "." || segment === "..");
 const requireEntry = (entries, path) => {
     const found = entries.find((entry) => entry.fileName === path);
     return found === undefined
@@ -36,28 +32,25 @@ const readText = (args, path) => Effect.gen(function* () {
 });
 /** Validate the complete type-specific package after Registry-only filtering. */
 export const validateFilteredPackage = (args) => Effect.gen(function* () {
-    const name = args.manifest.identity.name;
     switch (args.type) {
         case "skill": {
             const path = "src/SKILL.md";
-            const content = yield* readText(args, path);
-            if (Option.isNone(parseSkillMd(content, name))) {
-                return yield* new FilteredPackageError({
-                    code: "content_invalid",
-                    detail: `Filtered "${path}" must contain valid Agent Skill frontmatter whose name is "${name}".`,
-                    path,
-                });
-            }
+            // The envelope owns Registry identity. Authoring lint owns the chosen
+            // frontmatter convention; ingest must not rewrite or reject upstream metadata.
+            yield* readText(args, path);
             return;
         }
         case "subagent": {
-            const path = `src/${name}.md`;
-            const content = yield* readText(args, path);
-            yield* parseSubagentMd(content, name).pipe(Effect.mapError(() => new FilteredPackageError({
-                code: "content_invalid",
-                detail: `Filtered "${path}" must contain valid subagent frontmatter whose name is "${name}".`,
-                path,
-            })));
+            yield* readSubagentPackage({
+                manifest: args.manifest.raw,
+                readFile: (path) => readText(args, path),
+            }).pipe(Effect.mapError((error) => error instanceof FilteredPackageError
+                ? error
+                : new FilteredPackageError({
+                    code: error.reason === "reference-invalid" ? "reference_invalid" : "content_invalid",
+                    detail: error.detail,
+                    ...(error.source === undefined ? {} : { path: error.source }),
+                })));
             return;
         }
         case "rule": {
@@ -71,14 +64,14 @@ export const validateFilteredPackage = (args) => Effect.gen(function* () {
             return;
         }
         case "hook": {
-            const entrypoint = rawField(args.manifest.raw, "entrypoint");
-            if (typeof entrypoint !== "string" || !safeArchivePath(entrypoint)) {
-                return yield* new FilteredPackageError({
-                    code: "reference_invalid",
-                    detail: "Hook entrypoint must be a safe package-relative file path.",
-                });
-            }
-            yield* requireEntry(args.entries, entrypoint);
+            const manifest = yield* Schema.decodeUnknownEffect(HookManifestSchema)(args.manifest.raw, {
+                onExcessProperty: "error",
+            }).pipe(Effect.mapError(() => new FilteredPackageError({
+                code: "reference_invalid",
+                detail: "Filtered Hook manifest must declare valid native implementations and safe package-relative references.",
+            })));
+            for (const file of requiredHookRuntimeFiles(manifest))
+                yield* requireEntry(args.entries, file);
             return;
         }
         case "knowledge": {

package/dist/src/packaging/input-normalization.d.ts

@@ -35,6 +35,5 @@ export interface PublishInput {
     readonly clientIntegrity?: string;
     readonly digestHeader?: string;
 }
-export declare const defaultReadEntry: (archiveBytes: Uint8Array, entry: ZipEntry) => Effect.Effect<Uint8Array, ArchiveGuardrailError>;
 export declare const normalizePublishInput: (args: NormalizePublishInputArgs) => Effect.Effect<PublishInput, IngestLimitError | IngestUnsupportedContentTypeError | ArchiveGuardrailError | ManifestError | FilteredPackageError>;
 //# sourceMappingURL=input-normalization.d.ts.map

package/dist/src/packaging/input-normalization.js

@@ -1,84 +1,8 @@
 import * as Effect from "effect/Effect";
-import { inflateRawSync } from "node:zlib";
-import { ArchiveGuardrailError, ZIP_LOCAL_SIGNATURE, validateArchive, } from "./archive-guardrails.js";
+import { ArchiveGuardrailError, defaultReadEntry, validateArchive, } from "./archive-guardrails.js";
 import { enforceArchiveContentType, enforceArchiveSizeLimit, } from "./ingest-limits.js";
 import { resolveManifest, validateDeclaredManifestAlignment, } from "./manifest-policy.js";
 import { FilteredPackageError, validateFilteredPackage } from "./filtered-package-validation.js";
-const LOCAL_FILE_HEADER_SIZE = 30;
-const INFLATE_CHUNK_SIZE = 16 * 1024;
-export const defaultReadEntry = (archiveBytes, entry) => Effect.gen(function* () {
-    const { localHeaderOffset, compressedSize, compressionMethod, fileName } = entry;
-    if (localHeaderOffset + LOCAL_FILE_HEADER_SIZE > archiveBytes.length) {
-        return yield* new ArchiveGuardrailError({
-            code: "malformed_archive",
-            message: `Local file header for entry "${fileName}" exceeds archive bounds.`,
-            entry: fileName,
-        });
-    }
-    const view = new DataView(archiveBytes.buffer, archiveBytes.byteOffset, archiveBytes.byteLength);
-    const signature = view.getUint32(localHeaderOffset, true);
-    if (signature !== ZIP_LOCAL_SIGNATURE) {
-        return yield* new ArchiveGuardrailError({
-            code: "malformed_archive",
-            message: `Invalid local file header signature for entry "${fileName}".`,
-            entry: fileName,
-        });
-    }
-    const fileNameLength = view.getUint16(localHeaderOffset + 26, true);
-    const extraFieldLength = view.getUint16(localHeaderOffset + 28, true);
-    const dataStart = localHeaderOffset + LOCAL_FILE_HEADER_SIZE + fileNameLength + extraFieldLength;
-    if (dataStart + compressedSize > archiveBytes.length) {
-        return yield* new ArchiveGuardrailError({
-            code: "malformed_archive",
-            message: `Compressed data for entry "${fileName}" exceeds archive bounds.`,
-            entry: fileName,
-        });
-    }
-    const compressedData = archiveBytes.slice(dataStart, dataStart + compressedSize);
-    if (compressionMethod === 0) {
-        return compressedData;
-    }
-    if (compressionMethod === 8) {
-        const expansionFailure = () => new ArchiveGuardrailError({
-            code: "decompression_limit_exceeded",
-            message: `Entry "${fileName}" decompresses beyond its declared size of ${entry.uncompressedSize} bytes.`,
-            entry: fileName,
-        });
-        // workerd grows its bounded zlib buffer by whole chunks, including the
-        // final partial chunk. Reserve one chunk of codec headroom, then enforce
-        // the exact declared size below. Expansion remains bounded during decode.
-        const result = yield* Effect.try({
-            try: () => inflateRawSync(compressedData, {
-                chunkSize: INFLATE_CHUNK_SIZE,
-                maxOutputLength: entry.uncompressedSize + INFLATE_CHUNK_SIZE,
-            }),
-            catch: (error) => {
-                const errorCode = typeof error === "object" &&
-                    error !== null &&
-                    "code" in error &&
-                    typeof error.code === "string"
-                    ? error.code
-                    : "";
-                return errorCode === "ERR_BUFFER_TOO_LARGE" ||
-                    (error instanceof RangeError && error.message === "Memory limit exceeded")
-                    ? expansionFailure()
-                    : new ArchiveGuardrailError({
-                        code: "malformed_archive",
-                        message: `Failed to decompress entry "${fileName}".`,
-                        entry: fileName,
-                    });
-            },
-        });
-        if (result.byteLength > entry.uncompressedSize)
-            return yield* expansionFailure();
-        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
-    }
-    return yield* new ArchiveGuardrailError({
-        code: "unsupported_compression",
-        message: `Unsupported compression method ${compressionMethod} for entry "${fileName}".`,
-        entry: fileName,
-    });
-});
 export const normalizePublishInput = (args) => Effect.gen(function* () {
     const { declaredIdentity, archive, digestHeader, guardrailLimits } = args;
     const entryReader = args.readEntry ?? defaultReadEntry;

package/dist/src/packaging/manifest-file.js

@@ -39,7 +39,7 @@ export const readExtensionManifest = (directory, type, options) => Effect.gen(fu
         cause,
     })));
     const raw = withDefaultOwner(parsed, options?.defaultOwner);
-    const manifest = yield* Schema.decodeUnknownEffect(manifestSchemaForType(type))(raw).pipe(Effect.mapError((cause) => new ManifestError({
+    const manifest = yield* Schema.decodeUnknownEffect(manifestSchemaForType(type))(raw, type === "hook" ? { onExcessProperty: "error" } : undefined).pipe(Effect.mapError((cause) => new ManifestError({
         code: "manifest_schema_invalid",
         detail: `Manifest file "${fileName}" does not conform to the ${type} manifest schema.`,
         details: SchemaIssue.makeFormatterDefault()(cause.issue),