@mdbase-dev/connect-protocol 0.1.0-beta.126 → 0.1.0-beta.148

package/dist/manifest.d.ts

@@ -67,3 +67,6 @@ export declare function formatManifestValidationIssues(issues: readonly Manifest
  * prefixed with `path`, the provision's location in its enclosing document.
  */
 export declare function validateTypePackProvision(value: unknown, path?: string): ManifestValidationIssue[];
+/** 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 declare function isNativeLoopbackOrigin(value: unknown): value is string;

package/dist/manifest.js

@@ -1,9 +1,7 @@
-import { createHash } from "node:crypto";
-import { Ajv2020 } from "ajv/dist/2020.js";
-import addFormatsModule from "ajv-formats";
+import { sha256 as sha256Bytes } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
 import { isMap, parseDocument } from "yaml";
-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 { 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;
@@ -15,18 +13,11 @@ export class AppManifestValidationError extends Error {
         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));
+// 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.
  *
@@ -55,7 +46,8 @@ function validateManifest(value, options, versioned) {
     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 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;
@@ -104,12 +96,6 @@ function normalizeManifest(value) {
 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: [] };
@@ -192,6 +178,33 @@ function validateJsonValue(value, path, ancestors) {
 }
 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
@@ -215,12 +228,20 @@ function validateManifestOrigins(value, allowLocal) {
     }
     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)")];
+        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 (url.origin === homepage.origin && !secureOrAllowedLocal(url, allowLocal)) {
+            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));
@@ -358,7 +379,7 @@ function typeFrontmatter(document) {
     return { kind: parsed.get("kind"), name: parsed.get("name"), version: parsed.get("version") };
 }
 function sha256(document) {
-    return `sha256:${createHash("sha256").update(document).digest("hex")}`;
+    return `sha256:${bytesToHex(sha256Bytes(utf8ToBytes(document)))}`;
 }
 function validateConfigurationSetup(value) {
     const manifest = asObject(value);
@@ -555,7 +576,7 @@ function validateLegacyCapabilityRequirements(value) {
     }
     return issues;
 }
-function localManifestSchemaCandidate(value) {
+function localManifestSchemaCandidate(value, nativeOnly = false) {
     const source = asObject(value);
     if (source.distribution === "portable")
         return value;
@@ -564,18 +585,18 @@ function localManifestSchemaCandidate(value) {
     const object = { ...source };
     for (const field of ["homepage", "icon"]) {
         if (typeof object[field] === "string") {
-            object[field] = schemaSafeLocalUrl(object[field]);
+            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) : url);
+        object.redirect_uris = object.redirect_uris.map((url) => typeof url === "string" ? schemaSafeLocalUrl(url, nativeOnly) : url);
     }
     return object;
 }
-function schemaSafeLocalUrl(value) {
+function schemaSafeLocalUrl(value, nativeOnly) {
     try {
         const url = new URL(value);
-        if (url.protocol === "http:" && isLoopback(url.hostname))
+        if (url.protocol === "http:" && (nativeOnly ? isNativeLoopbackUrl(value) : isLoopback(url.hostname)))
             url.protocol = "https:";
         return url.href;
     }
@@ -583,6 +604,22 @@ function schemaSafeLocalUrl(value) {
         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));

package/dist/next-authorization.d.ts

@@ -0,0 +1,30 @@
+import { type ApplicationCapabilityId } from "./capabilities.js";
+import type { ApplicationRequirements, LegacyApplicationRequirements } from "./application-declaration.js";
+import type { FileAction } from "./files.js";
+import type { CollectionOperation } from "./operations.js";
+/** Exact record/file pairs used by both consent and next policy publication. */
+export declare const NEXT_CAPABILITY_FILE_ACTIONS: Partial<Record<ApplicationCapabilityId, readonly FileAction[]>>;
+export interface NextAuthorizationGroup {
+    id: ApplicationCapabilityId;
+    operations: CollectionOperation[];
+    fileActions: readonly FileAction[];
+    required: boolean;
+}
+type Requirements = {
+    access?: ApplicationRequirements["access"];
+    capabilities?: ApplicationRequirements["capabilities"] | LegacyApplicationRequirements["capabilities"];
+    files?: ApplicationRequirements["files"] | LegacyApplicationRequirements["files"];
+};
+/** Fresh offers only. Never change the original declaration or a retained grant. */
+export declare function projectNextAuthorizationGroups(requirements: Requirements, requested: readonly string[]): {
+    groups: NextAuthorizationGroup[];
+    error?: string;
+};
+/** Exact projection: no dropping or rounding of stored/approved permissions.
+ * Setup is an independent complete pair, not structural administration. This
+ * projects ordinary policy groups only; it does not authenticate a declaration
+ * or grant authority to execute setup. Producers must verify the original
+ * signed declaration/authorization before mediating either setup operation.
+ */
+export declare function exactNextPermissionCapabilities(operations: readonly string[], files: readonly string[]): ApplicationCapabilityId[] | undefined;
+export {};

package/dist/next-authorization.js

@@ -0,0 +1,90 @@
+import { APPLICATION_CAPABILITY_DEFINITIONS, APPLICATION_CAPABILITY_V1_DEFINITIONS, APPLICATION_SETUP_OPERATIONS } from "./capabilities.js";
+/** Exact record/file pairs used by both consent and next policy publication. */
+export const NEXT_CAPABILITY_FILE_ACTIONS = {
+    "collection.read": ["list", "read"], "records.create": ["add"],
+    "records.edit": ["replace", "move"], "records.delete": ["delete"]
+};
+const UPDATE_REQUIRED = "This app needs an update before it can connect. Try again after it updates.";
+const refuse = () => ({ groups: [], error: UPDATE_REQUIRED });
+const fileActions = new Set(["list", "read", "add", "replace", "move", "delete"]);
+const equalSet = (left, right) => {
+    const a = new Set(left), b = new Set(right);
+    return a.size === b.size && [...a].every(value => b.has(value));
+};
+/** Fresh offers only. Never change the original declaration or a retained grant. */
+export function projectNextAuthorizationGroups(requirements, requested) {
+    const declaration = requirements.capabilities;
+    if (!declaration || (declaration.contract_version !== 1 && declaration.contract_version !== 2)
+        || !Array.isArray(declaration.required) || (declaration.optional !== undefined && !Array.isArray(declaration.optional)))
+        return refuse();
+    const legacy = declaration.contract_version === 1;
+    if (legacy && requirements.access !== "full_collection")
+        return refuse();
+    const catalog = legacy ? APPLICATION_CAPABILITY_V1_DEFINITIONS : APPLICATION_CAPABILITY_DEFINITIONS;
+    const ids = [...declaration.required, ...(declaration.optional ?? [])];
+    if (ids.some(id => !Object.hasOwn(catalog, id)) || new Set(ids).size !== ids.length)
+        return refuse();
+    const files = requirements.files;
+    if (files && (legacy
+        ? !("actions" in files) || "required" in files || "optional" in files || !Array.isArray(files.actions)
+        : !("required" in files) || "actions" in files || !Array.isArray(files.required)
+            || (files.optional !== undefined && !Array.isArray(files.optional))))
+        return refuse();
+    const requiredFiles = files ? "actions" in files ? files.actions : files.required : [];
+    const declaredFiles = files ? "actions" in files ? files.actions : [...files.required, ...(files.optional ?? [])] : [];
+    if (declaredFiles.some(action => !fileActions.has(action)) || new Set(declaredFiles).size !== declaredFiles.length)
+        return refuse();
+    const requestedSet = new Set(requested);
+    const expansions = catalog;
+    const requiredOperations = new Set(declaration.required.flatMap(id => expansions[id] ?? []));
+    if (legacy) {
+        const allowed = new Set(ids.flatMap(id => expansions[id] ?? []));
+        if (requested.some(operation => !allowed.has(operation)))
+            return refuse();
+        // A required file capability cannot disappear just because its operation
+        // expansion is empty in the predecessor catalog.
+        if (declaration.required.some(id => id.startsWith("files.") && !declaredFiles.includes(id.slice(6))))
+            return refuse();
+    }
+    const candidates = legacy ? Object.keys(APPLICATION_CAPABILITY_DEFINITIONS) : ids;
+    const groups = [];
+    for (const id of candidates) {
+        const operations = [...APPLICATION_CAPABILITY_DEFINITIONS[id]];
+        const pairedFiles = NEXT_CAPABILITY_FILE_ACTIONS[id] ?? [];
+        const required = operations.some(operation => requiredOperations.has(operation)) || pairedFiles.some(action => requiredFiles.includes(action));
+        if (id === "offline.replica" || !operations.every(operation => requestedSet.has(operation))
+            || !pairedFiles.every(action => declaredFiles.includes(action))) {
+            if (required)
+                return refuse();
+            continue;
+        }
+        if (legacy && id === "definitions.manage" && APPLICATION_SETUP_OPERATIONS.every(operation => requestedSet.has(operation)))
+            operations.push(...APPLICATION_SETUP_OPERATIONS);
+        groups.push({ id, operations, fileActions: pairedFiles, required });
+    }
+    const covered = new Set(groups.flatMap(group => group.operations));
+    if ([...requiredOperations].some(operation => !covered.has(operation))
+        || requiredFiles.some(action => !groups.some(group => group.fileActions.includes(action))) || groups.length === 0)
+        return refuse();
+    return { groups };
+}
+/** Exact projection: no dropping or rounding of stored/approved permissions.
+ * Setup is an independent complete pair, not structural administration. This
+ * projects ordinary policy groups only; it does not authenticate a declaration
+ * or grant authority to execute setup. Producers must verify the original
+ * signed declaration/authorization before mediating either setup operation.
+ */
+export function exactNextPermissionCapabilities(operations, files) {
+    const groups = Object.keys(APPLICATION_CAPABILITY_DEFINITIONS).filter(id => id !== "offline.replica" && APPLICATION_CAPABILITY_DEFINITIONS[id].every(operation => operations.includes(operation)));
+    const expected = groups.flatMap(id => [...APPLICATION_CAPABILITY_DEFINITIONS[id]]);
+    const setup = APPLICATION_SETUP_OPERATIONS.filter(operation => operations.includes(operation));
+    if (setup.length) {
+        if (setup.length !== APPLICATION_SETUP_OPERATIONS.length)
+            return undefined;
+        expected.push(...setup);
+    }
+    if (!groups.length || !equalSet(expected, operations)
+        || !equalSet(groups.flatMap(id => [...(NEXT_CAPABILITY_FILE_ACTIONS[id] ?? [])]), files))
+        return undefined;
+    return groups.sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect-protocol",
-  "version": "0.1.0-beta.126",
+  "version": "0.1.0-beta.148",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,10 @@
       "types": "./dist/manifest.d.ts",
       "import": "./dist/manifest.js"
     },
+    "./next-authorization": {
+      "types": "./dist/next-authorization.d.ts",
+      "import": "./dist/next-authorization.js"
+    },
     "./schemas/*": "./schemas/*"
   },
   "files": [
@@ -27,17 +31,19 @@
     "schemas"
   ],
   "dependencies": {
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1",
+    "@noble/hashes": "2.4.0",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "esbuild": "^0.28.1",
     "typescript": "^7.0.2"
   },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
-    "test": "node --test test/*.test.mjs && node ../../scripts/generate-change-events.mjs --check && node ../../scripts/generate-connect-problems.mjs --check && node ../../scripts/generate-operation-catalog.mjs --check && node ../../scripts/generate-application-capabilities.mjs --check",
+    "test": "node --test test/*.test.mjs && node ../../scripts/generate-manifest-validators.mjs --check && node ../../scripts/generate-change-events.mjs --check && node ../../scripts/generate-connect-problems.mjs --check && node ../../scripts/generate-operation-catalog.mjs --check && node ../../scripts/generate-application-capabilities.mjs --check",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }