@fabricorg/assembly 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @fabricorg/assembly
 
+## 0.4.1
+
+### Patch Changes
+
+- 715e920: The adapter plane. An assembly manifest may declare `adapters`, each structurally the output of `certifyAdapter`, and resolution judges every port a contract requires by the deployment gate's own rule through `validatePortRequirements` with certification required: `unsatisfied_port`, `uncertified_adapter`, `standard_not_spoken`, `version_mismatch`, and, when `portDefinitions` are supplied, `stale_certification`. The lockfile records each certified adapter with the port version it was certified against and a digest of the certification, and the assembly digest covers them. Declaring `adapters`, even empty, engages the plane; an assembly that does not declare it resolves exactly as before, digest included. Every declared adapter is recorded in the lockfile with `certified` true or false, `portDefinitions` are validated before use, and `assertAssemblyRuntimeCompatible` accepts the runtime's registered adapters and refuses any drift from the approved list. Disclosed: this adds `@fabricorg/ports` as a runtime dependency and several exported types and one function; it is released as a patch because a minor on this 0.x package would cascade a major onto every peer, and nothing existing changes behaviour.
+- Updated dependencies [764b94b]
+  - @fabricorg/ports@0.5.4
+
+## 0.4.0
+
+### Minor Changes
+
+- 274d948: Close the gaps a second independent review found.
+
+  Experience promotion now binds the usage contracts it compiles routes from to the assembly the
+  release was validated against. Promotion previously accepted arbitrary contracts while copying the
+  release's assembly digest through unchanged, so a substituted contract could remap an already-granted
+  `capability://` reference onto a different installed action. PlatformHost still authorized that
+  action, which made this an integrity failure of what a release exposes rather than an authorization
+  bypass, and invisible downstream. `@fabricorg/assembly` exports `computeAssemblyLockfileDigest` so
+  tooling can build a self-consistent lockfile; the validator already recomputed it.
+
+  The MFE loader gains `fabric.mfe-loader.mismatched-digest-denial.v1`, which supplies a well-formed
+  integrity value that cannot match the approved bundle. The previous integrity check supplied only a
+  malformed value, so it proved a regex ran; a transport that ignored integrity entirely certified
+  clean. Since same-realm MFE code carries the application's own authority, a false integrity
+  certification is worth catching in the suite rather than in production.
+
+  The SDUI channel suite no longer certifies a channel it never exercised: the missing-vocabulary check
+  now runs against the subject rather than a fresh built-in one, rejects a vacuous or contradictory
+  subject instead of passing it, requires a refusal to name the digest so an unrelated crash cannot
+  read as correct behaviour, and edits several digest-covered fields so a channel cannot pass by
+  special-casing one fixture. `supportedTokenSets` uses a total comparator over its fields rather than
+  an interpolated key, and duplicate or malformed token-set references are rejected.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -68,3 +68,15 @@ const lockfile = assertAssemblyResolved({
 It does not load live modules, execute handlers, or run inside
 `@fabricorg/platform`. The assembly package depends on `@fabricorg/adoption-bindings`
 and `@fabricorg/gen-capability` for contract and binding validation.
+
+## The adapter plane
+
+An assembly manifest may declare `adapters`, each the output of `certifyAdapter`. Declaring the
+field, even empty, engages the plane: every port a contract requires must be satisfied by a declared,
+certified adapter, judged by `validatePortRequirements` with certification required, and a
+certification against an older port contract is stale when `portDefinitions` are supplied. The
+lockfile records every declared adapter, certified or not, and the assembly digest covers them.
+`assertAssemblyRuntimeCompatible(lockfile, capabilities, registeredAdapters)` then checks that what a
+runtime registered behind each port is what the assembly approved. An assembly that does not declare
+`adapters` resolves exactly as before.
+

package/dist/index.cjs

@@ -27,6 +27,8 @@ __export(index_exports, {
   assertAssemblyResolved: () => assertAssemblyResolved,
   assertAssemblyRuntimeCompatible: () => assertAssemblyRuntimeCompatible,
   assertComponentPackManifest: () => assertComponentPackManifest,
+  computeAdapterCertificationDigest: () => computeAdapterCertificationDigest,
+  computeAssemblyLockfileDigest: () => computeAssemblyLockfileDigest,
   computeUsageContractDocumentDigest: () => computeUsageContractDocumentDigest,
   parseSemverRange: () => parseSemverRange,
   resolveAssembly: () => resolveAssembly,
@@ -36,6 +38,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto = require("crypto");
+var import_ports = require("@fabricorg/ports");
 var import_adoption_bindings = require("@fabricorg/adoption-bindings");
 var import_gen_capability = require("@fabricorg/gen-capability");
 var ASSEMBLY_MANIFEST_FORMAT_VERSION = 2;
@@ -224,15 +227,24 @@ function computeUsageContractDocumentDigest(document) {
   (0, import_gen_capability.assertUsageContractDocument)(document);
   return assemblyDigest(document);
 }
+function computeAssemblyLockfileDigest(lockfile) {
+  return assemblyDigest(lockfileDigestBody(lockfile));
+}
 function lockfileDigestBody(lockfile) {
   return {
     formatVersion: lockfile.formatVersion,
     application: lockfile.application,
     capabilities: lockfile.capabilities,
     componentPacks: lockfile.componentPacks,
-    bindings: lockfile.bindings
+    bindings: lockfile.bindings,
+    // Omitted when absent, so a lockfile from before the adapter plane
+    // keeps the digest it was approved with.
+    ...lockfile.adapters ? { adapters: lockfile.adapters } : {}
   };
 }
+function computeAdapterCertificationDigest(certification) {
+  return assemblyDigest({ ...certification, checks: [...certification.checks].sort() });
+}
 function fail(path, message) {
   throw new Error(`Assembly manifest ${path} ${message}.`);
 }
@@ -278,6 +290,42 @@ function assertAssemblyManifest(value, path = "assembly") {
       fail(`${path}.contracts[${index}].document`, error instanceof Error ? error.message : String(error));
     }
   });
+  if (manifest.adapters !== void 0) {
+    requireArray(manifest.adapters, `${path}.adapters`).forEach((entry, index) => {
+      assertAdapterEntry(entry, `${path}.adapters[${index}]`);
+    });
+  }
+}
+function assertAdapterEntry(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "must be an object");
+  const adapter = value;
+  requireString(adapter.port, `${path}.port`);
+  requireString(adapter.vendor, `${path}.vendor`);
+  if (adapter.version !== void 0) requireString(adapter.version, `${path}.version`);
+  if (adapter.standard !== void 0) {
+    const standard = adapter.standard;
+    if (!standard || typeof standard !== "object" || Array.isArray(standard)) fail(`${path}.standard`, "must be an object");
+    requireString(standard.name, `${path}.standard.name`);
+    if (standard.version !== void 0) requireString(standard.version, `${path}.standard.version`);
+  }
+  if (adapter.certification !== void 0) {
+    const certification = adapter.certification;
+    if (!certification || typeof certification !== "object" || Array.isArray(certification)) fail(`${path}.certification`, "must be an object");
+    requireString(certification.portId, `${path}.certification.portId`);
+    if (!/^\d+\.\d+\.\d+$/.test(requireString(certification.portVersion, `${path}.certification.portVersion`))) {
+      fail(`${path}.certification.portVersion`, "must be a semver version");
+    }
+    const checks = requireArray(certification.checks, `${path}.certification.checks`);
+    if (checks.length === 0 || !checks.every((check) => typeof check === "string" && check.trim())) {
+      fail(`${path}.certification.checks`, "must name at least one check");
+    }
+    if (Number.isNaN(Date.parse(requireString(certification.certifiedAt, `${path}.certification.certifiedAt`)))) {
+      fail(`${path}.certification.certifiedAt`, "must be an instant");
+    }
+    if (certification.portId !== adapter.port) {
+      fail(`${path}.certification.portId`, `must match the adapter's port "${String(adapter.port)}"`);
+    }
+  }
 }
 function assertComponentPackManifest(value, path = "pack") {
   if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "must be an object");
