@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.149

package/node_modules/@mdbase-dev/connect-protocol/dist/manifest.js

@@ -0,0 +1,643 @@
+import { sha256 as sha256Bytes } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+import { isMap, parseDocument } from "yaml";
+import { appManifestValidator as generatedAppManifestValidator, legacyAppManifestValidator as generatedLegacyAppManifestValidator } from "./manifest-validators.generated.js";
+import { RECORD_EXTENSIONS_CONFIGURATION_PATH } from "./collection-setup.js";
+import { isNativeRedirectUri } from "./index.js";
+export const APPLICATION_MANIFEST_MAX_BYTES = 524_288;
+export class AppManifestValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid application manifest: ${formatManifestValidationIssues(issues)}`);
+        this.issues = issues;
+        this.name = "AppManifestValidationError";
+    }
+}
+// Precompiled from the published JSON Schemas by
+// scripts/generate-manifest-validators.mjs, so validation stays synchronous and
+// identical without shipping the Ajv compiler to consumers.
+const appManifestValidator = generatedAppManifestValidator;
+const legacyAppManifestValidator = generatedLegacyAppManifestValidator;
+/**
+ * Validate the complete bundled application declaration accepted by Connect.
+ *
+ * This is the canonical runtime validator used by the server and developer
+ * tooling. Keep structural rules in the published JSON Schema and cross-field
+ * rules here; consumers must not maintain parallel manifest validators.
+ */
+export function validateAppManifest(value, options = {}) {
+    return validateManifest(value, options, false);
+}
+/** Explicit opt-in to predecessor declarations; omission defaults to v1. */
+export function validateVersionedAppManifest(value, options = {}) {
+    return validateManifest(value, options, true);
+}
+function declaredContractVersion(value) {
+    const requirements = asObject(asObject(value).requirements);
+    return requirements.capabilities === undefined
+        ? 1
+        : asObject(requirements.capabilities).contract_version;
+}
+function validateManifest(value, options, versioned) {
+    const sizeIssue = validateSerializedSize(value, options.maxBytes ?? APPLICATION_MANIFEST_MAX_BYTES);
+    if (sizeIssue)
+        return invalid([sizeIssue]);
+    const version = versioned ? declaredContractVersion(value) : 2;
+    if (version !== 1 && version !== 2) {
+        return invalid([issue("/requirements/capabilities/contract_version", "contractVersion", "must declare supported contract version 1 or 2")]);
+    }
+    const native = asObject(value).platform === "native";
+    const candidate = options.allowLocal || native ? localManifestSchemaCandidate(value, !options.allowLocal) : value;
+    const schemaResult = validationResult(version === 1 ? legacyAppManifestValidator : appManifestValidator, candidate);
+    if (!schemaResult.valid)
+        return schemaResult;
+    const issues = [
+        ...validateManifestOrigins(value, options.allowLocal === true),
+        ...(version === 1
+            ? validateLegacyCapabilityRequirements(value)
+            : validateCapabilityRequirements(value)),
+        ...validateProvisionRequirements(value),
+        ...validateConfigurationSetup(value)
+    ];
+    return issues.length === 0 ? { valid: true, issues: [] } : invalid(issues);
+}
+/** Validate, normalize optional sections, and return an isolated declaration. */
+export function parseAppManifest(value, options = {}) {
+    const result = validateAppManifest(value, options);
+    if (!result.valid)
+        throw new AppManifestValidationError(result.issues);
+    return normalizeManifest(value);
+}
+/** Validate and clone without changing capability IDs, file aliases, or version. */
+export function parseVersionedAppManifest(value, options = {}) {
+    const result = validateVersionedAppManifest(value, options);
+    if (!result.valid)
+        throw new AppManifestValidationError(result.issues);
+    return declaredContractVersion(value) === 1
+        ? { contractVersion: 1, manifest: normalizeManifest(value) }
+        : { contractVersion: 2, manifest: normalizeManifest(value) };
+}
+function normalizeManifest(value) {
+    const manifest = structuredClone(value);
+    return {
+        ...manifest,
+        requirements: {
+            configuration: [],
+            ...manifest.requirements
+        },
+        provisions: {
+            type_packs: [],
+            configuration: [],
+            ...manifest.provisions
+        },
+        notifications: manifest.notifications ?? { criteria: [] }
+    };
+}
+export function formatManifestValidationIssues(issues) {
+    return issues.map((issue) => `${issue.path || "/"} ${issue.message}`).join("; ");
+}
+function validationResult(validate, value) {
+    if (validate(value))
+        return { valid: true, issues: [] };
+    const issues = (validate.errors ?? []).map(validationIssue);
+    const specific = issues.filter((issue) => issue.keyword !== "oneOf");
+    return invalid(specific.length > 0 ? specific : issues);
+}
+function validationIssue(error) {
+    const params = error.params;
+    if (error.keyword === "required" && typeof params.missingProperty === "string") {
+        return {
+            path: joinPointer(error.instancePath, params.missingProperty),
+            keyword: error.keyword,
+            message: "is required",
+            params
+        };
+    }
+    if (error.keyword === "additionalProperties"
+        && typeof params.additionalProperty === "string") {
+        return {
+            path: joinPointer(error.instancePath, params.additionalProperty),
+            keyword: error.keyword,
+            message: "is not allowed",
+            params
+        };
+    }
+    return {
+        path: error.instancePath,
+        keyword: error.keyword,
+        message: error.message ?? "is invalid",
+        params
+    };
+}
+function joinPointer(parent, child) {
+    const escaped = child.replaceAll("~", "~0").replaceAll("/", "~1");
+    return `${parent}/${escaped}`;
+}
+function validateSerializedSize(value, maxBytes) {
+    const jsonIssue = validateJsonValue(value, "", new WeakSet());
+    if (jsonIssue)
+        return jsonIssue;
+    try {
+        const serialized = JSON.stringify(value);
+        const bytes = new TextEncoder().encode(serialized).byteLength;
+        return bytes <= maxBytes
+            ? undefined
+            : issue("/", "maxBytes", `must not exceed ${maxBytes} UTF-8 bytes`, { maxBytes, actualBytes: bytes });
+    }
+    catch {
+        return issue("/", "json", "must be serializable as JSON");
+    }
+}
+function validateJsonValue(value, path, ancestors) {
+    if (value === null
+        || typeof value === "string"
+        || typeof value === "boolean"
+        || (typeof value === "number" && Number.isFinite(value)))
+        return undefined;
+    if (typeof value !== "object") {
+        return issue(path || "/", "json", "must be a JSON value");
+    }
+    if (ancestors.has(value)) {
+        return issue(path || "/", "json", "must not contain circular references");
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        return issue(path || "/", "json", "must be a plain JSON object");
+    }
+    ancestors.add(value);
+    const entries = Array.isArray(value)
+        ? value.map((item, index) => [String(index), item])
+        : Object.entries(value);
+    for (const [key, child] of entries) {
+        const childIssue = validateJsonValue(child, joinPointer(path, key), ancestors);
+        if (childIssue)
+            return childIssue;
+    }
+    ancestors.delete(value);
+    return undefined;
+}
+function validateManifestOrigins(value, allowLocal) {
+    const manifest = asObject(value);
+    const native = manifest.platform === "native";
+    for (const [environment, policy] of Object.entries(asObject(manifest.installation_origins))) {
+        for (const [kind, origins] of Object.entries(asObject(policy))) {
+            for (const [index, origin] of origins.entries()) {
+                const path = `/installation_origins/${environment}/${kind}/${index}`;
+                try {
+                    if (native && (kind !== "app-runtime" || !isNativeLoopbackOrigin(origin))) {
+                        return [issue(path, "origin", "native applications require canonical IPv4 loopback HTTP app-runtime origins")];
+                    }
+                    const url = new URL(origin);
+                    const web = (secureOrAllowedLocal(url, environment === "lab")
+                        || (native && isNativeLoopbackOrigin(origin))) && url.origin === origin;
+                    const mobile = kind === "mobile" && url.protocol === "capacitor:"
+                        && /^[a-z0-9.-]+$/u.test(url.hostname) && `${url.protocol}//${url.host}` === origin;
+                    // A Chrome extension ID is stable (derived from its key), so it can be
+                    // declared exactly. Firefox extension origins are random per profile.
+                    const extension = kind === "app-runtime" && /^chrome-extension:\/\/[a-p]{32}$/u.test(origin);
+                    if ((!web && !mobile && !extension) || origin.includes("*") || url.username || url.password || url.search || url.hash) {
+                        return [issue(path, "origin", "must be an exact HTTPS, loopback HTTP, mobile capacitor or Chrome extension origin without wildcards")];
+                    }
+                }
+                catch {
+                    return [issue(path, "origin", "must be an exact installation origin")];
+                }
+            }
+        }
+    }
+    if (manifest.distribution === "portable") {
+        if (manifest.project_url === undefined) {
+            return manifest.icon === undefined
+                ? []
+                : [issue("/icon", "origin", "requires a project_url on the same origin")];
+        }
+        try {
+            const project = new URL(String(manifest.project_url));
+            if (project.protocol !== "https:") {
+                return [issue("/project_url", "protocol", "must use HTTPS")];
+            }
+            if (manifest.icon !== undefined
+                && new URL(String(manifest.icon)).origin !== project.origin) {
+                return [issue("/icon", "origin", "must use the project_url origin")];
+            }
+            return [];
+        }
+        catch {
+            return [issue("/", "url", "contains an invalid URL")];
+        }
+    }
+    try {
+        const homepage = new URL(String(manifest.homepage));
+        if (native ? !isNativeLoopbackUrl(String(manifest.homepage)) : !secureOrAllowedLocal(homepage, allowLocal)) {
+            return [issue("/homepage", "protocol", native ? "native applications require canonical IPv4 loopback HTTP" : "must use HTTPS (or loopback HTTP in local mode)")];
+        }
+        for (const [index, redirect] of manifest.redirect_uris.entries()) {
+            // Redirects match exactly (RFC 8252 §8.10); a wildcard is never a pattern.
+            if (String(redirect).includes("*")) {
+                return [issue(`/redirect_uris/${index}`, "url", "must be an exact URI without wildcards")];
+            }
+            const url = new URL(String(redirect));
+            if (native && ["http:", "https:"].includes(url.protocol) && !isNativeLoopbackUrl(String(redirect))) {
+                return [issue(`/redirect_uris/${index}`, "origin", "native HTTP(S) redirects require canonical IPv4 loopback HTTP")];
+            }
+            if (url.origin === homepage.origin && !secureOrAllowedLocal(url, allowLocal)
+                && !(native && isNativeLoopbackUrl(String(redirect)))) {
+                return [issue(`/redirect_uris/${index}`, "protocol", "must use HTTPS (or loopback HTTP in local mode)")];
+            }
+            const nativeAllowed = nativeRedirectMatchesApplication(url, String(manifest.id));
+            if (url.origin !== homepage.origin && !nativeAllowed) {
+                return [issue(`/redirect_uris/${index}`, "origin", "must use the homepage origin or a private-use scheme matching the application ID")];
+            }
+        }
+        if (manifest.icon !== undefined
+            && new URL(String(manifest.icon)).origin !== homepage.origin) {
+            return [issue("/icon", "origin", "must use the homepage origin")];
+        }
+        return [];
+    }
+    catch {
+        return [issue("/", "url", "contains an invalid URL")];
+    }
+}
+function nativeRedirectMatchesApplication(url, applicationId) {
+    const scheme = url.protocol.slice(0, -1);
+    return isNativeRedirectUri(url)
+        && (scheme === applicationId || scheme.startsWith(`${applicationId}.`));
+}
+function validateProvisionRequirements(value) {
+    const manifest = asObject(value);
+    const requirements = asObject(manifest.requirements);
+    const requiredContracts = Array.isArray(requirements.contracts)
+        ? requirements.contracts
+        : [];
+    const required = new Set(requiredContracts.map((contract) => {
+        const value = asObject(contract);
+        return `${value.id}@${value.version}`;
+    }));
+    const provisions = asObject(manifest.provisions);
+    const packs = Array.isArray(provisions.type_packs) ? provisions.type_packs : [];
+    const issues = [];
+    for (const [packIndex, provisionValue] of packs.entries()) {
+        const provision = asObject(provisionValue);
+        const providedContracts = Array.isArray(provision.provides)
+            ? provision.provides
+            : [];
+        for (const providedValue of providedContracts) {
+            const provided = asObject(providedValue);
+            if (!required.has(`${provided.id}@${provided.version}`)) {
+                issues.push(issue(`/provisions/type_packs/${packIndex}/provides`, "contractRequirement", "may only contain contracts required by the application"));
+            }
+        }
+        issues.push(...validateTypePackProvision(provision, `/provisions/type_packs/${packIndex}`));
+    }
+    return issues;
+}
+/**
+ * Validate one schema-valid type-pack provision beyond its JSON Schema: the
+ * embedded resources are exactly the manifest's, each digest pins its bytes,
+ * and every seed `upgrade_from` baseline satisfies mdbase 05A. Issue paths are
+ * prefixed with `path`, the provision's location in its enclosing document.
+ */
+export function validateTypePackProvision(value, path = "") {
+    const provision = asObject(value);
+    const manifest = asObject(provision.manifest);
+    const declaredResources = Array.isArray(manifest.resources)
+        ? manifest.resources.map(asObject)
+        : [];
+    const embeddedResources = Array.isArray(provision.resources)
+        ? provision.resources.map(asObject)
+        : [];
+    const embedded = new Map(embeddedResources.map((resource) => [String(resource.source), resource.document]));
+    if (embedded.size !== embeddedResources.length
+        || new Set(declaredResources.map((resource) => String(resource.source))).size
+            !== declaredResources.length
+        || declaredResources.length !== embeddedResources.length) {
+        return [issue(`${path}/resources`, "resourceSet", "must match manifest source paths exactly")];
+    }
+    const issues = [];
+    for (const [resourceIndex, resource] of declaredResources.entries()) {
+        const resourcePath = `${path}/manifest/resources/${resourceIndex}`;
+        const source = String(resource.source);
+        const document = embedded.get(source);
+        if (typeof document !== "string") {
+            issues.push(issue(`${path}/resources`, "resourceSet", `is missing manifest source ${source}`));
+            continue;
+        }
+        if (sha256(document) !== resource.digest) {
+            issues.push(issue(`${resourcePath}/digest`, "digest", "does not match the embedded document"));
+        }
+        if (resource.upgrade_from !== undefined) {
+            issues.push(...validateSeedUpgrade(resource, document, `${resourcePath}/upgrade_from`));
+        }
+    }
+    return issues;
+}
+/** 05A seed-upgrade baselines: exact, distinct, earlier starters of the same type. */
+function validateSeedUpgrade(resource, document, path) {
+    if (resource.kind !== "type" || resource.mode !== "seed") {
+        return [issue(path, "seedUpgrade", "is only allowed for seed types")];
+    }
+    const desired = typeFrontmatter(document);
+    const listed = Array.isArray(resource.upgrade_from);
+    const baselines = (listed ? resource.upgrade_from : [resource.upgrade_from]).map(asObject);
+    const seen = new Set();
+    const issues = [];
+    for (const [index, baseline] of baselines.entries()) {
+        const baselinePath = listed ? `${path}/${index}` : path;
+        const baselineDocument = String(baseline.document);
+        if (baseline.digest !== sha256(baselineDocument)) {
+            issues.push(issue(`${baselinePath}/digest`, "digest", "does not match the baseline document"));
+        }
+        else if (seen.has(baseline.digest)) {
+            issues.push(issue(`${baselinePath}/digest`, "uniqueBaseline", "duplicates another upgrade baseline"));
+        }
+        else if (baseline.digest === resource.digest) {
+            issues.push(issue(`${baselinePath}/digest`, "seedUpgrade", "must not be the resource's own document"));
+        }
+        seen.add(baseline.digest);
+        const previous = typeFrontmatter(baselineDocument);
+        if (!desired || !previous || previous.kind !== desired.kind || previous.name !== desired.name) {
+            issues.push(issue(`${baselinePath}/document`, "seedUpgrade", "must be a type document with the same kind and name as the resource"));
+        }
+        else if (baseline.version !== undefined && previous.version !== baseline.version) {
+            issues.push(issue(`${baselinePath}/version`, "seedUpgrade", "must equal the version the baseline document declares"));
+        }
+    }
+    return issues;
+}
+/** Top-level frontmatter of a type document, or undefined when it has none. */
+// The identity a type document declares. Only these top-level keys are read, so
+// anchors and aliases elsewhere in a starter are harmless and alias expansion
+// stays disabled.
+function typeFrontmatter(document) {
+    const source = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(document)?.[1];
+    if (source === undefined)
+        return undefined;
+    const parsed = parseDocument(source, { uniqueKeys: true });
+    if (parsed.errors.length > 0 || !isMap(parsed.contents))
+        return undefined;
+    return { kind: parsed.get("kind"), name: parsed.get("name"), version: parsed.get("version") };
+}
+function sha256(document) {
+    return `sha256:${bytesToHex(sha256Bytes(utf8ToBytes(document)))}`;
+}
+function validateConfigurationSetup(value) {
+    const manifest = asObject(value);
+    const requirements = asObject(manifest.requirements);
+    const provisions = asObject(manifest.provisions);
+    const requiredValues = Array.isArray(requirements.configuration)
+        ? requirements.configuration
+        : [];
+    const provisionValues = Array.isArray(provisions.configuration)
+        ? provisions.configuration
+        : [];
+    const issues = [];
+    const required = new Map();
+    for (const [index, candidate] of requiredValues.entries()) {
+        const requirement = asObject(candidate);
+        const id = String(requirement.id);
+        const path = String(requirement.path);
+        const pathError = configurationPointerError(path, requirement.value);
+        if (pathError) {
+            issues.push(issue(`/requirements/configuration/${index}/path`, "configurationPointer", pathError));
+        }
+        if (required.has(id)) {
+            issues.push(issue(`/requirements/configuration/${index}/id`, "uniqueRequirement", `duplicates configuration requirement ${id}`));
+        }
+        else {
+            required.set(id, { path, value: requirement.value, index });
+        }
+    }
+    const linked = new Set();
+    const contributionKeys = new Set();
+    for (const [index, candidate] of provisionValues.entries()) {
+        const provision = asObject(candidate);
+        const requirementId = String(provision.requirement);
+        const path = String(provision.path);
+        const pathError = configurationPointerError(path, provision.value);
+        if (pathError) {
+            issues.push(issue(`/provisions/configuration/${index}/path`, "configurationPointer", pathError));
+        }
+        const requirement = required.get(requirementId);
+        if (!requirement) {
+            issues.push(issue(`/provisions/configuration/${index}/requirement`, "configurationRequirement", `references unknown configuration requirement ${requirementId}`));
+            continue;
+        }
+        if (linked.has(requirementId)) {
+            issues.push(issue(`/provisions/configuration/${index}/requirement`, "uniqueProvision", `configuration requirement ${requirementId} may have exactly one provision`));
+        }
+        linked.add(requirementId);
+        if (path !== requirement.path) {
+            issues.push(issue(`/provisions/configuration/${index}/path`, "configurationRequirement", `must equal /requirements/configuration/${requirement.index}/path`));
+        }
+        if (JSON.stringify(provision.value) !== JSON.stringify(requirement.value)) {
+            issues.push(issue(`/provisions/configuration/${index}/value`, "configurationRequirement", `must equal /requirements/configuration/${requirement.index}/value`));
+        }
+        const contributionKey = `${path}\0${JSON.stringify(provision.value)}`;
+        if (contributionKeys.has(contributionKey)) {
+            issues.push(issue(`/provisions/configuration/${index}`, "uniqueContribution", "duplicates another configuration path and value contribution"));
+        }
+        contributionKeys.add(contributionKey);
+    }
+    for (const [id, requirement] of required) {
+        if (!linked.has(id)) {
+            issues.push(issue(`/requirements/configuration/${requirement.index}`, "configurationProvision", `requires one provision linked by id ${id}`));
+        }
+    }
+    return issues;
+}
+// Matches mdbase-rs collection setup.
+const APPLICATION_RECORD_EXTENSIONS = ["md", "base"];
+function configurationPointerError(path, value) {
+    if (path === RECORD_EXTENSIONS_CONFIGURATION_PATH) {
+        return APPLICATION_RECORD_EXTENSIONS.includes(value)
+            ? undefined
+            : "accepts only the record extensions md and base";
+    }
+    if (!path.startsWith("/") || new TextEncoder().encode(path).byteLength > 1024) {
+        return "must be a bounded RFC 6901 JSON pointer";
+    }
+    const encoded = path.slice(1).split("/");
+    if (encoded.length < 2 || encoded.length > 16) {
+        return "must address a value below an x-* extension namespace";
+    }
+    const segments = [];
+    for (const value of encoded) {
+        if (/~(?:[^01]|$)/u.test(value))
+            return "contains an invalid RFC 6901 escape";
+        const segment = value.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (segment.length === 0
+            || segment === "-"
+            || /^\d+$/u.test(segment)
+            || [...segment].some((character) => /\p{Cc}/u.test(character)))
+            return "contains a disallowed object-key segment";
+        segments.push(segment);
+    }
+    return /^x-[a-z0-9][a-z0-9-]*$/u.test(segments[0])
+        ? undefined
+        : "must be inside a top-level x-* extension namespace";
+}
+function validateCapabilityRequirements(value) {
+    const manifest = asObject(value);
+    const requirements = asObject(manifest.requirements);
+    const capabilities = asObject(requirements.capabilities);
+    const issues = [];
+    if (requirements.access !== "full_collection") {
+        issues.push(issue("/requirements/access", "collectionAccess", "must explicitly request full_collection; legacy or omitted access is not widened"));
+    }
+    const required = Array.isArray(capabilities.required)
+        ? capabilities.required.map(String)
+        : [];
+    const optional = Array.isArray(capabilities.optional)
+        ? capabilities.optional.map(String)
+        : [];
+    const overlap = optional.find((capability) => required.includes(capability));
+    if (overlap) {
+        issues.push(issue("/requirements/capabilities/optional", "disjoint", `must not repeat required capability ${overlap}`));
+    }
+    const files = asObject(requirements.files);
+    const requiredFiles = Array.isArray(files.required) ? files.required.map(String) : [];
+    const optionalFiles = Array.isArray(files.optional) ? files.optional.map(String) : [];
+    const fileOverlap = optionalFiles.find((action) => requiredFiles.includes(action));
+    if (fileOverlap) {
+        issues.push(issue("/requirements/files/optional", "disjoint", `must not repeat required file action ${fileOverlap}`));
+    }
+    const people = asObject(requirements.people);
+    const requiredPeople = Array.isArray(people.required) ? people.required.map(String) : [];
+    const optionalPeople = Array.isArray(people.optional) ? people.optional.map(String) : [];
+    const peopleOverlap = optionalPeople.find((permission) => requiredPeople.includes(permission));
+    if (peopleOverlap) {
+        issues.push(issue("/requirements/people/optional", "disjoint", `must not repeat required people permission ${peopleOverlap}`));
+    }
+    return issues;
+}
+// Frozen cross-field rules from c2596a6e; notably, absent capabilities skip
+// alias/setup checks rather than inventing or widening a declaration.
+function validateLegacyCapabilityRequirements(value) {
+    const manifest = asObject(value);
+    const requirements = asObject(manifest.requirements);
+    const capabilities = asObject(requirements.capabilities);
+    const issues = [];
+    if (requirements.access !== "full_collection") {
+        issues.push(issue("/requirements/access", "collectionAccess", "must explicitly request full_collection; legacy or omitted access is not widened"));
+    }
+    if (Object.keys(capabilities).length === 0)
+        return issues;
+    const required = Array.isArray(capabilities.required)
+        ? capabilities.required.map(String)
+        : [];
+    const optional = Array.isArray(capabilities.optional)
+        ? capabilities.optional.map(String)
+        : [];
+    const overlap = optional.find((capability) => required.includes(capability));
+    if (overlap) {
+        issues.push(issue("/requirements/capabilities/optional", "disjoint", `must not repeat required capability ${overlap}`));
+    }
+    const declared = new Set([...required, ...optional]);
+    const provisions = asObject(manifest.provisions);
+    if (declared.has("definitions.type-pack.apply")) {
+        if (requirements.access !== "full_collection") {
+            issues.push(issue("/requirements/access", "typePackAccess", "must be full_collection for definitions.type-pack.apply"));
+        }
+    }
+    if (Array.isArray(provisions.type_packs)
+        && provisions.type_packs.length > 0
+        && !required.includes("collection.setup.apply")) {
+        issues.push(issue("/requirements/capabilities/required", "collectionSetupCapability", "must require collection.setup.apply when bundled type packs are declared"));
+    }
+    const hasConfigurationProvisions = Array.isArray(provisions.configuration)
+        && provisions.configuration.length > 0;
+    const hasSetupProvisions = hasConfigurationProvisions
+        || (Array.isArray(provisions.type_packs) && provisions.type_packs.length > 0);
+    if (hasConfigurationProvisions && !required.includes("collection.setup.apply")) {
+        issues.push(issue("/requirements/capabilities/required", "collectionSetupCapability", "must require collection.setup.apply when configuration provisions are declared"));
+    }
+    if (declared.has("collection.setup.apply")) {
+        if (requirements.access !== "full_collection") {
+            issues.push(issue("/requirements/access", "collectionSetupAccess", "must be full_collection for collection.setup.apply"));
+        }
+        if (!hasSetupProvisions) {
+            issues.push(issue("/provisions", "collectionSetupProvision", "must declare a configuration provision or type pack for collection.setup.apply"));
+        }
+    }
+    if (declared.has("notifications.background-delivery")
+        && !Array.isArray(asObject(manifest.notifications).criteria)) {
+        issues.push(issue("/notifications/criteria", "notificationCapability", "must be declared for notifications.background-delivery"));
+    }
+    const fileRequirement = asObject(requirements.files);
+    const fileActions = Array.isArray(fileRequirement.actions)
+        ? new Set(fileRequirement.actions.map(String))
+        : new Set();
+    for (const action of ["list", "read", "add", "replace", "move", "delete"]) {
+        const capability = `files.${action}`;
+        if (declared.has(capability) !== fileActions.has(action)) {
+            issues.push(issue("/requirements/capabilities", "fileCapability", `${capability} and requirements.files.actions.${action} must be declared together`));
+        }
+    }
+    return issues;
+}
+function localManifestSchemaCandidate(value, nativeOnly = false) {
+    const source = asObject(value);
+    if (source.distribution === "portable")
+        return value;
+    // Only URL fields need a schema-safe local substitute. A shallow copy keeps
+    // non-JSON values visible to the schema instead of silently dropping them.
+    const object = { ...source };
+    for (const field of ["homepage", "icon"]) {
+        if (typeof object[field] === "string") {
+            object[field] = schemaSafeLocalUrl(object[field], nativeOnly);
+        }
+    }
+    if (Array.isArray(object.redirect_uris)) {
+        object.redirect_uris = object.redirect_uris.map((url) => typeof url === "string" ? schemaSafeLocalUrl(url, nativeOnly) : url);
+    }
+    return object;
+}
+function schemaSafeLocalUrl(value, nativeOnly) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === "http:" && (nativeOnly ? isNativeLoopbackUrl(value) : isLoopback(url.hostname)))
+            url.protocol = "https:";
+        return url.href;
+    }
+    catch {
+        return value;
+    }
+}
+/** RFC 8252 §7.3 native exception: canonical literal IPv4 only, any valid port.
+ * This classifies transport; the registered manifest, consent and pairing grant authority. */
+export function isNativeLoopbackOrigin(value) {
+    if (typeof value !== "string" || !/^http:\/\/127\.0\.0\.1(?::[1-9][0-9]{0,4})?$/.test(value))
+        return false;
+    try {
+        return new URL(value).origin === value;
+    }
+    catch {
+        return false;
+    }
+}
+function isNativeLoopbackUrl(value) {
+    const origin = /^http:\/\/[^/?#]+/.exec(value)?.[0];
+    return isNativeLoopbackOrigin(origin);
+}
+function secureOrAllowedLocal(url, allowLocal) {
+    return url.protocol === "https:"
+        || (allowLocal && url.protocol === "http:" && isLoopback(url.hostname));
+}
+function isLoopback(hostname) {
+    return hostname === "localhost"
+        || hostname === "127.0.0.1"
+        || hostname === "[::1]"
+        || hostname === "::1";
+}
+function invalid(issues) {
+    return { valid: false, issues };
+}
+function issue(path, keyword, message, params = {}) {
+    return { path, keyword, message, params };
+}
+function asObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}

package/node_modules/@mdbase-dev/connect-protocol/dist/mutation-fingerprint.d.ts

@@ -0,0 +1,6 @@
+import { type EncryptedOperation } from "./operations.js";
+export declare const MUTATION_FINGERPRINT_SCHEMA_VERSION: 1;
+export declare const MUTATION_FINGERPRINT_DOMAIN: "mdbase-connect mutation fingerprint v1\0";
+export declare function canonicalMutationInput(input: unknown): string;
+export declare function mutationFingerprintTranscript(operation: EncryptedOperation, input: unknown): Uint8Array<ArrayBuffer>;
+export declare function mutationFingerprint(operation: EncryptedOperation, input: unknown): Promise<string>;