@mdbase-dev/connect-protocol 0.1.0-beta.100

package/dist/index.js

@@ -0,0 +1,94 @@
+import { FRESH_APPLICATION_AUTHORIZATION_CAPABILITIES } from "./capabilities.js";
+export * from "./connect-problems.generated.js";
+export * from "./files.js";
+export * from "./operations.js";
+export * from "./mutation-fingerprint.js";
+export * from "./compatibility.js";
+export * from "./capabilities.js";
+export * from "./application-authorization.js";
+export * from "./type-packs.js";
+export * from "./collection-setup.js";
+export const CONTROL_PROTOCOL_VERSION = 1;
+export { AUTHORIZATION_BINDING_PROTOCOL_VERSION as APPLICATION_AUTHORIZATION_PROTOCOL_VERSION } from "./compatibility.js";
+export const LOOPBACK_PROTOCOL_VERSION = 1;
+export const DEFAULT_LOOPBACK_PORT = 28_485;
+export const RELAY_ENCRYPTION_SUITE = "P256-HKDF-SHA256-AES256GCM";
+export const GRANT_ENCRYPTION_PROTOCOL_VERSION = 1;
+export const SYNC_PROTOCOL_VERSION = 1;
+export const CONTRACT_SETUP_CAPABILITY = "contract-setup-v1";
+export const FILE_RELAY_CAPABILITY = "file-relay-v1";
+export const PROTOCOL_USAGE_REPORT_CAPABILITY = "protocol-usage-report-v1";
+export const POLICY_FRESHNESS_LEASE_CAPABILITY = "policy-freshness-lease-v1";
+/** Advertised beta capabilities are intentionally broader than the beta baseline. */
+export const RELAY_REQUIRED_CAPABILITIES = [
+    "application-authorization-v4",
+    "authorization-activation",
+    "encrypted-relay",
+    "policy-ack"
+];
+export const MINIMUM_CONNECTOR_VERSION = "0.1.0-beta.33";
+export const POLICY_FRESHNESS_LEASE_MINIMUM_CONNECTOR_VERSION = "0.1.0-beta.91";
+export const HOSTED_PROVIDER_REQUIRED_CAPABILITIES = [
+    "durable-mutation-journal-v1",
+    "durable-file-lifecycle-v1"
+];
+export const HOSTED_CANDIDATE_B_ACTIVATION_CAPABILITY = "candidate-b-activation-v1";
+export const HOSTED_PROVIDER_CAPABILITIES = [
+    ...FRESH_APPLICATION_AUTHORIZATION_CAPABILITIES,
+    ...HOSTED_PROVIDER_REQUIRED_CAPABILITIES,
+    "mutation-replay-after-credential-retirement-v1",
+    HOSTED_CANDIDATE_B_ACTIVATION_CAPABILITY
+];
+export const APPLICATION_DECLARATION_EVIDENCE_CAPABILITY = "application-declaration-evidence-v1";
+export const RELAY_CAPABILITIES = [
+    ...FRESH_APPLICATION_AUTHORIZATION_CAPABILITIES,
+    APPLICATION_DECLARATION_EVIDENCE_CAPABILITY,
+    ...RELAY_REQUIRED_CAPABILITIES,
+    POLICY_FRESHNESS_LEASE_CAPABILITY,
+    "application-authorization-v5",
+    CONTRACT_SETUP_CAPABILITY,
+    FILE_RELAY_CAPABILITY,
+    PROTOCOL_USAGE_REPORT_CAPABILITY
+];
+export const AUTHORITY_PROOF_VERSION = 1;
+export const AUTHORITY_PROOF_ALGORITHM = "P256-SHA256";
+export const AUTHORITY_PROOF_DOMAIN = "mdbase-authority-request-proof-v1";
+export const AUTHORITY_PROOF_HEADERS = {
+    version: "x-mdbase-proof-version",
+    timestamp: "x-mdbase-proof-timestamp",
+    nonce: "x-mdbase-proof-nonce",
+    signature: "x-mdbase-proof-signature"
+};
+/**
+ * Validate a native OAuth callback against the publisher of its web manifest.
+ * Reverse-domain private-use schemes keep native app identity tied to the
+ * manifest origin; PKCE remains mandatory at the authorization boundary.
+ */
+export function isNativeRedirectUri(url, publisherHostname) {
+    const scheme = url.protocol.slice(0, -1);
+    const publisherPrefix = publisherHostname
+        ?.toLowerCase()
+        .split(".")
+        .reverse()
+        .join(".");
+    return scheme.includes(".")
+        && /^[a-z][a-z0-9+.-]*$/.test(scheme)
+        && !["http", "https", "file", "javascript", "data"].includes(scheme)
+        && (!publisherPrefix
+            || scheme === publisherPrefix
+            || scheme.startsWith(`${publisherPrefix}.`))
+        && url.username === ""
+        && url.password === ""
+        && url.hostname.length > 0
+        && url.hash === "";
+}
+export const CONNECT_SCHEMA_IDS = {
+    appManifest: "https://mdbase.dev/connect/schemas/mdbase-app.v1.json",
+    notificationWebhook: "https://mdbase.dev/connect/schemas/notification-webhook.v1.json",
+    dataContract: "https://mdbase.dev/schemas/v0.3/data-contract.schema.json",
+    eventActionInterop: "https://mdbase.dev/schemas/interop/v0.1/profile.schema.json",
+    protocol: "https://mdbase.dev/connect/schemas/connect-protocol.v1.json",
+    encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v3.json",
+    files: "https://mdbase.dev/connect/schemas/files.v1.json",
+    sync: "https://mdbase.dev/connect/schemas/sync.v1.json"
+};

