@fabricorg/sdui-release 0.3.0 → 0.6.0

package/dist/index.js

@@ -1,3 +1,14 @@
+import {
+  RELEASE_CHANNEL_POINTER_FORMAT_VERSION,
+  SDUI_RELEASE_V3_FORMAT_VERSION,
+  activateReleaseChannelPointer,
+  assertReleaseChannelPointer,
+  assertSduiReleaseV3,
+  canonicalizeJcs,
+  verifySignedExperienceArtifact,
+  verifySignedExperienceRelease
+} from "./chunk-BTWHVBZ3.js";
+
 // types.ts
 var SDUI_DOCUMENT_FORMAT_VERSION = 1;
 var SDUI_TOKEN_SET_FORMAT_VERSION = 1;
@@ -24,8 +35,9 @@ function requireArray(value, path) {
   if (!Array.isArray(value)) fail(path, "must be an array");
   return value;
 }
+var CAPABILITY_REF = /^capability:\/\/([a-z][a-z0-9-]*)\/([a-z][a-z0-9._-]*(?:\/[a-z0-9._-]+)*)$/;
 function parseCapabilityRef(ref) {
-  const match = /^capability:\/\/([a-z][a-z0-9-]*)\/(.+)$/.exec(ref);
+  const match = CAPABILITY_REF.exec(ref);
   if (!match) return void 0;
   return { namespace: match[1], name: match[2] };
 }
@@ -160,8 +172,20 @@ function assertSduiDocument(value, path = "document") {
     });
   }
   const tokenSet = requireRecord(document.tokenSet, `${path}.tokenSet`);
-  requireString(tokenSet.name, `${path}.tokenSet.name`);
-  requireString(tokenSet.version, `${path}.tokenSet.version`);
+  assertTokenSetReference(tokenSet, `${path}.tokenSet`);
+  if (document.supportedTokenSets !== void 0) {
+    const seenTokenSets = /* @__PURE__ */ new Set();
+    requireArray(document.supportedTokenSets, `${path}.supportedTokenSets`).forEach((entry, index) => {
+      const supportedPath = `${path}.supportedTokenSets[${index}]`;
+      const supported = requireRecord(entry, supportedPath);
+      assertTokenSetReference(supported, supportedPath);
+      const identity = `${String(supported.name)}\0${String(supported.version)}`;
+      if (seenTokenSets.has(identity)) {
+        fail(supportedPath, `declares token set "${String(supported.name)}@${String(supported.version)}" a second time`);
+      }
+      seenTokenSets.add(identity);
+    });
+  }
   requireArray(document.componentPacks, `${path}.componentPacks`).forEach((entry, index) => {
     const pack = requireRecord(entry, `${path}.componentPacks[${index}]`);
     requireString(pack.pack, `${path}.componentPacks[${index}].pack`);
@@ -241,6 +265,14 @@ function assertSduiRelease(value, path = "release") {
     }
   });
 }