@@ -369,19 +417,77 @@ function assertAssemblyLockfile(value, path = "lockfile") {
     if (binding?.valid !== true) fail(`${path}.bindings[${index}].valid`, "must be true");
     requireArray(binding?.findings, `${path}.bindings[${index}].findings`);
   }
+  let adapters;
+  if (lockfile.adapters !== void 0) {
+    adapters = requireArray(lockfile.adapters, `${path}.adapters`);
+    const seen = /* @__PURE__ */ new Set();
+    for (const [index, entry] of adapters.entries()) {
+      const adapter = entry;
+      const port = requireString(adapter?.port, `${path}.adapters[${index}].port`);
+      const vendor = requireString(adapter?.vendor, `${path}.adapters[${index}].vendor`);
+      const key = `${port}/${vendor}`;
+      if (seen.has(key)) fail(`${path}.adapters[${index}]`, `declares adapter "${key}" a second time`);
+      seen.add(key);
+      if (adapter?.version !== void 0) requireString(adapter.version, `${path}.adapters[${index}].version`);
+      if (adapter?.standard !== void 0) {
+        const standard = adapter.standard;
+        if (!standard || typeof standard !== "object" || Array.isArray(standard)) fail(`${path}.adapters[${index}].standard`, "must be an object");
+        requireString(standard.name, `${path}.adapters[${index}].standard.name`);
+        if (standard.version !== void 0) requireString(standard.version, `${path}.adapters[${index}].standard.version`);
+      }
+      if (typeof adapter?.certified !== "boolean") fail(`${path}.adapters[${index}].certified`, "must be a boolean");
+      if (adapter.certified) {
+        if (!/^\d+\.\d+\.\d+$/.test(requireString(adapter?.portVersion, `${path}.adapters[${index}].portVersion`))) {
+          fail(`${path}.adapters[${index}].portVersion`, "must be a semver version");
+        }
+        if (Number.isNaN(Date.parse(requireString(adapter?.certifiedAt, `${path}.adapters[${index}].certifiedAt`)))) {
+          fail(`${path}.adapters[${index}].certifiedAt`, "must be an instant");
+        }
+        if (!/^[0-9a-f]{64}$/.test(requireString(adapter?.certificationDigest, `${path}.adapters[${index}].certificationDigest`))) {
+          fail(`${path}.adapters[${index}].certificationDigest`, "must be a lowercase SHA-256 digest");
+        }
+      } else if (adapter.portVersion !== void 0 || adapter.certifiedAt !== void 0 || adapter.certificationDigest !== void 0) {
+        fail(`${path}.adapters[${index}]`, "carries certification fields but is marked uncertified");
+      }
+    }
+  }
   const expected = assemblyDigest(lockfileDigestBody({
     formatVersion: ASSEMBLY_LOCKFILE_FORMAT_VERSION,
     application: lockfile.application,
     capabilities,
     componentPacks,
-    bindings
+    bindings,
+    ...adapters ? { adapters } : {}
   }));
   if (lockfile.assemblyDigest !== expected) {
     fail(`${path}.assemblyDigest`, `does not match resolved lockfile content; expected "${expected}"`);
   }
 }