package/dist/manifest.d.ts

@@ -0,0 +1,62 @@
+import type { LegacyMdbaseAppManifest } from "./index.js";
+export type { LegacyApplicationFileRequirement, LegacyApplicationRequirements, LegacyMdbaseWebAppManifest, LegacyMdbasePortableAppManifest, LegacyMdbaseAppManifest } from "./index.js";
+import { type ApplicationNotifications, type ApplicationProvisions, type ApplicationRequirements, type MdbasePortableAppManifest, type MdbaseWebAppManifest } from "./index.js";
+export declare const APPLICATION_MANIFEST_MAX_BYTES = 524288;
+export interface ManifestValidationIssue {
+    path: string;
+    keyword: string;
+    message: string;
+    params: Record<string, unknown>;
+}
+export type ManifestValidationResult = {
+    valid: true;
+    issues: [];
+} | {
+    valid: false;
+    issues: ManifestValidationIssue[];
+};
+export interface ManifestValidationOptions {
+    /** Allow HTTP only for localhost/loopback developer web manifests. */
+    allowLocal?: boolean;
+    /** Maximum UTF-8 size of the complete declaration. */
+    maxBytes?: number;
+}
+interface ValidatedManifestFields {
+    requirements: ApplicationRequirements;
+    provisions: ApplicationProvisions;
+    notifications: ApplicationNotifications;
+}
+export type ValidatedWebAppManifest = Omit<MdbaseWebAppManifest, keyof ValidatedManifestFields> & ValidatedManifestFields;
+export type ValidatedPortableAppManifest = Omit<MdbasePortableAppManifest, keyof ValidatedManifestFields> & ValidatedManifestFields;
+export type ValidatedAppManifest = ValidatedWebAppManifest | ValidatedPortableAppManifest;
+export type ValidatedLegacyAppManifest = LegacyMdbaseAppManifest & {
+    provisions: ApplicationProvisions;
+    notifications: ApplicationNotifications;
+};
+/** The discriminator describes the original declaration, not a translation. */
+export type VersionedAppManifest = {
+    contractVersion: 1;
+    manifest: ValidatedLegacyAppManifest;
+} | {
+    contractVersion: 2;
+    manifest: ValidatedAppManifest;
+};
+export declare class AppManifestValidationError extends Error {
+    readonly issues: ManifestValidationIssue[];
+    constructor(issues: ManifestValidationIssue[]);
+}
+/**
+ * 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 declare function validateAppManifest(value: unknown, options?: ManifestValidationOptions): ManifestValidationResult;
+/** Explicit opt-in to predecessor declarations; omission defaults to v1. */
+export declare function validateVersionedAppManifest(value: unknown, options?: ManifestValidationOptions): ManifestValidationResult;
+/** Validate, normalize optional sections, and return an isolated declaration. */
+export declare function parseAppManifest(value: unknown, options?: ManifestValidationOptions): ValidatedAppManifest;
+/** Validate and clone without changing capability IDs, file aliases, or version. */
+export declare function parseVersionedAppManifest(value: unknown, options?: ManifestValidationOptions): VersionedAppManifest;
+export declare function formatManifestValidationIssues(issues: readonly ManifestValidationIssue[]): string;

