@mdbase-dev/connect-protocol 0.1.0-beta.28 → 0.1.0-beta.29

package/dist/connect-problems.generated.d.ts

@@ -463,7 +463,14 @@ export interface ConnectProblemDetailsByCode {
         "missing_operations": Array<string>;
     };
     "invalid_application_authorization": undefined;
-    "invalid_application_manifest": undefined;
+    "invalid_application_manifest": {
+        "issues": Array<{
+            "path": string;
+            "keyword": string;
+            "message": string;
+            "params": Record<string, unknown>;
+        }>;
+    };
     "invalid_callback": undefined;
     "invalid_device_authorization_response": undefined;
     "invalid_encrypted_response": undefined;
@@ -784,7 +791,7 @@ export interface ConnectProblemByCode {
         code: "invalid_application_manifest";
         category: "validation";
         recovery: "fix_request";
-        details?: never;
+        details: ConnectProblemDetailsByCode["invalid_application_manifest"];
     };
     "invalid_callback": ConnectProblemBase & {
         code: "invalid_callback";

package/dist/connect-problems.generated.js

@@ -254,6 +254,40 @@ const CONNECT_PROBLEM_DETAIL_SCHEMAS = {
             }
         }
     },
+    "invalid_application_manifest": {
+        "type": "object",
+        "required": [
+            "issues"
+        ],
+        "properties": {
+            "issues": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": [
+                        "path",
+                        "keyword",
+                        "message",
+                        "params"
+                    ],
+                    "properties": {
+                        "path": {
+                            "type": "string"
+                        },
+                        "keyword": {
+                            "type": "string"
+                        },
+                        "message": {
+                            "type": "string"
+                        },
+                        "params": {
+                            "type": "object"
+                        }
+                    }
+                }
+            }
+        }
+    },
     "operation_invalid": {
         "type": "object",
         "required": [

package/dist/manifest.d.ts

@@ -0,0 +1,45 @@
+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 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;
+/** Validate, normalize optional sections, and return an isolated declaration. */
+export declare function parseAppManifest(value: unknown, options?: ManifestValidationOptions): ValidatedAppManifest;
+export declare function formatManifestValidationIssues(issues: readonly ManifestValidationIssue[]): string;
+export {};

package/dist/manifest.js

@@ -0,0 +1,355 @@
+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 { 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));
+/**
+ * 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 = {}) {
+    const sizeIssue = validateSerializedSize(value, options.maxBytes ?? APPLICATION_MANIFEST_MAX_BYTES);
+    if (sizeIssue)
+        return invalid([sizeIssue]);
+    const candidate = options.allowLocal ? localManifestSchemaCandidate(value) : value;
+    const schemaResult = validationResult(appManifestValidator, candidate);
+    if (!schemaResult.valid)
+        return schemaResult;
+    const issues = [
+        ...validateManifestOrigins(value, options.allowLocal === true),
+        ...validateCapabilityRequirements(value),
+        ...validateProvisionRequirements(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);
+    const manifest = structuredClone(value);
+    return {
+        ...manifest,
+        requirements: manifest.requirements ?? { contracts: [] },
+        provisions: manifest.provisions ?? { type_packs: [] },
+        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 validateCapabilityRequirements(value) {
+    const manifest = asObject(value);
+    const requirements = asObject(manifest.requirements);
+    const capabilities = asObject(requirements.capabilities);
+    if (Object.keys(capabilities).length === 0)
+        return [];
+    const required = Array.isArray(capabilities.required)
+        ? capabilities.required.map(String)
+        : [];
+    const optional = Array.isArray(capabilities.optional)
+        ? capabilities.optional.map(String)
+        : [];
+    const issues = [];
+    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 (Array.isArray(requirements.contracts)
+        && requirements.contracts.length > 0
+        && requirements.access !== "full_collection"
+        && !required.includes("definitions.contracts.current")) {
+        issues.push(issue("/requirements/capabilities/required", "contractCapability", "must require definitions.contracts.current for contract-scoped requirements"));
+    }
+    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("definitions.type-pack.apply")) {
+        issues.push(issue("/requirements/capabilities/required", "typePackCapability", "must require definitions.type-pack.apply when bundled type packs are declared"));
+    }
+    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
+        : {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect-protocol",
-  "version": "0.1.0-beta.28",
+  "version": "0.1.0-beta.29",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -16,15 +16,22 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js"
+    },
     "./schemas/*": "./schemas/*"
   },
   "files": [
     "dist",
     "schemas"
   ],
-  "devDependencies": {
+  "dependencies": {
     "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
     "typescript": "^7.0.2"
   },
   "scripts": {

package/schemas/connect-problem.v1.schema.json

@@ -1904,7 +1904,8 @@
         "code",
         "category",
         "recovery",
-        "message"
+        "message",
+        "details"
       ],
       "properties": {
         "problem_version": {
@@ -1933,6 +1934,42 @@
         "trace_id": {
           "type": "string",
           "minLength": 1
+        },
+        "details": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "issues"
+          ],
+          "properties": {
+            "issues": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "path",
+                  "keyword",
+                  "message",
+                  "params"
+                ],
+                "properties": {
+                  "path": {
+                    "type": "string"
+                  },
+                  "keyword": {
+                    "type": "string"
+                  },
+                  "message": {
+                    "type": "string"
+                  },
+                  "params": {
+                    "type": "object"
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },

package/schemas/connect-problems.v1.catalog.json

@@ -167,7 +167,28 @@
       }
     },
     "invalid_application_authorization": { "category": "validation", "recovery": "fix_request" },
-    "invalid_application_manifest": { "category": "validation", "recovery": "fix_request" },
+    "invalid_application_manifest": {
+      "category": "validation",
+      "recovery": "fix_request",
+      "details": {
+        "required": ["issues"],
+        "properties": {
+          "issues": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["path", "keyword", "message", "params"],
+              "properties": {
+                "path": { "type": "string" },
+                "keyword": { "type": "string" },
+                "message": { "type": "string" },
+                "params": { "type": "object" }
+              }
+            }
+          }
+        }
+      }
+    },
     "invalid_callback": { "category": "validation", "recovery": "fix_request" },
     "invalid_device_authorization_response": { "category": "integrity", "recovery": "contact_support" },
     "invalid_encrypted_response": { "category": "integrity", "recovery": "contact_support" },