-function assertAssemblyRuntimeCompatible(lockfile, loadedCapabilities) {
+function assertAssemblyRuntimeCompatible(lockfile, loadedCapabilities, registeredAdapters) {
   assertAssemblyLockfile(lockfile);
+  if (lockfile.adapters !== void 0 && registeredAdapters !== void 0) {
+    const registeredByKey = new Map(registeredAdapters.map((adapter) => [`${adapter.port}/${adapter.vendor}`, adapter]));
+    for (const approved of lockfile.adapters) {
+      const key = `${approved.port}/${approved.vendor}`;
+      const registered = registeredByKey.get(key);
+      if (!registered) throw new Error(`Approved adapter "${key}" is not registered by this runtime.`);
+      if (approved.version !== void 0 && registered.version !== approved.version) {
+        throw new Error(`Registered adapter "${key}" is version "${registered.version ?? "unversioned"}"; the assembly approved "${approved.version}".`);
+      }
+      if (approved.certified) {
+        const digest = registered.certification ? computeAdapterCertificationDigest(registered.certification) : void 0;
+        if (digest !== approved.certificationDigest) {
+          throw new Error(`Registered adapter "${key}" does not carry the certification the assembly approved (digest "${approved.certificationDigest}").`);
+        }
+      }
+    }
+    for (const registered of registeredAdapters) {
+      const key = `${registered.port}/${registered.vendor}`;
+      if (!lockfile.adapters.some((approved) => approved.port === registered.port && approved.vendor === registered.vendor)) {
+        throw new Error(`Registered adapter "${key}" is not approved by assembly "${lockfile.assemblyDigest}".`);
+      }
+    }
+  }
   const loadedByNamespace = /* @__PURE__ */ new Map();
   for (const loaded of loadedCapabilities) {
     if (loadedByNamespace.has(loaded.namespace)) {
@@ -586,6 +692,51 @@ function resolveAssembly(input) {
     }
     contractsByNamespace.set(entry.namespace, entry.document.capability);
   }
+  const resolvedAdapters = [];
+  const declaredAdapters = input.manifest.adapters ?? [];
+  const adapterKeys = /* @__PURE__ */ new Set();
+  for (const adapter of declaredAdapters) {
+    const key = `${adapter.port}/${adapter.vendor}`;
+    if (adapterKeys.has(key)) {
+      add("duplicate_adapter", `assembly.adapters.${key}`, `adapter "${key}" is declared a second time`);
+      continue;
+    }
+    adapterKeys.add(key);
+    resolvedAdapters.push({
+      port: adapter.port,
+      vendor: adapter.vendor,
+      ...adapter.version === void 0 ? {} : { version: adapter.version },
+      ...adapter.standard === void 0 ? {} : { standard: adapter.standard },
+      certified: adapter.certification !== void 0,
+      ...adapter.certification === void 0 ? {} : {
+        portVersion: adapter.certification.portVersion,
+        certifiedAt: adapter.certification.certifiedAt,
+        certificationDigest: computeAdapterCertificationDigest(adapter.certification)
+      }
+    });
+  }
+  const portDefinitions = (input.portDefinitions ?? []).map((definition, index) => {
+    if (typeof definition.id !== "string" || !import_ports.PORT_ID.test(definition.id)) {
+      fail(`portDefinitions[${index}].id`, `must be a namespaced lowercase port id, received ${JSON.stringify(definition.id)}`);
+    }
+    if (typeof definition.version !== "string" || !/^\d+\.\d+\.\d+$/.test(definition.version)) {
+      fail(`portDefinitions[${index}].version`, `must be a semver version, received ${JSON.stringify(definition.version)}`);
+    }
+    return { id: definition.id, version: definition.version, description: "", checks: () => [] };
+  });
+  for (const [namespace, capability] of contractsByNamespace) {
+    if (input.manifest.adapters === void 0) break;
+    if (!capability.requirements?.ports?.length) continue;
+    const result = (0, import_ports.validatePortRequirements)({
+      capability: { namespace, requirements: { ports: capability.requirements.ports } },
+      adapters: declaredAdapters,
+      definitions: portDefinitions,
+      requireCertification: true
+    });
+    for (const finding of result.findings) {
+      add(finding.code, `assembly.contracts.${namespace}.requirements.ports.${finding.port}`, finding.message);
+    }
+  }
   const resolvedBindings = [];
   for (const entry of input.manifest.bindings) {
     const contract = contractsByNamespace.get(entry.capability);
@@ -636,12 +787,17 @@ function resolveAssembly(input) {
   const bindings = [...resolvedBindings].sort(
     (a, b) => a.capability < b.capability ? -1 : a.capability > b.capability ? 1 : 0
   );
+  const adapters = input.manifest.adapters === void 0 ? void 0 : [...resolvedAdapters].sort((a, b) => {
+    const key = (e) => `${e.port}/${e.vendor}`;
+    return key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0;
+  });
   const lockfileBody = {
     formatVersion: ASSEMBLY_LOCKFILE_FORMAT_VERSION,
     application: input.manifest.application,
     capabilities,
     componentPacks,
-    bindings
+    bindings,
+    ...adapters ? { adapters } : {}
   };
   const lockfile = {
     formatVersion: ASSEMBLY_LOCKFILE_FORMAT_VERSION,
@@ -649,7 +805,8 @@ function resolveAssembly(input) {
     assemblyDigest: assemblyDigest(lockfileDigestBody(lockfileBody)),
     capabilities,
     componentPacks,
-    bindings
+    bindings,
+    ...adapters ? { adapters } : {}
   };
   return {
     lockfile: findings.length === 0 ? lockfile : void 0,
@@ -725,6 +882,8 @@ function validateAssemblyBindings(input) {
   assertAssemblyResolved,
   assertAssemblyRuntimeCompatible,
   assertComponentPackManifest,
+  computeAdapterCertificationDigest,
+  computeAssemblyLockfileDigest,
   computeUsageContractDocumentDigest,
   parseSemverRange,
   resolveAssembly,