@agentxm/registry-protocol 0.28.4-bootstrap.0

package/dist/src/unstable/publish/filtered-package-validation.js

@@ -0,0 +1,117 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+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";
+/** 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
+        ? Effect.fail(new FilteredPackageError({
+            code: "required_file_missing",
+            detail: `Filtered ${path} is required by this package type.`,
+            path,
+        }))
+        : Effect.succeed(found);
+};
+const readText = (args, path) => Effect.gen(function* () {
+    yield* requireEntry(args.entries, path);
+    const bytes = yield* args.readEntry(path).pipe(Effect.mapError(() => new FilteredPackageError({
+        code: "content_invalid",
+        detail: `Could not read filtered package file "${path}".`,
+        path,
+    })));
+    return new TextDecoder().decode(bytes);
+});
+/** 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,
+                });
+            }
+            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,
+            })));
+            return;
+        }
+        case "rule": {
+            const path = "src/RULE.md";
+            const content = yield* readText(args, path);
+            yield* parseFrontmatterEffect(content).pipe(Effect.mapError(() => new FilteredPackageError({
+                code: "content_invalid",
+                detail: `Filtered "${path}" contains invalid frontmatter.`,
+                path,
+            })));
+            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);
+            return;
+        }
+        case "knowledge": {
+            if (rawField(args.manifest.raw, "bundleRoot") !== "src") {
+                return yield* new FilteredPackageError({
+                    code: "reference_invalid",
+                    detail: "Knowledge bundleRoot must resolve to the filtered src directory.",
+                });
+            }
+            yield* readText(args, "src/index.md");
+            const sourcePrefix = "src/";
+            const knowledgeEntries = args.entries
+                .filter((entry) => entry.fileName.startsWith(sourcePrefix))
+                .map((entry) => ({
+                relativePath: entry.fileName.slice(sourcePrefix.length),
+                type: "File",
+                size: BigInt(entry.uncompressedSize),
+            }));
+            const inspection = yield* inspectKnowledgeEntries(knowledgeEntries, (relativePath) => readText(args, `${sourcePrefix}${relativePath}`));
+            const errors = inspection.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+            if (errors.length > 0) {
+                return yield* new FilteredPackageError({
+                    code: "content_invalid",
+                    detail: `Filtered Knowledge bundle is invalid: ${errors
+                        .map((diagnostic) => `${diagnostic.relativePath}: ${diagnostic.message}`)
+                        .join("; ")}`,
+                });
+            }
+            return;
+        }
+        case "mcp-server":
+        case "pack":
+            return;
+    }
+});
+//# sourceMappingURL=filtered-package-validation.js.map

package/dist/src/unstable/publish/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { ArchiveGuardrailError, type ArchiveGuardrailLimits, type ZipEntry, checkForbiddenSourceEntries, validateArchive, } from "./archive-guardrails.js";
+export { FilteredPackageError, type ValidateFilteredPackageArgs, validateFilteredPackage, } from "./filtered-package-validation.js";
+export { IngestLimitError, IngestUnsupportedContentTypeError, REGISTRY_PUBLISH_MAX_ARCHIVE_BYTES, REGISTRY_PUBLISH_MAX_REQUEST_BYTES, enforceArchiveContentType, enforceArchiveSizeLimit, enforceRequestSizeLimit, } from "./ingest-limits.js";
+export { type NormalizePublishInputArgs, type PublishArchiveInput, type PublishInput, normalizePublishInput, } from "./input-normalization.js";
+export { type DeclaredPublishIdentity, ManifestError, type ManifestIdentity, ManifestIdentitySchema, type ResolvedManifest, manifestFilenameForType, validateDeclaredManifestAlignment, } from "./manifest-policy.js";
+export { type PublishVisibility, PublishVisibilitySchema, type ResolveVisibilityIntentArgs, type VisibilityActual, VisibilityActualSchema, type VisibilityComparison, VisibilityComparisonSchema, type VisibilityEvaluation, type VisibilityEvaluationResult, VisibilityEvaluationResultSchema, VisibilityEvaluationSchema, type VisibilityEvaluationUnavailable, VisibilityEvaluationUnavailableSchema, type VisibilityFinding, type VisibilityFindingCode, VisibilityFindingCodeSchema, VisibilityFindingSchema, type VisibilityFingerprint, VisibilityFingerprintSchema, type VisibilityIntent, VisibilityIntentSchema, type VisibilityIntentSource, type VisibilityMutationAuthority, VisibilityMutationAuthoritySchema, type VisibilityMutationRequest, VisibilityMutationRequestSchema, type VisibilityMutationResult, VisibilityMutationResultSchema, type VisibilityRevision, VisibilityRevisionSchema, resolveVisibilityIntent, } from "./visibility.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/publish/index.js

@@ -0,0 +1,12 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { ArchiveGuardrailError, checkForbiddenSourceEntries, validateArchive, } from "./archive-guardrails.js";
+export { FilteredPackageError, validateFilteredPackage, } from "./filtered-package-validation.js";
+export { IngestLimitError, IngestUnsupportedContentTypeError, REGISTRY_PUBLISH_MAX_ARCHIVE_BYTES, REGISTRY_PUBLISH_MAX_REQUEST_BYTES, enforceArchiveContentType, enforceArchiveSizeLimit, enforceRequestSizeLimit, } from "./ingest-limits.js";
+export { normalizePublishInput, } from "./input-normalization.js";
+export { ManifestError, ManifestIdentitySchema, manifestFilenameForType, validateDeclaredManifestAlignment, } from "./manifest-policy.js";
+export { PublishVisibilitySchema, VisibilityActualSchema, VisibilityComparisonSchema, VisibilityEvaluationResultSchema, VisibilityEvaluationSchema, VisibilityEvaluationUnavailableSchema, VisibilityFindingCodeSchema, VisibilityFindingSchema, VisibilityFingerprintSchema, VisibilityIntentSchema, VisibilityMutationAuthoritySchema, VisibilityMutationRequestSchema, VisibilityMutationResultSchema, VisibilityRevisionSchema, resolveVisibilityIntent, } from "./visibility.js";
+//# sourceMappingURL=index.js.map

package/dist/src/unstable/publish/ingest-limits.d.ts

@@ -0,0 +1,25 @@
+import * as Result from "effect/Result";
+export declare const REGISTRY_PUBLISH_MAX_REQUEST_BYTES: number;
+export declare const REGISTRY_PUBLISH_MAX_ARCHIVE_BYTES: number;
+declare const IngestLimitError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "IngestLimitError";
+} & Readonly<A>;
+export declare class IngestLimitError extends IngestLimitError_base<{
+    readonly code: "ingest_request_too_large" | "ingest_archive_too_large" | "ingest_decompression_limit";
+    readonly detail: string;
+    readonly limit?: number;
+    readonly actual?: number;
+}> {
+}
+declare const IngestUnsupportedContentTypeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "IngestUnsupportedContentTypeError";
+} & Readonly<A>;
+export declare class IngestUnsupportedContentTypeError extends IngestUnsupportedContentTypeError_base<{
+    readonly detail: string;
+}> {
+}
+export declare const enforceRequestSizeLimit: (contentLength: number | undefined, maxBytes?: number) => Result.Result<void, IngestLimitError>;
+export declare const enforceArchiveSizeLimit: (archiveBytes: number, maxBytes?: number) => Result.Result<void, IngestLimitError>;
+export declare const enforceArchiveContentType: (contentType: string | undefined) => Result.Result<void, IngestUnsupportedContentTypeError>;
+export {};
+//# sourceMappingURL=ingest-limits.d.ts.map

package/dist/src/unstable/publish/ingest-limits.js

@@ -0,0 +1,41 @@
+import * as Data from "effect/Data";
+import * as Result from "effect/Result";
+export const REGISTRY_PUBLISH_MAX_REQUEST_BYTES = 35 * 1024 * 1024;
+export const REGISTRY_PUBLISH_MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
+export class IngestLimitError extends Data.TaggedError("IngestLimitError") {
+}
+export class IngestUnsupportedContentTypeError extends Data.TaggedError("IngestUnsupportedContentTypeError") {
+}
+export const enforceRequestSizeLimit = (contentLength, maxBytes = REGISTRY_PUBLISH_MAX_REQUEST_BYTES) => {
+    if (contentLength !== undefined && contentLength > maxBytes) {
+        return Result.fail(new IngestLimitError({
+            code: "ingest_request_too_large",
+            detail: `Request body exceeds maximum size of ${maxBytes} bytes.`,
+            limit: maxBytes,
+            actual: contentLength,
+        }));
+    }
+    return Result.void;
+};
+export const enforceArchiveSizeLimit = (archiveBytes, maxBytes = REGISTRY_PUBLISH_MAX_ARCHIVE_BYTES) => {
+    if (archiveBytes > maxBytes) {
+        return Result.fail(new IngestLimitError({
+            code: "ingest_archive_too_large",
+            detail: `Archive exceeds maximum size of ${maxBytes} bytes.`,
+            limit: maxBytes,
+            actual: archiveBytes,
+        }));
+    }
+    return Result.void;
+};
+const V1_ARCHIVE_CONTENT_TYPES = new Set(["application/zip"]);
+export const enforceArchiveContentType = (contentType) => {
+    const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+    if (!normalized || !V1_ARCHIVE_CONTENT_TYPES.has(normalized)) {
+        return Result.fail(new IngestUnsupportedContentTypeError({
+            detail: `Unsupported archive content type: ${contentType ?? "(none)"}. Supported: application/zip.`,
+        }));
+    }
+    return Result.void;
+};
+//# sourceMappingURL=ingest-limits.js.map

package/dist/src/unstable/publish/input-normalization.d.ts

@@ -0,0 +1,40 @@
+import * as Effect from "effect/Effect";
+import type { ExtensionName, ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { ArchiveGuardrailError, type ArchiveGuardrailLimits, type ZipEntry } from "./archive-guardrails.js";
+import { type IngestLimitError, type IngestUnsupportedContentTypeError } from "./ingest-limits.js";
+import { type ManifestError, type ResolvedManifest } from "./manifest-policy.js";
+import type { Version } from "@agentxm/extension-model/unstable/version-constraints";
+import { FilteredPackageError } from "./filtered-package-validation.js";
+export interface DeclaredPublishIdentity {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version;
+}
+export interface PublishArchiveInput {
+    readonly archiveBytes: Uint8Array;
+    readonly archiveContentType?: string;
+    readonly clientIntegrity?: string;
+}
+export interface NormalizePublishInputArgs {
+    readonly declaredIdentity: DeclaredPublishIdentity;
+    readonly archive: PublishArchiveInput;
+    readonly digestHeader?: string;
+    readonly readEntry?: (archiveBytes: Uint8Array, entry: ZipEntry) => Effect.Effect<Uint8Array, ArchiveGuardrailError>;
+    readonly guardrailLimits?: ArchiveGuardrailLimits;
+}
+export interface PublishInput {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version;
+    readonly archiveBytes: Uint8Array;
+    readonly archiveContentType: string;
+    readonly manifest: ResolvedManifest;
+    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/unstable/publish/input-normalization.js

@@ -0,0 +1,125 @@
+import * as Effect from "effect/Effect";
+import { inflateRawSync } from "node:zlib";
+import { ArchiveGuardrailError, ZIP_LOCAL_SIGNATURE, 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;
+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) {
+        // Cap actual decompression at the declared (guardrail-validated) size so a
+        // small deflate stream cannot expand into a memory bomb, and route any
+        // inflate throw into the typed error channel instead of an uncaught defect.
+        const result = yield* Effect.try({
+            try: () => inflateRawSync(compressedData, { maxOutputLength: entry.uncompressedSize }),
+            catch: (error) => {
+                const errorCode = typeof error === "object" &&
+                    error !== null &&
+                    "code" in error &&
+                    typeof error.code === "string"
+                    ? error.code
+                    : "";
+                return errorCode === "ERR_BUFFER_TOO_LARGE"
+                    ? new ArchiveGuardrailError({
+                        code: "decompression_limit_exceeded",
+                        message: `Entry "${fileName}" decompresses beyond its declared size of ${entry.uncompressedSize} bytes.`,
+                        entry: fileName,
+                    })
+                    : new ArchiveGuardrailError({
+                        code: "malformed_archive",
+                        message: `Failed to decompress entry "${fileName}".`,
+                        entry: fileName,
+                    });
+            },
+        });
+        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;
+    yield* Effect.fromResult(enforceArchiveContentType(archive.archiveContentType));
+    yield* Effect.fromResult(enforceArchiveSizeLimit(archive.archiveBytes.length));
+    const entries = yield* validateArchive(archive.archiveBytes, guardrailLimits);
+    const manifest = yield* resolveManifest({
+        type: declaredIdentity.type,
+        entries,
+        readEntry: (fileName) => {
+            const entry = entries.find((candidate) => candidate.fileName === fileName);
+            if (entry === undefined) {
+                return Effect.fail(new ArchiveGuardrailError({
+                    code: "malformed_archive",
+                    message: `Entry "${fileName}" not found in archive.`,
+                    entry: fileName,
+                }));
+            }
+            return entryReader(archive.archiveBytes, entry);
+        },
+    });
+    yield* Effect.fromResult(validateDeclaredManifestAlignment(declaredIdentity, manifest.identity));
+    yield* validateFilteredPackage({
+        type: declaredIdentity.type,
+        entries,
+        manifest,
+        readEntry: (fileName) => {
+            const entry = entries.find((candidate) => candidate.fileName === fileName);
+            return entry === undefined
+                ? Effect.fail(new FilteredPackageError({
+                    code: "required_file_missing",
+                    detail: `Filtered package file "${fileName}" is missing.`,
+                    path: fileName,
+                }))
+                : entryReader(archive.archiveBytes, entry);
+        },
+    });
+    return {
+        owner: declaredIdentity.owner,
+        type: declaredIdentity.type,
+        name: declaredIdentity.name,
+        version: declaredIdentity.version,
+        archiveBytes: archive.archiveBytes,
+        archiveContentType: archive.archiveContentType ?? "application/zip",
+        manifest,
+        ...(archive.clientIntegrity === undefined
+            ? {}
+            : { clientIntegrity: archive.clientIntegrity }),
+        ...(digestHeader === undefined ? {} : { digestHeader }),
+    };
+});
+//# sourceMappingURL=input-normalization.js.map