+function assertTokenSetReference(reference, path) {
+  if (!/^[a-z][a-z0-9-]*$/.test(requireString(reference.name, `${path}.name`))) {
+    fail(`${path}.name`, "must be lowercase letters, numbers and hyphens");
+  }
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(requireString(reference.version, `${path}.version`))) {
+    fail(`${path}.version`, "must be a semver version");
+  }
+}
 
 // validate.ts
 import {
@@ -293,6 +325,16 @@ function releaseDigest(document, tokenSet, componentPacks, grants, assemblyDiges
         variants: [...document.variants].sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
       } : {},
       tokenSet: document.tokenSet,
+      // Which brands a document may be promoted against is part of what was
+      // authored. Sorted, and omitted when absent so a document declaring
+      // none digests exactly as it did before the field existed.
+      ...document.supportedTokenSets?.length ? {
+        supportedTokenSets: [...document.supportedTokenSets].sort((left, right) => {
+          if (left.name !== right.name) return left.name < right.name ? -1 : 1;
+          if (left.version !== right.version) return left.version < right.version ? -1 : 1;
+          return 0;
+        })
+      } : {},
       componentPacks: [...document.componentPacks].sort((a, b) => {
         const key = (e) => `${e.namespace}/${e.pack}`;
         return key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0;
@@ -342,19 +384,56 @@ function buildKnownViews(contracts) {
   const views = /* @__PURE__ */ new Set();
   for (const contract of contracts) {
     for (const view of contract.views) {
-      const name = view.name.startsWith(`${contract.namespace}/`) ? view.name.slice(contract.namespace.length + 1) : view.name;
-      views.add(`${contract.namespace}/${name}`);
+      views.add(`${contract.namespace}/${shortViewName(view.name, contract.namespace)}`);
     }
   }
   return views;
 }
-function buildKnownActionIntents(contracts) {
+function shortViewName(name, namespace) {
+  return name.startsWith(`${namespace}/`) ? name.slice(namespace.length + 1) : name;
+}
+function reportAmbiguousGrantedViews(contracts, grantedViews, add) {
+  const occurrences = /* @__PURE__ */ new Map();
+  for (const contract of contracts) {
+    for (const view of contract.views) {
+      const reference = `capability://${contract.namespace}/${shortViewName(view.name, contract.namespace)}`;
+      if (!grantedViews.has(reference)) continue;
+      occurrences.set(reference, [...occurrences.get(reference) ?? [], `${view.name}@${view.version}`]);
+    }
+  }
+  for (const [reference, declarations] of occurrences) {
+    if (declarations.length > 1) {
+      add(
+        "ambiguous_capability_reference",
+        `grants.views.${reference}`,
+        `"${reference}" is granted but addresses ${declarations.length} views (${declarations.join(", ")}); a versionless reference cannot pick one`
+      );
+    }
+  }
+}
+function buildKnownActionIntents(contracts, add, grantedIntents) {
   const intents = /* @__PURE__ */ new Set();
+  const occurrences = /* @__PURE__ */ new Map();
   for (const contract of contracts) {
     const experience = contract.extensions?.["fabric.experience/v1"];
+    const declaredActions = new Set(contract.actions.map((action) => action.actionId));
     for (const intent of experience?.actionIntents ?? []) {
-      const shortName = intent.name.startsWith(`${contract.namespace}.`) ? intent.name.slice(contract.namespace.length + 1) : intent.name;
-      intents.add(`${contract.namespace}/${shortName}`);
+      if (!declaredActions.has(intent.actionId)) continue;
+      const shortName2 = intent.name.startsWith(`${contract.namespace}.`) ? intent.name.slice(contract.namespace.length + 1) : intent.name;
+      const reference = `${contract.namespace}/${shortName2}`;
+      if (grantedIntents === void 0 || grantedIntents.has(`capability://${reference}`)) {
+        occurrences.set(reference, [...occurrences.get(reference) ?? [], intent.name]);
+      }
+      intents.add(reference);
+    }
+  }
+  for (const [reference, declarations] of occurrences) {
+    if (declarations.length > 1) {
+      add?.(
+        "ambiguous_capability_reference",
+        `contracts.actionIntents.${reference}`,
+        `"capability://${reference}" is declared ${declarations.length} times (${declarations.join(", ")}), so a route for it cannot be resolved`
+      );
     }
   }
   return intents;
@@ -548,18 +627,13 @@ function validateSduiRelease(input) {
   const add = (code, path, message) => {
     findings.push({ code, path, message });
   };
-  if (input.document.tokenSet.name !== input.tokenSet.name) {
+  const promotableTokenSets = [input.document.tokenSet, ...input.document.supportedTokenSets ?? []];
+  const promotedAgainst = promotableTokenSets.some((candidate) => candidate.name === input.tokenSet.name && candidate.version === input.tokenSet.version);
+  if (!promotedAgainst) {
     add(
       "missing_token_set",
-      "document.tokenSet.name",
-      `document references token set "${input.document.tokenSet.name}" but the provided set is "${input.tokenSet.name}"`
-    );
-  }
-  if (input.document.tokenSet.version !== input.tokenSet.version) {
-    add(
-      "missing_token_set",
-      "document.tokenSet.version",
-      `document references token set version "${input.document.tokenSet.version}" but the provided set is version "${input.tokenSet.version}"`
+      "document.tokenSet",
+      `document supports token sets [${promotableTokenSets.map((set) => `${set.name}@${set.version}`).join(", ")}] but the provided set is "${input.tokenSet.name}@${input.tokenSet.version}"`
     );
   }
   const packsByKey = /* @__PURE__ */ new Map();
@@ -675,9 +749,43 @@ function validateSduiRelease(input) {
   }
   const coreComponents = new Set(input.coreComponents ?? []);
   const knownViews = buildKnownViews(contracts);
-  const knownIntents = buildKnownActionIntents(contracts);
   const grantedViews = buildGrantedReferences(input.grants.views, "grants.views");
   const grantedIntents = buildGrantedReferences(input.grants.intents, "grants.intents");
+  const contractNamespaces = /* @__PURE__ */ new Set();
+  const distinctContracts = contracts.filter((contract) => {
+    if (contractNamespaces.has(contract.namespace)) {
+      add(
+        "ambiguous_capability_reference",
+        `contracts.${contract.namespace}`,
+        `contract for "${contract.namespace}" is supplied more than once`
+      );
+      return false;
+    }
+    contractNamespaces.add(contract.namespace);
+    return true;
+  });
+  const knownIntents = buildKnownActionIntents(distinctContracts, add, grantedIntents);
+  reportAmbiguousGrantedViews(distinctContracts, grantedViews, add);
+  for (const reference of grantedViews) {
+    const parsed = parseCapabilityRef(reference);
+    if (parsed && !knownViews.has(`${parsed.namespace}/${parsed.name}`)) {
+      add(
+        "unauthorized_data_ref",
+        `grants.views.${reference}`,
+        `release grants "${reference}", which no supplied capability publishes; promotion would fail to route it`
+      );
+    }
+  }
+  for (const reference of grantedIntents) {
+    const parsed = parseCapabilityRef(reference);
+    if (parsed && !knownIntents.has(`${parsed.namespace}/${parsed.name}`)) {
+      add(
+        "mutation_bypass",
+        `grants.intents.${reference}`,
+        `release grants "${reference}", which no supplied capability declares as an intent; promotion would fail to route it`
+      );
+    }
+  }
   validateIntentActionDeclarations(contracts, add);
   const fragmentGrants = /* @__PURE__ */ new Map();
   for (const [fragmentId, declared] of Object.entries(input.grants.fragments ?? {})) {
@@ -802,6 +910,221 @@ function collectCoreComponents(fragment) {
   }
   return used;
 }
+async function refusalReason(run, expect) {
+  try {
+    await run();
+    return null;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return expect.test(message) ? message : null;
+  }
+}
+function sduiChannelChecks() {
+  return [
+    {
+      id: "fabric.sdui-channel.verified-release.v1",
+      async run(subject) {
+        assertSduiReleaseIntegrity(subject.validRelease);
+        const result = subject.channel.consume(subject.validRelease);
+        if (result.release.releaseDigest !== subject.validRelease.releaseDigest) {
+          throw new Error("channel returned a release other than the one it was given");
+        }
+        return [subject.validRelease.releaseDigest];
+      }
+    },
+    {
+      id: "fabric.sdui-channel.tampered-release-denial.v1",
+      async run(subject) {
+        const tampered = {
+          ...subject.validRelease,
+          document: { ...subject.validRelease.document, name: `${subject.validRelease.document.name}-tampered` }
+        };
+        const reason = await refusalReason(() => subject.channel.consume(tampered), /digest|integrity/i);
+        if (reason === null) {
+          throw new Error("channel did not refuse a release whose content no longer matches its digest, citing the digest");
+        }
+        for (const [label, mutate] of [
+          ["version", (release) => ({ ...release, document: { ...release.document, version: "9.9.9" } })],
+          ["grants", (release) => ({ ...release, grants: { ...release.grants, views: [...release.grants.views, "capability://smuggled/view"] } })],
+          ["assembly", (release) => ({ ...release, assemblyDigest: "f".repeat(64) })]
+        ]) {
+          const edited = mutate(subject.validRelease);
+          if (await refusalReason(() => subject.channel.consume(edited), /digest|integrity/i) === null) {
+            throw new Error(`channel accepted a release whose ${label} was edited after promotion`);
+          }
+        }
+        return ["tampered document refused", "edited version, grants and assembly refused"];
+      }
+    },
+    {
+      id: "fabric.sdui-channel.unpromoted-document-denial.v1",
+      async run(subject) {
+        const expected = /digest|integrity|release|formatVersion|must be/i;
+        const unpromoted = { document: subject.validRelease.document };
+        if (await refusalReason(() => subject.channel.consume(unpromoted), expected) === null) {
+          throw new Error("channel did not refuse a bare document that was never promoted, citing what was wrong with it");
+        }
+        const digestless = { ...subject.validRelease, releaseDigest: void 0 };
+        if (await refusalReason(() => subject.channel.consume(digestless), expected) === null) {
+          throw new Error("channel did not refuse a release carrying no digest, citing what was wrong with it");
+        }
+        return ["bare document refused", "digestless release refused"];
+      }
+    },
+    {
+      id: "fabric.sdui-channel.reports-missing-vocabulary.v1",
+      async run(subject) {
+        const used = collectCoreComponents(subject.validRelease.document.root);
+        for (const variant of subject.validRelease.document.variants ?? []) {
+          for (const component of collectCoreComponents(variant.root)) used.add(component);
+        }
+        if (!used.has(subject.unimplementedCoreComponent)) {
+          throw new Error(
+            `conformance subject is vacuous: validRelease never uses "${subject.unimplementedCoreComponent}", so the channel is never asked to report it`
+          );
+        }
+        if (subject.channel.coreComponents.includes(subject.unimplementedCoreComponent)) {
+          throw new Error(
+            `conformance subject is contradictory: the channel implements "${subject.unimplementedCoreComponent}"`
+          );
+        }
+        const result = subject.channel.consume(subject.validRelease);
+        if (result.compatible) {
+          throw new Error("channel reported compatible for a release using a component it does not implement");
+        }
+        if (!result.missingCoreComponents.includes(subject.unimplementedCoreComponent)) {
+          throw new Error("channel reported incompatible without naming the component it cannot render");
+        }
+        return [`missing: ${result.missingCoreComponents.join(", ")}`];
+      }
+    },
+    {
+      id: "fabric.sdui-channel.consumption-is-pure.v1",
+      async run(subject) {
+        const before = JSON.stringify(subject.validRelease);
+        subject.channel.consume(subject.validRelease);
+        subject.channel.consume(subject.validRelease);
+        if (JSON.stringify(subject.validRelease) !== before) {
+          throw new Error("channel mutated the release it consumed");
+        }
+        return ["release unchanged after two consumptions"];
+      }
+    }
+  ];
+}
+async function runSduiChannelChecks(subject) {
+  const checks = [];
+  for (const check of sduiChannelChecks()) {
+    try {
+      checks.push({ id: check.id, status: "passed", evidence: await check.run(subject) });
+    } catch (error) {
+      checks.push({
+        id: check.id,
+        status: "failed",
+        evidence: [],
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return { passed: checks.every((check) => check.status === "passed"), checks };
+}
+
+// references.ts
+function collectDocumentReferences(document) {
+  const views = /* @__PURE__ */ new Set();
+  const intents = /* @__PURE__ */ new Set();
+  const trees = [document.root, ...(document.variants ?? []).map((variant) => variant.root)];
+  for (const tree of trees) walk(tree, views, intents);
+  return { views, intents };
+}
+function walk(fragment, views, intents) {
+  if (fragment.dataRef) views.add(fragment.dataRef);
+  for (const action of Object.values(fragment.actions ?? {})) {
+    intents.add(action.intent);
+    if (action.params) collectValues(action.params, views);
+  }
+  if (fragment.props) collectValues(fragment.props, views);
+  for (const child of fragment.children ?? []) walk(child, views, intents);
+}
+function collectValues(props, views) {
+  for (const value of Object.values(props)) collectValue(value, views);
+}
+function collectValue(value, views) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && "$ref" in value) {
+    views.add(value.$ref);
+    for (const [key, sibling] of Object.entries(value)) {
+      if (key !== "$ref") collectValue(sibling, views);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectValue(item, views);
+    return;
+  }
+  if (value !== null && typeof value === "object") collectValues(value, views);
+}
+
+// entitlements.ts
+function deriveAuthorizationGrants(contracts, held, options = {}) {
+  const undeclared = options.undeclaredRequirements ?? "withhold";
+  const bound = options.document ? collectDocumentReferences(options.document) : void 0;
+  const permissions = new Set(held.permissions ?? []);
+  const entitlements = new Set(held.entitlements ?? []);
+  const featureFlags = new Set(held.featureFlags ?? []);
+  const views = [];
+  const intents = [];
+  const withheld = [];
+  for (const contract of contracts) {
+    if (undeclared === "withhold" && !declaresAnyRequirement(contract)) {
+      withheld.push({ namespace: contract.namespace, missing: { kind: "permission", name: "(none declared)" } });
+      continue;
+    }
+    const missing = firstMissingRequirement(contract, { permissions, entitlements, featureFlags });
+    if (missing) {
+      withheld.push({ namespace: contract.namespace, missing });
+      continue;
+    }
+    for (const view of contract.views) {
+      const reference = `capability://${contract.namespace}/${shortName(view.name, contract.namespace, "/")}`;
+      if (!bound || bound.views.has(reference)) views.push(reference);
+    }
+    for (const intent of actionIntentsOf(contract)) {
+      const reference = `capability://${contract.namespace}/${shortName(intent.name, contract.namespace, ".")}`;
+      if (!bound || bound.intents.has(reference)) intents.push(reference);
+    }
+  }
+  return {
+    grants: { views: [...new Set(views)].sort(), intents: [...new Set(intents)].sort() },
+    withheld: withheld.sort((left, right) => left.namespace < right.namespace ? -1 : left.namespace > right.namespace ? 1 : 0)
+  };
+}
+function declaresAnyRequirement(contract) {
+  const requirements = contract.requirements;
+  return Boolean(
+    requirements && ((requirements.permissions?.length ?? 0) > 0 || (requirements.entitlements?.length ?? 0) > 0 || (requirements.featureFlags?.length ?? 0) > 0)
+  );
+}
+function firstMissingRequirement(contract, held) {
+  const requirements = contract.requirements;
+  for (const name of requirements?.permissions ?? []) {
+    if (!held.permissions.has(name)) return { kind: "permission", name };
+  }
+  for (const name of requirements?.entitlements ?? []) {
+    if (!held.entitlements.has(name)) return { kind: "entitlement", name };
+  }
+  for (const name of requirements?.featureFlags ?? []) {
+    if (!held.featureFlags.has(name)) return { kind: "featureFlag", name };
+  }
+  return void 0;
+}
+function actionIntentsOf(contract) {
+  const experience = contract.extensions?.["fabric.experience/v1"];
+  return experience?.actionIntents ?? [];
+}
+function shortName(name, namespace, separator) {
+  const prefix = `${namespace}${separator}`;
+  return name.startsWith(prefix) ? name.slice(prefix.length) : name;
+}
 
 // schemas.ts
 var SDUI_DOCUMENT_JSON_SCHEMA = {
@@ -834,22 +1157,34 @@ var SDUI_RELEASE_JSON_SCHEMA = {
   }
 };
 export {
+  RELEASE_CHANNEL_POINTER_FORMAT_VERSION,
   SDUI_COMPONENT_PACK_FORMAT_VERSION,
   SDUI_DOCUMENT_FORMAT_VERSION,
   SDUI_DOCUMENT_JSON_SCHEMA,
   SDUI_RELEASE_FORMAT_VERSION,
   SDUI_RELEASE_JSON_SCHEMA,
+  SDUI_RELEASE_V3_FORMAT_VERSION,
   SDUI_TOKEN_SET_FORMAT_VERSION,
+  activateReleaseChannelPointer,
+  assertReleaseChannelPointer,
   assertSduiAuthorizationGrants,
   assertSduiComponentPack,
   assertSduiDocument,
   assertSduiFragment,
   assertSduiRelease,
   assertSduiReleaseIntegrity,
+  assertSduiReleaseV3,
   assertSduiReleaseValid,
   assertSduiTokenSet,
+  canonicalizeJcs,
   computeReleaseDigest,
   createSduiChannel,
-  validateSduiRelease
+  deriveAuthorizationGrants,
+  parseCapabilityRef,
+  runSduiChannelChecks,
+  sduiChannelChecks,
+  validateSduiRelease,
+  verifySignedExperienceArtifact,
+  verifySignedExperienceRelease
 };
 //# sourceMappingURL=index.js.map