package/dist/manifest.js

@@ -0,0 +1,527 @@
+import { createHash } from "node:crypto";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsModule from "ajv-formats";
+import appManifestSchema from "../schemas/mdbase-app.schema.json" with { type: "json" };
+import legacyAppManifestSchema from "../schemas/mdbase-app.legacy-v1.schema.json" with { type: "json" };
+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";
+    }
+}
+const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+    // `required` may name properties declared by an enclosing oneOf branch.
+    strictRequired: false
+});
+const addFormats = addFormatsModule;
+addFormats(ajv);
+ajv.addSchema(appManifestSchema);
+const appManifestValidator = requiredValidator(String(appManifestSchema.$id));
+ajv.addSchema(legacyAppManifestSchema);
+const legacyAppManifestValidator = requiredValidator(String(legacyAppManifestSchema.$id));
+/**
+ * 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 candidate = options.allowLocal ? localManifestSchemaCandidate(value) : 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 requiredValidator(reference) {
+    const validate = ajv.getSchema(reference);
+    if (!validate)
+        throw new Error(`Canonical schema is unavailable: ${reference}`);
+    return validate;
+}
+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);
+    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 (!secureOrAllowedLocal(homepage, allowLocal)) {
+            return [issue("/homepage", "protocol", "must use HTTPS (or loopback HTTP in local mode)")];
+        }
+        for (const [index, redirect] of manifest.redirect_uris.entries()) {
+            const url = new URL(String(redirect));
+            if (url.origin === homepage.origin && !secureOrAllowedLocal(url, allowLocal)) {
+                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"));
+            }
+        }
+        const packManifest = asObject(provision.manifest);
+        const declaredResources = Array.isArray(packManifest.resources)
+            ? packManifest.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) {
+            issues.push(issue(`/provisions/type_packs/${packIndex}/resources`, "resourceSet", "must match manifest source paths exactly"));
+            continue;
+        }
+        for (const [resourceIndex, resource] of declaredResources.entries()) {
+            const source = String(resource.source);
+            const document = embedded.get(source);
+            if (typeof document !== "string") {
+                issues.push(issue(`/provisions/type_packs/${packIndex}/resources`, "resourceSet", `is missing manifest source ${source}`));
+                continue;
+            }
+            const digest = `sha256:${createHash("sha256").update(document).digest("hex")}`;
+            if (digest !== resource.digest) {
+                issues.push(issue(`/provisions/type_packs/${packIndex}/manifest/resources/${resourceIndex}/digest`, "digest", "does not match the embedded document"));
+            }
+        }
+    }
+    return issues;
+}
+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);
+        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);
+        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;
+}
+function configurationPointerError(path) {
+    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}`));
+    }
+    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) {
+    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]);
+        }
+    }
+    if (Array.isArray(object.redirect_uris)) {
+        object.redirect_uris = object.redirect_uris.map((url) => typeof url === "string" ? schemaSafeLocalUrl(url) : url);
+    }
+    return object;
+}
+function schemaSafeLocalUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === "http:" && isLoopback(url.hostname))
+            url.protocol = "https:";
+        return url.href;
+    }
+    catch {
+        return value;
+    }
+}
+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
+        : {};
+}